These are the core options that make everything else possible.

They include the .extendModules, .apply, .eval, and .wrap functions, and the .wrapper itself

They are always imported with every module evaluation.

They are somewhat minimal by design. They pertain to building the derivation, not the wrapper script.

The default builderFunction 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!

Doing it this way allows wrapper modules to do anything you might wish involving wrapping some source/package in a derivation.

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!

apply

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns .config from the lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

binName

The name of the binary output by wrapperFunction to $out/bin

If not specified, the default name from the package will be used.

Type: non-empty line

Default:

"hello"

Declared by:

• lib/core.nix

builderFunction

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:

module arguments + wrapper + pkgs.callPackage

{
  wlib,
  config,
  wrapper,
  ... # <- anything you can get from pkgs.callPackage
}@initialArgs:
"<buildCommand>"

It is in charge of linking wrapper and config.outputs to the final package.

wrapper is the unchecked result of calling wrapperFunction, or null if one was not provided.

• The function is to return a string which will be added to the buildCommand of the wrapper.

The builtin implementation, and also the wlib.modules.symlinkScript module, accept either a string to prepend to the returned buildCommand string, or a derivation to link with lndir

• Alternatively, it may return a function which returns a set like:

{ wlib, config, wrapper, ... }@initialArgs:
drvArgs:
drvArgs // {}

If it does this, that function will be given the final computed derivation attributes, and it will be expected to return the final attribute set to be passed to pkgs.stdenv.mkDerivation.

Regardless of if you return a string or function, passthru.wrap, passthru.apply, passthru.eval, passthru.extendModules, passthru.override, passthru.overrideAttrs will be added to the thing you return, and config.sourceStdenv will be handled for you.

However:

• You can also return a functor with a (required) mkDerivation field.

  { config, stdenv, wrapper, wlib, ... }@initialArgs:
  {
    inherit (stdenv) mkDerivation;
    __functor = {
      mkDerivation,
      __functor,
      defaultPhases, # [ "<all stdenv phases>" ... ]
      setupPhases, # phases: "if [ -z \"${phases[*]:-}\" ]; then phases="etc..."; fi"
      runPhases, # "for curPhase in ${phases[*]}; do runPhase \"$curPhase\"; done"
      ...
    }@self:
    defaultArgs:
    defaultArgs // (if config.sourceStdenv then { } else { buildCommand = ""; }
  }

• If you do this:
  • You are in control over the entire derivation.
  • This means you need to take care of config.passthru and config.sourceStdenv yourself.
  • The mkDerivation function will be called with the final result of your functor.

As you can see, you are provided with some things to help you via the self argument to your functor.

The generated passthru items mentioned above are given to you as part of what is shown as defaultArgs above

And you are also given some helpers to help you run the phases if needed!

Tip: A functor is a set with a { __functor = self: args: ...; } field. You can call it like a function and it gets passed itself as its first argument!

Type: function that evaluates to a(n) (string or function that evaluates to a(n) attribute set of raw value)

Default:

<function, args: {config, lib, lndir, wlib, wrapper}>

Declared by:

• lib/core.nix

drv

Extra attributes to add to the resulting derivation.

Cannot affect passthru, or outputs. For that, use config.passthru, or config.outputs instead.

Also cannot override buildCommand. That is controlled by the config.builderFunction and config.sourceStdenv options.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

eval

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns the raw lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

exePath

The relative path to the executable to wrap. i.e. bin/exename

If not specified, the path gained from calling lib.getExe on config.package and subtracting the path to the package will be used.

Type: null or non-empty line

Default:

"bin/hello"

Declared by:

• lib/core.nix

extendModules

Alias for .extendModules so that you can call it from outside of wlib.types.subWrapperModule types

In addition, it is also a set which stores the function args for the module evaluation. This may prove useful when dealing with subWrapperModules or packages, which otherwise would not have access to some of them.

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function, args: {modules?, prefix?, specialArgs?}>

Declared by:

• lib/core.nix

meta.description

Description of the module.

Accepts either a string, or a set of { pre ? "", post ? "" }

Resulting config value will be a list of { pre, post, file }

Type: string or { pre ? “”, post ? “” } (converted to [ { pre, post, file } ])

Default:

""

Declared by:

• lib/core.nix

meta.maintainers

Maintainers of this module.

Type: list of (open submodule of attrsRecursive)

Default:

[ ]

Declared by:

• lib/core.nix

meta.maintainers.*.email

email

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.github

GitHub username

Type: string

Declared by:

• lib/core.nix

meta.maintainers.*.githubId

GitHub id

Type: signed integer

Declared by:

• lib/core.nix

meta.maintainers.*.matrix

Matrix ID

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.name

name

Type: string

Default:

"‹name›"

Declared by:

• lib/core.nix

meta.platforms

Supported platforms

Type: list of strings from enum of lib.platforms.all

Default:

lib.platforms.all

Example:

[
  "x86_64-linux"
  "aarch64-linux"
]

Declared by:

• lib/core.nix

outputs

Override the list of nix outputs that get symlinked into the final package.

Default is config.package.outputs or [ "out" ] if invalid.

Type: non-empty list of string

Default:

[
  "out"
]

Declared by:

• lib/core.nix

overrides

the list of .override and .overrideAttrs to apply to config.package

Accessing config.package will return the package with all overrides applied.

Accepts a list of { data, type ? null, name ? null, before ? [], after ? [] }

If type == null then data must be a function. It will receive and return the package.

If type is a string like override or overrideAttrs, it represents the attribute of config.package to pass the data field to.

If a raw value is given, it will be used as the data field, and type will be null.

config.package = pkgs.mpv;
config.overrides = [
  { # If they don't have a name they cannot be targeted!
    type = "override";
    after = [ "MPV_SCRIPTS" ];
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.visualizer ];
    });
  }
  {
    name = "MPV_SCRIPTS";
    type = "override";
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.modernz ];
    });
  }
  # the default `type` is `null`
  (pkg: pkg.override (prev: {
    scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.autocrop ];
  }))
  {
    type = null;
    before = [ "MPV_SCRIPTS" ];
    data = (pkg: pkg.override (prev: {
      scripts = (prev.scripts or []) ++ config.scripts;
    }));
  }
  { # It was already after "MPV_SCRIPTS" so this will stay where it is
    type = "overrideAttrs";
    after = [ "MPV_SCRIPTS" ];
    data = prev: {
      name = prev.name + "-wrapped";
    };
  }
];

The above will add config.scripts, then modernz then visualizer and finally autocrop

Then it will add -wrapped to the end of config.package’s name attribute.

The sort will not always put the value directly after the targeted value, it fulfils the requested before or after dependencies and no more.

You can modify the specs!

The type supports type merging, so you may redeclare it in order to add more options or change default values.

{ config, lib, wlib, pkgs, ... }:{
  options.overrides = lib.mkOption {
    type = wlib.types.seriesOf (wlib.types.spec ({ config, ... }: {
      options = {};
      config = {};
    }));
  };
}

