`wlib.makeWrapper` set documentation

`wlib.makeWrapper.wrapAll`

The default config.wrapperFunction value for the wlib.modules.makeWrapper module

Generates build instructions for wrapping the main target and all enabled variants.

Usage:

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

Arguments:

pkgs (set either this or callPackage): Package set providing callPackage.
callPackage (set either this or pkgs): calls the wrapper builder.
config (required): Configuration attribute set.
wrapperImplementation (optional): Path or function for the wrapper implementation.

Requirements on config:

Must define wrapperPaths.input, wrapperPaths.placeholder, wrapperPaths.relDir, outputName.
May include options from wlib.modules.makeWrapper.

Behavior:

Wraps the main target and all enabled variants.
Wraps the path at config.wrapperPaths.input
Outputs it to config.wrapperPaths.placeholder
Wraps the paths at config.wrapperVariants.*.wrapperPaths.input
Outputs to config.wrapperVariants.*.wrapperPaths.placeholder

Returns: A string containing build instructions to append to a derivation.

It also takes as an argument wrapperImplementation

You may define a function that receives config, wlib, and arguments from callPackage and returns a string of build instructions, that follows similar behavior.

You may use the other functions in wlib.makeWrapper to help with this.

`wlib.makeWrapper.wrapMain`

Generates build instructions for wrapping only the main target.

Usage:

  wlib.makeWrapper.wrapMain {
    inherit config;
    inherit (pkgs) callPackage; # or `inherit pkgs`;
  };

Arguments:

pkgs (set either this or callPackage): Package set providing callPackage.
callPackage (set either this or pkgs): calls the wrapper builder.
config (required): Configuration attribute set.
wrapperImplementation (optional): Path or function for the wrapper implementation.

Requirements on config:

Must define wrapperPaths.input, wrapperPaths.placeholder, wrapperPaths.relDir, outputName.
May include options from wlib.modules.makeWrapper.

Behavior:

Wraps only the main target (no variants).
Wraps the path at config.wrapperPaths.input
Outputs to config.wrapperPaths.placeholder

Returns: A string containing build instructions to append to a derivation.

It also takes as an argument wrapperImplementation

You may define a function that receives config, wlib, and arguments from callPackage and returns a string of build instructions, that follows similar behavior.

You may use the other functions in wlib.makeWrapper to help with this.

structured function argument

pkgs: Function argument
callPackage: Function argument
config: Function argument
wrapperImplementation: Function argument

`wlib.makeWrapper.wrapVariants`

Generates build instructions for wrapping all enabled variants, excluding the main target.

Usage:

  wlib.makeWrapper.wrapVariants {
    inherit config;
    inherit (pkgs) callPackage; # or `inherit pkgs`;
  };

Arguments:

pkgs (set either this or callPackage): Package set providing callPackage.
callPackage (set either this or pkgs): calls the wrapper builder.
config (required): Configuration attribute set.
wrapperImplementation (optional): Path or function for the wrapper implementation.

Requirements on config:

Must define wrapperPaths.input, wrapperPaths.placeholder, wrapperPaths.relDir, outputName.
Must define wrapperVariants as an attribute set.
May include options from wlib.modules.makeWrapper.

Behavior:

Wraps all variants in config.wrapperVariants.
Variants with enable = false are excluded.
Wraps the paths at config.wrapperVariants.*.wrapperPaths.input
Outputs to config.wrapperVariants.*.wrapperPaths.placeholder

Returns: A string containing build instructions to append to a derivation.

It also takes as an argument wrapperImplementation

You may define a function that receives config, wlib, and arguments from callPackage and returns a string of build instructions, that follows similar behavior.

You may use the other functions in wlib.makeWrapper to help with this.

structured function argument

pkgs: Function argument
callPackage: Function argument
config: Function argument
wrapperImplementation: Function argument

`wlib.makeWrapper.wrapVariant`

Generates build instructions for wrapping a single variant.

Usage:

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

Arguments:

pkgs (set either this or callPackage): Package set providing callPackage.
callPackage (set either this or pkgs): calls the wrapper builder.
config (required): Configuration attribute set.
wrapperImplementation (optional): Path or function for the wrapper implementation.
name (required): String name of a variant attribute in config.wrapperVariants.

Requirements on config:

Must define wrapperPaths.input, wrapperPaths.placeholder, wrapperPaths.relDir, outputName.
May include options from wlib.modules.makeWrapper.

Behavior:

