Core (builtin) Options set
These are the core options that make everything else possible.
They include the .apply, .eval, and .wrap functions, and the .wrapper itself
They are always imported with every module evaluation.
They are very minimal by design.
The default symlinkScript value provides no options.
The default wrapperFunction is null.
wlib.modules.default provides great values for these options, and creates many more for you to use.
But you may want to wrap your package via different means, provide different options, or provide modules for others to use to help do those things!
For example:
wlib.modules.makeWrapperNix is a partial reimplementation of wlib.modules.makeWrapper, but without using pkgs.makeWrapper at all!
In doing that, it allows for runtime variable expansion. You could use that instead of wlib.modules.makeWrapper if you wanted to alongside wlib.modules.symlinkScript
Excited to see what ways to use these options everyone comes up with! Docker helpers? BubbleWrap? If it's a derivation, it should be possible!
package
The base package to wrap.
This means config.symlinkScript will be responsible
for inheriting all other files from this package
(like man page, /share, …)
Type: package
apply
Function to extend the current configuration with additional modules. Re-evaluates the configuration with the original settings plus the new module.
Type: function that evaluates to a(n) raw value (read only)
Default:
<function>
binName
The name of the binary output by wrapperFunction.
If not specified, the name of the package will be used.
If set as an empty string, wrapperFunction may behave unpredictably, depending on its implementation.
Type: null or string
Default:
null
eval
Function to extend the current configuration with additional modules. Re-evaluates the configuration with the original settings plus the new module. Returns the raw evaluated module.
Type: function that evaluates to a(n) raw value (read only)
Default:
<function>
extraDrvAttrs
Extra attributes to add to the resulting derivation.
Type: attribute set of raw value
Default:
{ }
meta.maintainers
Maintainers of this wrapper module.
Type: list of (submodule)
Default:
[ ]
meta.maintainers.*.email
Type: null or string
Default:
null
meta.maintainers.*.github
GitHub username
Type: string
meta.maintainers.*.githubId
GitHub id
Type: signed integer
meta.maintainers.*.matrix
Matrix ID
Type: null or string
Default:
null
meta.maintainers.*.name
name
Type: string
Default:
"‹name›"
meta.platforms
Supported platforms
Type: list of string
Default:
[
"... lib.platforms.all ..."
]
Example:
"[ \"x86_64-linux\" \"aarch64-linux\" ]"
outputs
Override the list of nix outputs that get symlinked into the final package.
Type: null or (list of string)
Default:
null
passthru
Additional attributes to add to the resulting derivation’s passthru. This can be used to add additional metadata or functionality to the wrapped package. This will always contain options, config and settings, so these are reserved names and cannot be used here.
Type: attribute set
Default:
{ }
pkgs
The nixpkgs pkgs instance to use.
Required in order to access .wrapper attribute,
either directly, or indirectly.
Type: unspecified value
sourceStdenv
Whether to call $stdenv/setup to set up the environment before the symlinkScript
If any phases are enabled, also runs the enabled phases after the symlinkScript command has ran.
NOTE: often you may prefer to set extraDrvAttrs.phases = [ ... "buildPhase" etc ... ]; instead,
to override this choice in a more fine-grained manner
Type: boolean
Default:
true
symlinkScript
Outside of importing wlib.modules.symlinkScript module,
which is included in wlib.modules.default,
This is usually an option you will never have to redefine.
This option takes a function receiving the following arguments:
{
wlib,
config,
outputs,
binName,
wrapper,
... # <- anything you can get from pkgs.callPackage
}:
The function is to return a string which will be added to the buildCommand of the wrapper. It is in charge of taking those options, and linking the files into place as requested.
binName is the value of config.binName if non-null, otherwise it is given a default value via baseNameOf lib.getExe on the config.package value
The value of config.binName is left as the user of the module set it, so that you can know who is giving you the value.
The same is true of the outputs argument.
wrapper is the result of calling wrapperFunction, or null if one was not provided.
Type: function that evaluates to a(n) string
Default:
<function, args: {binName, config, lib, lndir, outputs, wlib, wrapper}>
wrap
Function to extend the current configuration with additional modules. Re-evaluates the configuration with the original settings plus the new module. Returns the updated package.
Type: function that evaluates to a(n) raw value (read only)
Default:
<function>
wrapper
The final wrapped package.
You may still call .eval and the rest on the package again afterwards.
Accessing this value without defining pkgs option,
either directly, or via some other means like .wrap,
will cause an error.
Type: package (read only)
Default:
<derivation hello>
wrapperFunction
A function which returns a package.
Arguments:
{ config, wlib, outputs, binName, /* other args from callPackage */ ... }
That package returned must contain "$out/bin/${binName}"
as the executable to be wrapped.
(unless you also override symlinkScript)
binName is the value of config.binName if non-null, otherwise it is given a default value via baseNameOf lib.getExe
The value of config.binName is left as the user of the module set it, so that you can know who is giving you the value.
The same is true of the outputs argument.
The usual implementation is imported via wlib.modules.makeWrapperBase
wlib.modules.makeWrapper and wlib.modules.default include that module automatically.
Type: null or (function that evaluates to a(n) package)
Default:
null