Type: series of spec with main field: data of raw value

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.after

Items that this spec should be ordered after.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.before

Items that this spec should be ordered before.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.data

If type is null, then this is the function to call on the package.

If type is a string, then this is the data to pass to the function corresponding with that attribute.

Type: raw value

Declared by:

• lib/core.nix

overrides.*.name

The name for targeting from the before or after fields of other specs.

If null it cannot be targeted by other specs.

Type: null or string

Default:

null

Declared by:

• lib/core.nix

overrides.*.type

The attribute of config.package to pass the override argument to. If null, then data receives and returns the package instead.

If null, data must be a function. If a string, config.package must have the corresponding attribute, and it must be a function.

Type: null or one of “override”, “overrideAttrs” or string

Default:

null

Declared by:

• lib/core.nix

package

The base package to wrap. This means config.builderFunction will be responsible for inheriting all other files from this package (like man page, /share, …)

The config.package value given by this option already has all values from config.overrides applied to it.

Type: str|path|drv

Declared by:

• lib/core.nix

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. Anything added under the attribute name configuration will be ignored, as that value is used internally.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

pkgs

The nixpkgs pkgs instance to use.

Required in order to access .wrapper attribute, either directly, or indirectly.

Type: Nixpkgs package set

Declared by:

• lib/core.nix

sourceStdenv

Run the enabled stdenv phases on the wrapper derivation.

NOTE: often you may prefer to use things like drv.doDist = true;, or even drv.phases = [ ... "buildPhase" etc ... ]; instead, to override this choice in a more fine-grained manner

Type: boolean

Default:

true

Declared by:

• lib/core.nix

wrap

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns the updated package.

Type: (read-only) function that evaluates to a(n) package

Default:

<function>

Declared by:

• lib/core.nix

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: (read-only) package

Default:

<derivation hello-2.12.2>

Declared by:

• lib/core.nix

wrapperFunction

Arguments:

This option takes a function receiving the following arguments:

module arguments + pkgs.callPackage

{
  config,
  wlib,
  ... # <- anything you can get from pkgs.callPackage
}

The result of this function is passed DIRECTLY to the value of the builderFunction function.

The relative path to the thing to wrap from within config.package is config.exePath

You should wrap the package and place the wrapper at "$out/bin/${config.binName}"

Type: null or (function that evaluates to a(n) raw value)

Default:

null

Declared by:

• lib/core.nix

Adds extra options compared to the default builderFunction option value.

Imported by wlib.modules.default

aliases

Aliases for the package to also be added to the PATH

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToExclude

List of file paths (glob patterns) relative to package root to exclude from the wrapped package. This allows filtering out unwanted binaries or files. Example: [ "bin/unwanted-tool" "share/applications/*.desktop" ]

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToPatch

List of file paths (glob patterns) relative to package root to patch for self-references. Desktop files are patched by default to update Exec= and Icon= paths.

Type: list of string

Default:

[
  "share/applications/*.desktop"
]

Declared by:

• modules/symlinkScript

An implementation of the makeWrapper interface via type safe module options.

Allows you to choose one of several underlying implementations of the makeWrapper interface.

Imported by wlib.modules.default

Wherever the type includes DAG you can mentally substitute this with attrsOf

Wherever the type includes DAL or DAG list you can mentally substitute this with listOf

However they also take items of the form { data, name ? null, before ? [], after ? [] }

This allows you to specify that values are added to the wrapper before or after another value.

The sorting occurs across ALL the options, thus you can target items in any DAG or DAL within this module from any other DAG or DAL option within this module.

The DAG/DAL entries in this module also accept an extra field, esc-fn ? null

If defined, it will be used instead of the value of options.escapingFunction to escape that value.

It also has a set of submodule options under config.wrapperVariants which allow you to duplicate the effects to other binaries from the package, or add extra ones.

Each one contains an enable option, and a mirror option.

They also contain the same options the top level module does, however if mirror is true, as it is by default, then they will inherit the defaults from the top level as well.

They also have their own package, exePath, and binName options, with sensible defaults.

addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

wrapperVariants

Allows for you to apply the wrapper options to multiple binaries from config.package (or elsewhere)

They are called variants because they are the same options as the top level makeWrapper options, however, their defaults mirror the values of the top level options.

Meaning if you set config.env.MYVAR = "HELLO" at the top level, then the following statement would be true by default:

config.wrapperVariants.foo.env.MYVAR.data == "HELLO"

They achieve this by receiving mainConfig and mainOpts via specialArgs, which contain config and options from the top level.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.binName

The name of the file to output to $out/bin/

Type: non-empty line

Default:

"‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.enable

Enables the wrapping of this variant

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.exePath

The location within the package of the thing to wrap.

Type: null or non-empty line

Default:

"bin/‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.mirror

Allows the variant to inherit defaults from the top level

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.package

The package to wrap with these options

Type: str|path|drv

Default:

<derivation hello-2.12.2>

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

The makeWrapper library:

Should you ever need to redefine config.wrapperFunction, or use these options somewhere else, this module doubles as a library for doing so!

makeWrapper = import wlib.modules.makeWrapper;

If you import it like shown, you gain access to some values.

First, you may modify the module itself.

For this it offers:

exclude_wrapper = true; to stop it from setting config.wrapperFunction

wrapperFunction = ...; to override the default config.wrapperFunction that it sets instead of excluding it.

exclude_meta = true; to stop it from setting any values in config.meta

excluded_options = { ... }; where you may include optionname = true in order to not define that option.

_file and key: _file changes the value set for the modules imported when you import this module. key is set on the main one if not null.