Wraps only the specified variant.
Asserts that name is a string.
If the selected variant has enable = false, it is excluded.
Wraps the path at config.wrapperVariants.${name}.wrapperPaths.input
Outputs to config.wrapperVariants.${name}.wrapperPaths.placeholder

Returns: A string containing build instructions to append to a derivation.

It also takes as an argument wrapperImplementation

You may define a function that receives config, wlib, and arguments from callPackage and returns a string of build instructions, that follows similar behavior.

You may use the other functions in wlib.makeWrapper to help with this.

structured function argument

pkgs: Function argument
callPackage: Function argument
config: Function argument
wrapperImplementation: Function argument
name: Function argument

`wlib.makeWrapper.aggregateSingleOptionSet`

Aggregates a single wrapper option set (either the top-level config or one of the entries from config.wrapperVariants) into a unified DAG-like list (DAL).

Usage:

  wlib.makeWrapper.aggregateSingleOptionSet {
    inherit config;
    sortResult = true; # optional
  };

Arguments:

config (required): An attribute set containing wrapper options. This may be the top-level wrapper configuration or a single variant’s option set.
sortResult (optional, default: true): Whether to sort the resulting DAL using wlib.dag.unwrapSort "makeWrapper".

Behavior:

Collects the following wrapper option categories from config:
- unsetVar
- env
- envDefault
- prefixVar
- suffixVar
- prefixContent
- suffixContent
- chdir
- runShell
- flags
- addFlag
- appendFlag
Normalizes each entry into a consistent structure containing:
- type — the originating option category
- data — primary value
- before/after/name — DAG sorting values
- esc-fn — not yet applied, may be null.
- value — original value
- 3 more which are only present for some types:
  - sep/ifs — flags option-specific metadata (only included for type == flags)
  - attr-name — (on attribute-style options) original attribute name (can’t be overriden from within the spec)
Attribute-based option sets (e.g. env, flags) are converted into lists with their attribute names preserved.
If sortResult = true, the combined list is then sorted according to DAG ordering rules via wlib.dag.unwrapSort.

Returns: A list (DAL) of normalized option entries suitable for further processing (e.g., splitting with splitDal or transforming with fixArgs).

`wlib.makeWrapper.splitDal`

splitDal receives the dal as returned by aggregateSingleOptionSet and splits it into 2 lists, args and other.

It returns a set with args and other attributes, containing the same format of items as aggregateSingleOptionSet returns.

It puts all type == "flags", "addFlag", or "appendFlag" into args, and anything else into other.

args are almost always necessarily separate from the way anything else gets set, so a helper exists to separate them.

DAL: Function argument

`wlib.makeWrapper.fixArgs`

Normalizes and resolves argument-related entries from a DAL into concrete addFlag and appendFlag lists.

Usage:

wlib.makeWrapper.fixArgs {
  sep = "=";  # optional default separator
  ifs = ",";  # optional default inner-field separator
} argsDAL;

Arguments:

1st argument, a set with:
- sep (optional, default: null): Default separator used when a flags entry does not define its own sep. If null, flags and values may be emitted as separate arguments depending on configuration.
- ifs (optional, default: null): Default inner-field separator used when a flags entry does not define its own ifs and the value is a list.
- fixPreFlagSort (optional, default: true): Sorts the flags and addFlag values again after concatenating them, thus ensuring that it all still works like 1 DAL.
2nd argument (required): A list of DAL entries, typically the args attribute returned by splitDal, but may also be the full DAL.

Behavior:

Identifies entries of type:
- “flags”
- “addFlag”
- “appendFlag”
Converts all "flags" entries into "addFlag" entries.
For each "flags" entry:
- Uses entry-specific sep and ifs if defined.
- Otherwise falls back to the provided sep and ifs options.
Handles flag value forms:
- Boolean flags (true → standalone flag, false/null → omitted)
- Single scalar values
- Lists of values
Applies separator logic:
- If both sep and ifs are set and the value is a list, emits a single argument with joined values.
- If sep is set but ifs is null, emits one argument per list element using the separator.
- If sep is null and ifs is set, emits the flag name followed by a joined value string.
- If both are null, emits flag and value(s) as separate arguments.
Preserves existing "addFlag" and "appendFlag" entries.

Returns: An attribute set containing:

{
  addFlag = [ ... ];    # fully expanded and converted flags
  appendFlag = [ ... ]; # append-style flag entries
}

Intended to be called after splitDal and before final wrapper command generation.

Keyboard shortcuts

nix-wrapper-modules