In order to change these values, you change them in the set before importing the module like so:

  imports = [ (import wlib.modules.makeWrapper // { excluded_options.wrapperVariants = true; }) ];

It also offers 4 functions for using those options to generate build instructions for a wrapper

• wrapAll: generates build instructions for the main target and all variants
• wrapMain: generates build instructions for the main target
• wrapVariants: generates build instructions for all variants but not the main target
• wrapVariant: generates build instructions for a single variant

All 4 of them return a string that can be added to the derivation definition to build the specified wrappers.

The first 3, wrapAll, wrapMain, and wrapVariants, are used like this:

(import wlib.modules.makeWrapper).wrapAll { inherit config wlib; inherit (pkgs) callPackage; # or inherit pkgs; };

The 4th, wrapVariant, has an extra name argument:

(import wlib.modules.makeWrapper).wrapVariant { inherit config wlib; inherit (pkgs) callPackage; # or inherit pkgs; name = "attribute"; };

Where attribute is an attribute of the config.wrapperVariants set

Other than whatever options from the wlib.modules.makeWrapper module are defined in the config variable passed, each one relies on config containing binName, package, and exePath.

If config.exePath is not a string or is an empty string, config.package will be the full path wrapped. Otherwise, it will wrap "${config.package}/${config.binName}.

If config.binName or config.package are not provided it will return an empty string for that target.

In addition, if a variant has enable set to false, it will also not be included in the returned string.

An implementation of the makeWrapper interface via type safe module options.

Allows you to choose one of several underlying implementations of the makeWrapper interface.

Imported by wlib.modules.default

Wherever the type includes DAG you can mentally substitute this with attrsOf

Wherever the type includes DAL or DAG list you can mentally substitute this with listOf

However they also take items of the form { data, name ? null, before ? [], after ? [] }

This allows you to specify that values are added to the wrapper before or after another value.

The sorting occurs across ALL the options, thus you can target items in any DAG or DAL within this module from any other DAG or DAL option within this module.

The DAG/DAL entries in this module also accept an extra field, esc-fn ? null

If defined, it will be used instead of the value of options.escapingFunction to escape that value.

It also has a set of submodule options under config.wrapperVariants which allow you to duplicate the effects to other binaries from the package, or add extra ones.

Each one contains an enable option, and a mirror option.

They also contain the same options the top level module does, however if mirror is true, as it is by default, then they will inherit the defaults from the top level as well.

They also have their own package, exePath, and binName options, with sensible defaults.

addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

wrapperVariants

Allows for you to apply the wrapper options to multiple binaries from config.package (or elsewhere)

They are called variants because they are the same options as the top level makeWrapper options, however, their defaults mirror the values of the top level options.

Meaning if you set config.env.MYVAR = "HELLO" at the top level, then the following statement would be true by default:

config.wrapperVariants.foo.env.MYVAR.data == "HELLO"

They achieve this by receiving mainConfig and mainOpts via specialArgs, which contain config and options from the top level.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.binName

The name of the file to output to $out/bin/

Type: non-empty line

Default:

"‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.enable

Enables the wrapping of this variant

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.exePath

The location within the package of the thing to wrap.

Type: null or non-empty line

Default:

"bin/‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.mirror

Allows the variant to inherit defaults from the top level

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.package

The package to wrap with these options

Type: str|path|drv

Default:

<derivation hello-2.12.2>

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

The makeWrapper library:

Should you ever need to redefine config.wrapperFunction, or use these options somewhere else, this module doubles as a library for doing so!

makeWrapper = import wlib.modules.makeWrapper;

If you import it like shown, you gain access to some values.

First, you may modify the module itself.

For this it offers:

exclude_wrapper = true; to stop it from setting config.wrapperFunction

wrapperFunction = ...; to override the default config.wrapperFunction that it sets instead of excluding it.

exclude_meta = true; to stop it from setting any values in config.meta

excluded_options = { ... }; where you may include optionname = true in order to not define that option.

_file and key: _file changes the value set for the modules imported when you import this module. key is set on the main one if not null.

In order to change these values, you change them in the set before importing the module like so:

  imports = [ (import wlib.modules.makeWrapper // { excluded_options.wrapperVariants = true; }) ];

It also offers 4 functions for using those options to generate build instructions for a wrapper

• wrapAll: generates build instructions for the main target and all variants
• wrapMain: generates build instructions for the main target
• wrapVariants: generates build instructions for all variants but not the main target
• wrapVariant: generates build instructions for a single variant

All 4 of them return a string that can be added to the derivation definition to build the specified wrappers.

The first 3, wrapAll, wrapMain, and wrapVariants, are used like this:

(import wlib.modules.makeWrapper).wrapAll { inherit config wlib; inherit (pkgs) callPackage; # or inherit pkgs; };

The 4th, wrapVariant, has an extra name argument:

(import wlib.modules.makeWrapper).wrapVariant { inherit config wlib; inherit (pkgs) callPackage; # or inherit pkgs; name = "attribute"; };

Where attribute is an attribute of the config.wrapperVariants set

Other than whatever options from the wlib.modules.makeWrapper module are defined in the config variable passed, each one relies on config containing binName, package, and exePath.

If config.exePath is not a string or is an empty string, config.package will be the full path wrapped. Otherwise, it will wrap "${config.package}/${config.binName}.

If config.binName or config.package are not provided it will return an empty string for that target.

In addition, if a variant has enable set to false, it will also not be included in the returned string.

Adds extra options compared to the default builderFunction option value.

Imported by wlib.modules.default

aliases

Aliases for the package to also be added to the PATH

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToExclude

List of file paths (glob patterns) relative to package root to exclude from the wrapped package. This allows filtering out unwanted binaries or files. Example: [ "bin/unwanted-tool" "share/applications/*.desktop" ]

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToPatch

List of file paths (glob patterns) relative to package root to patch for self-references. Desktop files are patched by default to update Exec= and Icon= paths.

Type: list of string

Default:

[
  "share/applications/*.desktop"
]

Declared by:

• modules/symlinkScript

settings

Configuration of alacritty. See {manpage}alacritty(5) or https://alacritty.org/config-alacritty.html

Type: TOML value

Default:

{ }

Declared by:

• wrapperModules/a/alacritty

Adds extra options compared to the default builderFunction option value.

Imported by wlib.modules.default

aliases

Aliases for the package to also be added to the PATH

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToExclude

List of file paths (glob patterns) relative to package root to exclude from the wrapped package. This allows filtering out unwanted binaries or files. Example: [ "bin/unwanted-tool" "share/applications/*.desktop" ]

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToPatch

List of file paths (glob patterns) relative to package root to patch for self-references. Desktop files are patched by default to update Exec= and Icon= paths.

Type: list of string

Default:

[
  "share/applications/*.desktop"
]

Declared by:

• modules/symlinkScript

An implementation of the makeWrapper interface via type safe module options.

Allows you to choose one of several underlying implementations of the makeWrapper interface.

Imported by wlib.modules.default

Wherever the type includes DAG you can mentally substitute this with attrsOf

Wherever the type includes DAL or DAG list you can mentally substitute this with listOf

However they also take items of the form { data, name ? null, before ? [], after ? [] }

This allows you to specify that values are added to the wrapper before or after another value.

The sorting occurs across ALL the options, thus you can target items in any DAG or DAL within this module from any other DAG or DAL option within this module.

The DAG/DAL entries in this module also accept an extra field, esc-fn ? null

If defined, it will be used instead of the value of options.escapingFunction to escape that value.

It also has a set of submodule options under config.wrapperVariants which allow you to duplicate the effects to other binaries from the package, or add extra ones.

Each one contains an enable option, and a mirror option.

They also contain the same options the top level module does, however if mirror is true, as it is by default, then they will inherit the defaults from the top level as well.

They also have their own package, exePath, and binName options, with sensible defaults.

addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

wrapperVariants

Allows for you to apply the wrapper options to multiple binaries from config.package (or elsewhere)

They are called variants because they are the same options as the top level makeWrapper options, however, their defaults mirror the values of the top level options.

Meaning if you set config.env.MYVAR = "HELLO" at the top level, then the following statement would be true by default:

config.wrapperVariants.foo.env.MYVAR.data == "HELLO"

They achieve this by receiving mainConfig and mainOpts via specialArgs, which contain config and options from the top level.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.binName

The name of the file to output to $out/bin/

Type: non-empty line

Default:

"‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.enable

Enables the wrapping of this variant

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.exePath

The location within the package of the thing to wrap.

Type: null or non-empty line

Default:

"bin/‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{
  "--config-file" = {
    after = [ ];
    before = [ ];
    data = <derivation alacritty.toml>;
    esc-fn = null;
    name = null;
    sep = null;
  };
}

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.mirror

Allows the variant to inherit defaults from the top level

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.package

The package to wrap with these options

Type: str|path|drv

Default:

<derivation alacritty-0.16.1>

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

These are the core options that make everything else possible.

They include the .extendModules, .apply, .eval, and .wrap functions, and the .wrapper itself

They are always imported with every module evaluation.

They are somewhat minimal by design. They pertain to building the derivation, not the wrapper script.

The default builderFunction 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!

Doing it this way allows wrapper modules to do anything you might wish involving wrapping some source/package in a derivation.

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!

apply

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns .config from the lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

binName

The name of the binary output by wrapperFunction to $out/bin

If not specified, the default name from the package will be used.

Type: non-empty line

Default:

"alacritty"

Declared by:

• lib/core.nix

builderFunction

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:

module arguments + wrapper + pkgs.callPackage

{
  wlib,
  config,
  wrapper,
  ... # <- anything you can get from pkgs.callPackage
}@initialArgs:
"<buildCommand>"

It is in charge of linking wrapper and config.outputs to the final package.

wrapper is the unchecked result of calling wrapperFunction, or null if one was not provided.

• The function is to return a string which will be added to the buildCommand of the wrapper.

The builtin implementation, and also the wlib.modules.symlinkScript module, accept either a string to prepend to the returned buildCommand string, or a derivation to link with lndir

• Alternatively, it may return a function which returns a set like:

{ wlib, config, wrapper, ... }@initialArgs:
drvArgs:
drvArgs // {}

If it does this, that function will be given the final computed derivation attributes, and it will be expected to return the final attribute set to be passed to pkgs.stdenv.mkDerivation.

Regardless of if you return a string or function, passthru.wrap, passthru.apply, passthru.eval, passthru.extendModules, passthru.override, passthru.overrideAttrs will be added to the thing you return, and config.sourceStdenv will be handled for you.

However:

• You can also return a functor with a (required) mkDerivation field.

  { config, stdenv, wrapper, wlib, ... }@initialArgs:
  {
    inherit (stdenv) mkDerivation;
    __functor = {
      mkDerivation,
      __functor,
      defaultPhases, # [ "<all stdenv phases>" ... ]
      setupPhases, # phases: "if [ -z \"${phases[*]:-}\" ]; then phases="etc..."; fi"
      runPhases, # "for curPhase in ${phases[*]}; do runPhase \"$curPhase\"; done"
      ...
    }@self:
    defaultArgs:
    defaultArgs // (if config.sourceStdenv then { } else { buildCommand = ""; }
  }

• If you do this:
  • You are in control over the entire derivation.
  • This means you need to take care of config.passthru and config.sourceStdenv yourself.
  • The mkDerivation function will be called with the final result of your functor.

As you can see, you are provided with some things to help you via the self argument to your functor.

The generated passthru items mentioned above are given to you as part of what is shown as defaultArgs above

And you are also given some helpers to help you run the phases if needed!

Tip: A functor is a set with a { __functor = self: args: ...; } field. You can call it like a function and it gets passed itself as its first argument!

Type: function that evaluates to a(n) (string or function that evaluates to a(n) attribute set of raw value)

Default:

<function, args: {config, lib, lndir, wlib, wrapper}>

Declared by:

• lib/core.nix

drv

Extra attributes to add to the resulting derivation.

Cannot affect passthru, or outputs. For that, use config.passthru, or config.outputs instead.

Also cannot override buildCommand. That is controlled by the config.builderFunction and config.sourceStdenv options.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

eval

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns the raw lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

exePath

The relative path to the executable to wrap. i.e. bin/exename

If not specified, the path gained from calling lib.getExe on config.package and subtracting the path to the package will be used.

Type: null or non-empty line

Default:

"bin/alacritty"

Declared by:

• lib/core.nix

extendModules

Alias for .extendModules so that you can call it from outside of wlib.types.subWrapperModule types

In addition, it is also a set which stores the function args for the module evaluation. This may prove useful when dealing with subWrapperModules or packages, which otherwise would not have access to some of them.

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function, args: {modules?, prefix?, specialArgs?}>

Declared by:

• lib/core.nix

meta.description

Description of the module.

Accepts either a string, or a set of { pre ? "", post ? "" }

Resulting config value will be a list of { pre, post, file }

Type: string or { pre ? “”, post ? “” } (converted to [ { pre, post, file } ])

Default:

""

Declared by:

• lib/core.nix

meta.maintainers

Maintainers of this module.

Type: list of (open submodule of attrsRecursive)

Default:

[ ]

Declared by:

• lib/core.nix

meta.maintainers.*.email

email

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.github

GitHub username

Type: string

Declared by:

• lib/core.nix

meta.maintainers.*.githubId

GitHub id

Type: signed integer

Declared by:

• lib/core.nix

meta.maintainers.*.matrix

Matrix ID

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.name

name

Type: string

Default:

"‹name›"

Declared by:

• lib/core.nix

meta.platforms

Supported platforms

Type: list of strings from enum of lib.platforms.all

Default:

lib.platforms.all

Example:

[
  "x86_64-linux"
  "aarch64-linux"
]

Declared by:

• lib/core.nix

outputs

Override the list of nix outputs that get symlinked into the final package.

Default is config.package.outputs or [ "out" ] if invalid.

Type: non-empty list of string

Default:

[
  "out"
  "terminfo"
]

Declared by:

• lib/core.nix

overrides

the list of .override and .overrideAttrs to apply to config.package

Accessing config.package will return the package with all overrides applied.

Accepts a list of { data, type ? null, name ? null, before ? [], after ? [] }

If type == null then data must be a function. It will receive and return the package.

If type is a string like override or overrideAttrs, it represents the attribute of config.package to pass the data field to.

If a raw value is given, it will be used as the data field, and type will be null.

config.package = pkgs.mpv;
config.overrides = [
  { # If they don't have a name they cannot be targeted!
    type = "override";
    after = [ "MPV_SCRIPTS" ];
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.visualizer ];
    });
  }
  {
    name = "MPV_SCRIPTS";
    type = "override";
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.modernz ];
    });
  }
  # the default `type` is `null`
  (pkg: pkg.override (prev: {
    scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.autocrop ];
  }))
  {
    type = null;
    before = [ "MPV_SCRIPTS" ];
    data = (pkg: pkg.override (prev: {
      scripts = (prev.scripts or []) ++ config.scripts;
    }));
  }
  { # It was already after "MPV_SCRIPTS" so this will stay where it is
    type = "overrideAttrs";
    after = [ "MPV_SCRIPTS" ];
    data = prev: {
      name = prev.name + "-wrapped";
    };
  }
];

The above will add config.scripts, then modernz then visualizer and finally autocrop

Then it will add -wrapped to the end of config.package’s name attribute.

The sort will not always put the value directly after the targeted value, it fulfils the requested before or after dependencies and no more.

You can modify the specs!

The type supports type merging, so you may redeclare it in order to add more options or change default values.

{ config, lib, wlib, pkgs, ... }:{
  options.overrides = lib.mkOption {
    type = wlib.types.seriesOf (wlib.types.spec ({ config, ... }: {
      options = {};
      config = {};
    }));
  };
}

Type: series of spec with main field: data of raw value

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.after

Items that this spec should be ordered after.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.before

Items that this spec should be ordered before.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.data

If type is null, then this is the function to call on the package.

If type is a string, then this is the data to pass to the function corresponding with that attribute.

Type: raw value

Declared by:

• lib/core.nix

overrides.*.name

The name for targeting from the before or after fields of other specs.

If null it cannot be targeted by other specs.

Type: null or string

Default:

null

Declared by:

• lib/core.nix

overrides.*.type

The attribute of config.package to pass the override argument to. If null, then data receives and returns the package instead.

If null, data must be a function. If a string, config.package must have the corresponding attribute, and it must be a function.

Type: null or one of “override”, “overrideAttrs” or string

Default:

null

Declared by:

• lib/core.nix

package

The base package to wrap. This means config.builderFunction will be responsible for inheriting all other files from this package (like man page, /share, …)

The config.package value given by this option already has all values from config.overrides applied to it.

Type: str|path|drv

Declared by:

• lib/core.nix

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. Anything added under the attribute name configuration will be ignored, as that value is used internally.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

pkgs

The nixpkgs pkgs instance to use.

Required in order to access .wrapper attribute, either directly, or indirectly.

Type: Nixpkgs package set

Declared by:

• lib/core.nix

sourceStdenv

Run the enabled stdenv phases on the wrapper derivation.

NOTE: often you may prefer to use things like drv.doDist = true;, or even drv.phases = [ ... "buildPhase" etc ... ]; instead, to override this choice in a more fine-grained manner

Type: boolean

Default:

true

Declared by:

• lib/core.nix

wrap

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns the updated package.

Type: (read-only) function that evaluates to a(n) package

Default:

<function>

Declared by:

• lib/core.nix

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: (read-only) package

Default:

<derivation alacritty-0.16.1>

Declared by:

• lib/core.nix

wrapperFunction

Arguments:

This option takes a function receiving the following arguments:

module arguments + pkgs.callPackage

{
  config,
  wlib,
  ... # <- anything you can get from pkgs.callPackage
}

The result of this function is passed DIRECTLY to the value of the builderFunction function.

The relative path to the thing to wrap from within config.package is config.exePath

You should wrap the package and place the wrapper at "$out/bin/${config.binName}"

Type: null or (function that evaluates to a(n) raw value)

Default:

null

Declared by:

• lib/core.nix

settings

Configuration options of atool via the –option flag. See {manpage}atool(1)

Type: attribute set of (string or boolean)

Default:

{ }

Declared by:

• wrapperModules/a/atool

tools.enable

Enable managing which tool paths atool will use.

Type: boolean

Default:

true

Declared by:

• wrapperModules/a/atool

tools.paths."7z"

Path to the 7z executable.

Type: string

Default:

"/nix/store/9zy0g1djayzh25g8b1y7p9p928ic28cs-p7zip-17.06/bin/7z"

Declared by:

• wrapperModules/a/atool

tools.paths.arj

Path to the arj executable.

Type: string

Default:

"/nix/store/2zngbid4mrfhiwc9a7xqmvbzr603zm38-arj-3.10.22/bin/arj"

Declared by:

• wrapperModules/a/atool

tools.paths.bzip2

Path to the bzip2 execeutable.

Type: string

Default:

"/nix/store/90yw24gqmwph4xjp4mqhpx1y1gcrvqla-bzip2-1.0.8-bin/bin/bzip2"

Declared by:

• wrapperModules/a/atool

tools.paths.cabextract

Path to the cabextract executable.

Type: string

Default:

"/nix/store/qnw13h7mjl897aqw817paj25fclmvhsp-cabextract-1.11/bin/cabextract"

Declared by:

• wrapperModules/a/atool

tools.paths.cpio

Path to the cpio executable.

Type: string

Default:

"/nix/store/bnf1y2hy2151xj0jg3v6gjyp1mqwl1cy-cpio-2.15/bin/cpio"

Declared by:

• wrapperModules/a/atool

tools.paths.dpkg_deb

Path to the dpkg-deb executable.

Type: string

Default:

"/nix/store/kls9dgmmdrvnxm07zyshxm4ppw0jg2h7-dpkg-1.22.21/bin/dpkg-deb"

Declared by:

• wrapperModules/a/atool

tools.paths.gzip

Path to the gzip execeutable.

Type: string

Default:

"/nix/store/84yyzmxs7mb8nhkvcfv9n1l9irpb6mnq-gzip-1.14/bin/gzip"

Declared by:

• wrapperModules/a/atool

tools.paths.lrzip

Path to the lrzip executable.

Type: string

Default:

"/nix/store/rmgdsmnwi453a98k6jrlm486a0jzc5vp-lrzip-0.651/bin/lrzip"

Declared by:

• wrapperModules/a/atool

tools.paths.lzma

Path to the lzma execeutable.

Type: string

Default:

"/nix/store/zys6d102zp171wpwcs08g632886w2qxs-xz-5.8.2-bin/bin/lzma"

Declared by:

• wrapperModules/a/atool

tools.paths.lzop

Path to the lzop executable.

Type: string

Default:

"/nix/store/gd6dhvwn3k4iqzhdsf9mgfxv50ya4dyl-lzop-1.04/bin/lzop"

Declared by:

• wrapperModules/a/atool

tools.paths.rar

Path to the rar executable.

Type: string

Default:

"rar"

Declared by:

• wrapperModules/a/atool

tools.paths.rpm

Path to the rpm executable.

Type: string

Default:

"/nix/store/bqrjjqpcsswskyv4x9swrhhvkz4m54bg-rpm-4.20.1/bin/rpm"

Declared by:

• wrapperModules/a/atool

tools.paths.rpm2cpio

Path to the rpm2cpio executable.

Type: string

Default:

"/nix/store/bqrjjqpcsswskyv4x9swrhhvkz4m54bg-rpm-4.20.1/bin/rpm2cpio"

Declared by:

• wrapperModules/a/atool

tools.paths.rzip

Path to the rzip executable.

Type: string

Default:

"/nix/store/gdh2fq9ikas0320ki94f6hr5qadf5vlc-rzip-2.1/bin/rzip"

Declared by:

• wrapperModules/a/atool

tools.paths.tar

Path to the tar executable.

Type: string

Default:

"/nix/store/qyg62bc2xnpwz0fa9prqxvvk00zj4g9q-gnutar-1.35/bin/tar"

Declared by:

• wrapperModules/a/atool

tools.paths.unrar

Path to the lzma execeutable.

Type: string

Default:

"unrar"

Declared by:

• wrapperModules/a/atool

tools.paths.unzip

Path to the unzip execeutable.

Type: string

Default:

"/nix/store/d8dikfh0z22zmqxjgj0sw6v8sfnfv0nv-unzip-6.0/bin/unzip"

Declared by:

• wrapperModules/a/atool

tools.paths.zip

Path to the zip execeutable.

Type: string

Default:

"/nix/store/gmnyjhnic4kcg3k33lifhpsm4v0zxhrb-zip-3.0/bin/zip"

Declared by:

• wrapperModules/a/atool

Adds extra options compared to the default builderFunction option value.

Imported by wlib.modules.default

aliases

Aliases for the package to also be added to the PATH

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToExclude

List of file paths (glob patterns) relative to package root to exclude from the wrapped package. This allows filtering out unwanted binaries or files. Example: [ "bin/unwanted-tool" "share/applications/*.desktop" ]

Type: list of string

Default:

[ ]

Declared by:

• modules/symlinkScript

filesToPatch

List of file paths (glob patterns) relative to package root to patch for self-references. Desktop files are patched by default to update Exec= and Icon= paths.

Type: list of string

Default:

[
  "share/applications/*.desktop"
]

Declared by:

• modules/symlinkScript

An implementation of the makeWrapper interface via type safe module options.

Allows you to choose one of several underlying implementations of the makeWrapper interface.

Imported by wlib.modules.default

Wherever the type includes DAG you can mentally substitute this with attrsOf

Wherever the type includes DAL or DAG list you can mentally substitute this with listOf

However they also take items of the form { data, name ? null, before ? [], after ? [] }

This allows you to specify that values are added to the wrapper before or after another value.

The sorting occurs across ALL the options, thus you can target items in any DAG or DAL within this module from any other DAG or DAL option within this module.

The DAG/DAL entries in this module also accept an extra field, esc-fn ? null

If defined, it will be used instead of the value of options.escapingFunction to escape that value.

It also has a set of submodule options under config.wrapperVariants which allow you to duplicate the effects to other binaries from the package, or add extra ones.

Each one contains an enable option, and a mirror option.

They also contain the same options the top level module does, however if mirror is true, as it is by default, then they will inherit the defaults from the top level as well.

They also have their own package, exePath, and binName options, with sensible defaults.

addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{ }

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

wrapperVariants

Allows for you to apply the wrapper options to multiple binaries from config.package (or elsewhere)

They are called variants because they are the same options as the top level makeWrapper options, however, their defaults mirror the values of the top level options.

Meaning if you set config.env.MYVAR = "HELLO" at the top level, then the following statement would be true by default:

config.wrapperVariants.foo.env.MYVAR.data == "HELLO"

They achieve this by receiving mainConfig and mainOpts via specialArgs, which contain config and options from the top level.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag

Wrapper for

–add-flag ARG

Prepend the single argument ARG to the invocation of the executable, before any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.addFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag

–append-flag ARG

Append the single argument ARG to the invocation of the executable, after any command-line arguments.

This option takes a list. To group them more strongly, option may take a list of lists as well.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of (str|path|drv or list of str|path|drv)

Default:

[ ]

Example:

[
  "-v"
  "-f"
  [
    "--config"
    ./storePath.cfg
  ]
  [
    "-s"
    "idk"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.appendFlag.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0

–argv0 NAME

Set the name of the executed process to NAME. If unset or null, defaults to EXECUTABLE.

overrides the setting from argv0type if set.

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.argv0type

argv0 overrides this option if not null or unset

Both shell and the nix implementations ignore this option, as the shell always resolves $0

However, the binary implementation will use this option

Values:

• "inherit":

The executable inherits argv0 from the wrapper. Use instead of --argv0 '$0'.

• "resolve":

If argv0 does not include a “/” character, resolve it against PATH.

• Function form: str -> str

This one works only in the nix implementation. The others will treat it as inherit

Rather than calling exec, you get the command plus all its flags supplied, and you can choose how to run it.

e.g. command_string: "eval \"$(${command_string})\";

It will also be added to the end of the overall DAL, with the name NIX_RUN_MAIN_PACKAGE

Thus, you can make things run after it, but by default it is still last.

Type: one of “resolve”, “inherit” or function that evaluates to a(n) string

Default:

"inherit"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.binName

The name of the file to output to $out/bin/

Type: non-empty line

Default:

"‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir

–chdir DIR

Change working directory before running the executable. Use instead of --run "cd DIR".

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.chdir.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.enable

Enables the wrapping of this variant

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env

Environment variables to set in the wrapper.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/somewhere/on/your/machine";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.env.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault

Environment variables to set in the wrapper.

Like env, but only adds the variable if not already set in the environment.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of str|path|drv

Default:

{ }

Example:

{
  XDG_DATA_HOME = "/only/if/not/set";
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.envDefault.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.escapingFunction

The function to use to escape shell values

Caution: When using shell or binary implementations, these will be expanded at BUILD time.

You should probably leave this as is when using either of those implementations.

However, when using the nix implementation, they will expand at runtime! Which means wlib.escapeShellArgWithEnv may prove to be a useful substitute!

Type: function that evaluates to a(n) string

Default:

lib.escapeShellArg

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.exePath

The location within the package of the thing to wrap.

Type: null or non-empty line

Default:

"bin/‹name›"

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.extraPackages

Additional packages to add to the wrapper’s runtime PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_PATH_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flagSeparator

Separator between flag names and values when generating args from flags. " " for --flag value or "=" for --flag=value

Type: string

Default:

" "

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags

Flags to pass to the wrapper. The key is the flag name, the value is the flag value. If the value is true, the flag will be passed without a value. If the value is false or null, the flag will not be passed. If the value is a list, the flag will be passed multiple times with each value.

This option takes a set.

Any entry can instead be of type { data, before ? [], after ? [], esc-fn ? null, sep ? null }

The sep field may be used to override the value of config.flagSeparator

This will cause it to be added to the DAG, which will cause the resulting wrapper argument to be sorted accordingly

Type: attribute set of spec with main field: data of (null or boolean or str|path|drv or list of str|path|drv)

Default:

{
  "--option" = {
    after = [ ];
    before = [ ];
    data = [
      "path_7z=/nix/store/9zy0g1djayzh25g8b1y7p9p928ic28cs-p7zip-17.06/bin/7z"
      "path_arj=/nix/store/2zngbid4mrfhiwc9a7xqmvbzr603zm38-arj-3.10.22/bin/arj"
      "path_bzip2=/nix/store/90yw24gqmwph4xjp4mqhpx1y1gcrvqla-bzip2-1.0.8-bin/bin/bzip2"
      "path_cabextract=/nix/store/qnw13h7mjl897aqw817paj25fclmvhsp-cabextract-1.11/bin/cabextract"
      "path_cpio=/nix/store/bnf1y2hy2151xj0jg3v6gjyp1mqwl1cy-cpio-2.15/bin/cpio"
      "path_dpkg_deb=/nix/store/kls9dgmmdrvnxm07zyshxm4ppw0jg2h7-dpkg-1.22.21/bin/dpkg-deb"
      "path_gzip=/nix/store/84yyzmxs7mb8nhkvcfv9n1l9irpb6mnq-gzip-1.14/bin/gzip"
      "path_lrzip=/nix/store/rmgdsmnwi453a98k6jrlm486a0jzc5vp-lrzip-0.651/bin/lrzip"
      "path_lzma=/nix/store/zys6d102zp171wpwcs08g632886w2qxs-xz-5.8.2-bin/bin/lzma"
      "path_lzop=/nix/store/gd6dhvwn3k4iqzhdsf9mgfxv50ya4dyl-lzop-1.04/bin/lzop"
      "path_rar=rar"
      "path_rpm=/nix/store/bqrjjqpcsswskyv4x9swrhhvkz4m54bg-rpm-4.20.1/bin/rpm"
      "path_rpm2cpio=/nix/store/bqrjjqpcsswskyv4x9swrhhvkz4m54bg-rpm-4.20.1/bin/rpm2cpio"
      "path_rzip=/nix/store/gdh2fq9ikas0320ki94f6hr5qadf5vlc-rzip-2.1/bin/rzip"
      "path_tar=/nix/store/qyg62bc2xnpwz0fa9prqxvvk00zj4g9q-gnutar-1.35/bin/tar"
      "path_unrar=unrar"
      "path_unzip=/nix/store/d8dikfh0z22zmqxjgj0sw6v8sfnfv0nv-unzip-6.0/bin/unzip"
      "path_zip=/nix/store/gmnyjhnic4kcg3k33lifhpsm4v0zxhrb-zip-3.0/bin/zip"
    ];
    esc-fn = null;
    name = null;
    sep = "=";
  };
}

Example:

{
  "--config" = ./nixPath;
}

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.flags.<name>.sep

A per-item override of the default separator used for flags and their values

Type: null or string

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.mirror

Allows the variant to inherit defaults from the top level

Type: boolean

Default:

true

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.package

The package to wrap with these options

Type: str|path|drv

Default:

<derivation atool-0.39.0>

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Prefix ENV with contents of FILE and SEP at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar

–prefix ENV SEP VAL

Prefix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.prefixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell

–run COMMAND

Run COMMAND before executing the main program.

This option takes a list.

Any entry can instead be of type { data, name ? null, before ? [], after ? [], esc-fn ? null }

This will cause it to be added to the DAG.

If no name is provided, it cannot be targeted.

Type: list of spec with main field: data of str|path|drv

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runShell.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.runtimeLibraries

Additional libraries to add to the wrapper’s runtime LD_LIBRARY_PATH. This is useful if the wrapped program needs additional libraries or tools to function correctly.

Adds all its entries to the DAG under the name NIX_LIB_ADDITIONS

Type: list of package

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent

[
  [ "ENV" "SEP" "FILE" ]
]

Suffix ENV with SEP and then the contents of FILE at build time.

Also accepts sets like the other options

[
  [ "ENV" "SEP" "FILE" ]
  { data = [ "ENV" "SEP" "FILE" ]; esc-fn = lib.escapeShellArg; /* name, before, after */ }
]

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixContent.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar

–suffix ENV SEP VAL

Suffix ENV with VAL, separated by SEP.

Type: list of spec with main field: data of (List of length 3)

Default:

[ ]

Example:

[
  [
    "LD_LIBRARY_PATH"
    ":"
    "${lib.makeLibraryPath (with pkgs; [ ... ])}"
  ]
  [
    "PATH"
    ":"
    "${lib.makeBinPath (with pkgs; [ ... ])}"
  ]
]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.suffixVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar

–unset VAR

Remove VAR from the environment.

Type: list of spec with main field: data of string

Default:

[ ]

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.unsetVar.*.esc-fn

A per-item override of the default string escape function

Type: null or (function that evaluates to a(n) string)

Default:

null

Declared by:

• modules/makeWrapper

wrapperVariants.<name>.wrapperImplementation

the nix implementation is the default

It makes the escapingFunction most relevant.

This is because the shell and binary implementations use pkgs.makeWrapper or pkgs.makeBinaryWrapper, and arguments to these functions are passed at BUILD time.

So, generally, when not using the nix implementation, you should always prefer to have escapingFunction set to lib.escapeShellArg.

However, if you ARE using the nix implementation, using wlib.escapeShellArgWithEnv will allow you to use $ expansions, which will expand at runtime.

binary implementation is useful for programs which are likely to be used in “shebangs”, as macos will not allow scripts to be used for these.

However, it is more limited. It does not have access to runShell, prefixContent, and suffixContent options.

Chosing binary will thus cause values in those options to be ignored.

Type: one of “nix”, “shell”, “binary”

Default:

"nix"

Declared by:

• modules/makeWrapper

These are the core options that make everything else possible.

They include the .extendModules, .apply, .eval, and .wrap functions, and the .wrapper itself

They are always imported with every module evaluation.

They are somewhat minimal by design. They pertain to building the derivation, not the wrapper script.

The default builderFunction 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!

Doing it this way allows wrapper modules to do anything you might wish involving wrapping some source/package in a derivation.

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!

apply

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns .config from the lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

binName

The name of the binary output by wrapperFunction to $out/bin

If not specified, the default name from the package will be used.

Type: non-empty line

Default:

"atool"

Declared by:

• lib/core.nix

builderFunction

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:

module arguments + wrapper + pkgs.callPackage

{
  wlib,
  config,
  wrapper,
  ... # <- anything you can get from pkgs.callPackage
}@initialArgs:
"<buildCommand>"

It is in charge of linking wrapper and config.outputs to the final package.

wrapper is the unchecked result of calling wrapperFunction, or null if one was not provided.

• The function is to return a string which will be added to the buildCommand of the wrapper.

The builtin implementation, and also the wlib.modules.symlinkScript module, accept either a string to prepend to the returned buildCommand string, or a derivation to link with lndir

• Alternatively, it may return a function which returns a set like:

{ wlib, config, wrapper, ... }@initialArgs:
drvArgs:
drvArgs // {}

If it does this, that function will be given the final computed derivation attributes, and it will be expected to return the final attribute set to be passed to pkgs.stdenv.mkDerivation.

Regardless of if you return a string or function, passthru.wrap, passthru.apply, passthru.eval, passthru.extendModules, passthru.override, passthru.overrideAttrs will be added to the thing you return, and config.sourceStdenv will be handled for you.

However:

• You can also return a functor with a (required) mkDerivation field.

  { config, stdenv, wrapper, wlib, ... }@initialArgs:
  {
    inherit (stdenv) mkDerivation;
    __functor = {
      mkDerivation,
      __functor,
      defaultPhases, # [ "<all stdenv phases>" ... ]
      setupPhases, # phases: "if [ -z \"${phases[*]:-}\" ]; then phases="etc..."; fi"
      runPhases, # "for curPhase in ${phases[*]}; do runPhase \"$curPhase\"; done"
      ...
    }@self:
    defaultArgs:
    defaultArgs // (if config.sourceStdenv then { } else { buildCommand = ""; }
  }

• If you do this:
  • You are in control over the entire derivation.
  • This means you need to take care of config.passthru and config.sourceStdenv yourself.
  • The mkDerivation function will be called with the final result of your functor.

As you can see, you are provided with some things to help you via the self argument to your functor.

The generated passthru items mentioned above are given to you as part of what is shown as defaultArgs above

And you are also given some helpers to help you run the phases if needed!

Tip: A functor is a set with a { __functor = self: args: ...; } field. You can call it like a function and it gets passed itself as its first argument!

Type: function that evaluates to a(n) (string or function that evaluates to a(n) attribute set of raw value)

Default:

<function, args: {config, lib, lndir, wlib, wrapper}>

Declared by:

• lib/core.nix

drv

Extra attributes to add to the resulting derivation.

Cannot affect passthru, or outputs. For that, use config.passthru, or config.outputs instead.

Also cannot override buildCommand. That is controlled by the config.builderFunction and config.sourceStdenv options.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

eval

Function to extend the current configuration with additional modules. Can accept a single module, or a list of modules. Re-evaluates the configuration with the original settings plus the new module(s).

Returns the raw lib.evalModules result

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function>

Declared by:

• lib/core.nix

exePath

The relative path to the executable to wrap. i.e. bin/exename

If not specified, the path gained from calling lib.getExe on config.package and subtracting the path to the package will be used.

Type: null or non-empty line

Default:

"bin/atool"

Declared by:

• lib/core.nix

extendModules

Alias for .extendModules so that you can call it from outside of wlib.types.subWrapperModule types

In addition, it is also a set which stores the function args for the module evaluation. This may prove useful when dealing with subWrapperModules or packages, which otherwise would not have access to some of them.

Type: (read-only) function that evaluates to a(n) raw value

Default:

<function, args: {modules?, prefix?, specialArgs?}>

Declared by:

• lib/core.nix

meta.description

Description of the module.

Accepts either a string, or a set of { pre ? "", post ? "" }

Resulting config value will be a list of { pre, post, file }

Type: string or { pre ? “”, post ? “” } (converted to [ { pre, post, file } ])

Default:

""

Declared by:

• lib/core.nix

meta.maintainers

Maintainers of this module.

Type: list of (open submodule of attrsRecursive)

Default:

[ ]

Declared by:

• lib/core.nix

meta.maintainers.*.email

email

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.github

GitHub username

Type: string

Declared by:

• lib/core.nix

meta.maintainers.*.githubId

GitHub id

Type: signed integer

Declared by:

• lib/core.nix

meta.maintainers.*.matrix

Matrix ID

Type: null or string

Default:

null

Declared by:

• lib/core.nix

meta.maintainers.*.name

name

Type: string

Default:

"‹name›"

Declared by:

• lib/core.nix

meta.platforms

Supported platforms

Type: list of strings from enum of lib.platforms.all

Default:

lib.platforms.all

Example:

[
  "x86_64-linux"
  "aarch64-linux"
]

Declared by:

• lib/core.nix

outputs

Override the list of nix outputs that get symlinked into the final package.

Default is config.package.outputs or [ "out" ] if invalid.

Type: non-empty list of string

Default:

[
  "out"
]

Declared by:

• lib/core.nix

overrides

the list of .override and .overrideAttrs to apply to config.package

Accessing config.package will return the package with all overrides applied.

Accepts a list of { data, type ? null, name ? null, before ? [], after ? [] }

If type == null then data must be a function. It will receive and return the package.

If type is a string like override or overrideAttrs, it represents the attribute of config.package to pass the data field to.

If a raw value is given, it will be used as the data field, and type will be null.

config.package = pkgs.mpv;
config.overrides = [
  { # If they don't have a name they cannot be targeted!
    type = "override";
    after = [ "MPV_SCRIPTS" ];
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.visualizer ];
    });
  }
  {
    name = "MPV_SCRIPTS";
    type = "override";
    data = (prev: {
      scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.modernz ];
    });
  }
  # the default `type` is `null`
  (pkg: pkg.override (prev: {
    scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.autocrop ];
  }))
  {
    type = null;
    before = [ "MPV_SCRIPTS" ];
    data = (pkg: pkg.override (prev: {
      scripts = (prev.scripts or []) ++ config.scripts;
    }));
  }
  { # It was already after "MPV_SCRIPTS" so this will stay where it is
    type = "overrideAttrs";
    after = [ "MPV_SCRIPTS" ];
    data = prev: {
      name = prev.name + "-wrapped";
    };
  }
];

The above will add config.scripts, then modernz then visualizer and finally autocrop

Then it will add -wrapped to the end of config.package’s name attribute.

The sort will not always put the value directly after the targeted value, it fulfils the requested before or after dependencies and no more.

You can modify the specs!

The type supports type merging, so you may redeclare it in order to add more options or change default values.

{ config, lib, wlib, pkgs, ... }:{
  options.overrides = lib.mkOption {
    type = wlib.types.seriesOf (wlib.types.spec ({ config, ... }: {
      options = {};
      config = {};
    }));
  };
}

Type: series of spec with main field: data of raw value

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.after

Items that this spec should be ordered after.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.before

Items that this spec should be ordered before.

Type: list of string

Default:

[ ]

Declared by:

• lib/core.nix

overrides.*.data

If type is null, then this is the function to call on the package.

If type is a string, then this is the data to pass to the function corresponding with that attribute.

Type: raw value

Declared by:

• lib/core.nix

overrides.*.name

The name for targeting from the before or after fields of other specs.

If null it cannot be targeted by other specs.

Type: null or string

Default:

null

Declared by:

• lib/core.nix

overrides.*.type

The attribute of config.package to pass the override argument to. If null, then data receives and returns the package instead.

If null, data must be a function. If a string, config.package must have the corresponding attribute, and it must be a function.

Type: null or one of “override”, “overrideAttrs” or string

Default:

null

Declared by:

• lib/core.nix

package

The base package to wrap. This means config.builderFunction will be responsible for inheriting all other files from this package (like man page, /share, …)

The config.package value given by this option already has all values from config.overrides applied to it.

Type: str|path|drv

Declared by:

• lib/core.nix

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. Anything added under the attribute name configuration will be ignored, as that value is used internally.

Type: attrsRecursive

Default:

{ }

Declared by:

• lib/core.nix

pkgs

The nixpkgs pkgs instance to use.

Required in order to access .wrapper attribute, either directly, or indirectly.

Type: Nixpkgs package set

Declared by:

• lib/core.nix

sourceStdenv

Run the enabled stdenv phases on the wrapper derivation.

NOTE: often you may prefer to use things like drv.doDist = true;, or even drv.phases = [ ... "buildPhase" etc ... ]; instead, to override this choice in a more fine-grained manner

Type: boolean

Default:

true

Declared by:

• lib/core.nix