wlib.wrapperModules.mdbook
wrapperModules/m/mdbook
This module is made possible by: birdee
This module makes use of wrapperVariants to make a script for each of the books you define.
If you make an entry in the books attribute set, you will get a binary of that name,
which as its first argument takes the output directory to generate to (or a default if not provided).
As each one already has its book directory specified and -d option set to the first argument or a default,
you only have access to the other flags on these items at runtime.
To achieve greater runtime control, run the main executable with one of the generated books within the derivation
as input yourself, either at runtime, or within the module via ${placeholder "out"}/${config.book-out-dir}/${name}
Within the module, there is an option called mainBook to REPLACE the main executable with a symlink to the desired book generation script.
For more fine-tuned control, you should instead give it the path to the book yourself as demonstrated above.
book-out-dir
The books are generated to:
${placeholder "out"}/${config.book-out-dir}/${name}
Type: (read-only) string
Default:
"mdbook-book-dir"
Declared by:
books
Type: attribute set of (submodule)
Default:
{ }
Declared by:
books.<name>.book
Values for the book.toml file for this book.
Reference: rust-lang.github.io/mdBook/format/configuration/general.html
Any null values will be as if not declared.
Type: open submodule of (nullable TOML value)
Default:
{ }
Declared by:
books.<name>.book.book
The book table of the book.toml file.
Reference: rust-lang.github.io/mdBook/format/configuration/general.html#general-metadata
Type: open submodule of (nullable TOML value)
Declared by:
books.<name>.book.book.authors
The author(s) of the book
Type: null or (list of string)
Default:
null
Declared by:
books.<name>.book.book.description
A description for the book, which is added as meta information in the html <head> of each page
Type: null or string
Default:
null
Declared by:
books.<name>.book.book.language
The main language of the book, which is used as a
language attribute <html lang="en"> for example.
This is also used to derive the direction of text (RTL, LTR) within the book.
Type: null or non-empty string
Default:
null
Declared by:
books.<name>.book.book.src
By default, the source directory is found in the directory named src directly under the root folder.
Type: non-empty string
Default:
"src"
Declared by:
books.<name>.book.book.text-direction
The direction of text in the book: Left-to-right (LTR) or Right-to-left (RTL).
Possible values: ltr, rtl.
When not specified, the text direction is derived from the book’s language attribute.
Type: null or non-empty string
Default:
null
Declared by:
books.<name>.book.book.title
The title of the book
Type: null or string
Default:
null
Declared by:
books.<name>.defaultOutLocation
The book outputs take the target directory to generate to as their first argument.
This sets the default output directory for this book if the first argument is not supplied.
Type: string
Default:
"_site"
Declared by:
books.<name>.enable
Whether to enable the book ‹name›.
Type: boolean
Default:
true
Example:
true
Declared by:
books.<name>.generated-book-subdir
The directory within the wrapped derivation that contains the generated markdown for the book.
${placeholder "out"}/${config.books.<name>.generated-book-subdir} is the root of this book.
Type: (read-only) string
Default:
"mdbook-book-dir/‹name›"
Declared by:
books.<name>.summary
Builds your summary, and your book!
A list of specs, with the main field, data,
representing the type of the item.
Accepts prefix, suffix, title, numbered, draft, separator
For info on what those are:
rust-lang.github.io/mdBook/format/summary
In addition, it accepts name, subchapters, src, and path.
These values are processed differently depending on the type of item.
path refers to the output path src will be linked to.
It is relative to the book root dir.
name is the visible part of the summary item, if it displays text.
You can also sort based on name, before, and after like the other DAL options.
It will sort within each chapter list if any orderings were specified.
subchapters are processed recursively, and the depth represents the indentation of the summary item.
Type:
list of spec with main field: data of (one of “prefix”, “suffix”, “title”, “numbered”, “draft”, “separator”)
Default:
[ ]
Declared by:
books.<name>.summary.*.after
Ensure this item appears after the named entries in this list
Type: list of string
Default:
[ ]
Declared by:
books.<name>.summary.*.before
Ensure this item appears before the named entries in this list
Type: list of string
Default:
[ ]
Declared by:
books.<name>.summary.*.build
If extra processing is required to generate a source file for this item, you may specify extra commands to run before the wrapper links it into place here.
Type: strings concatenated with “\n”
Default:
""
Declared by:
books.<name>.summary.*.data
Identifies the kind of summary item.
This determines how the item is rendered in SUMMARY.md and which additional fields are required or meaningful.
Valid values are:
title — A section heading in the summary.
separator — A horizontal rule (—) separating sections. (can be defined simply as the string “separator” in the list unless you want to sort on them)
prefix — A link rendered before the main numbered chapters.
suffix — A link rendered after the main numbered chapters.
numbered — A standard numbered chapter entry.
draft — A chapter entry without a target path.
Rendering behavior and required fields depend on this value.
Type: one of “prefix”, “suffix”, “title”, “numbered”, “draft”, “separator”
Declared by:
books.<name>.summary.*.name
The name of the summary item. Usually rendered as the text of the item.
Can also be used as a sorting target by before and after fields of other items.
Type: null or string
Default:
null
Declared by:
books.<name>.summary.*.path
The relative output path of the item within the book directory.
Type: null or non-empty line
Default:
null
Declared by:
books.<name>.summary.*.src
If this item is of a type which accepts a source file,
this file will be linked to the location indicated by the path option.
Type: null or str|path|drv
Default:
null
Declared by:
books.<name>.summary.*.subchapters
The same options as this level of the summary, however the items within will be indented 1 level further.
Type:
list of spec with main field: data of (one of “prefix”, “suffix”, “title”, “numbered”, “draft”, “separator”)
Default:
[ ]
Declared by:
mainBook
If not null, replace the main package with a link to the generator script for that book
Type: null or non-empty line
Default:
null
Declared by:
modules/symlinkScript
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:
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:
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/makeWrapper
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
flagSeparator
Separator between flag names and values when generating args from flags.
" " for --flag value or "=" for --flag=value
Type: string
Default:
" "
Declared by:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
unsetVar
–unset VAR
Remove VAR from the environment.
Type:
list of spec with main field: data of string
Default:
[ ]
Declared by:
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:
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:
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:
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:
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:
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:
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:
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:
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:
wrapperVariants.<name>.binName
The name of the file to output to $out/bin/
Type: non-empty line
Default:
"‹name›"
Declared by:
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:
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:
wrapperVariants.<name>.enable
Enables the wrapping of this variant
Type: boolean
Default:
true
Declared by:
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:
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:
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:
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:
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:
wrapperVariants.<name>.exePath
The location within the package of the thing to wrap.
Type: null or non-empty line
Default:
"bin/‹name›"
Declared by:
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:
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:
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:
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:
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:
wrapperVariants.<name>.mirror
Allows the variant to inherit defaults from the top level
Type: boolean
Default:
true
Declared by:
wrapperVariants.<name>.package
The package to wrap with these options
Type: str|path|drv
Default:
<derivation mdbook-0.5.2>
Declared by:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
wrapperVariants.<name>.unsetVar
–unset VAR
Remove VAR from the environment.
Type:
list of spec with main field: data of string
Default:
[ ]
Declared by:
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:
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:
lib/core.nix
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:
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:
"mdbook"
Declared by:
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)
mkDerivationfield.
{ 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.passthruandconfig.sourceStdenvyourself. - The
mkDerivationfunction 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:
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:
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:
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/mdbook"
Declared by:
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:
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:
meta.maintainers
Maintainers of this module.
Type: list of (open submodule of attrsRecursive)
Default:
[ ]
Declared by:
meta.maintainers.*.email
Type: null or string
Default:
null
Declared by:
meta.maintainers.*.github
GitHub username
Type: string
Declared by:
meta.maintainers.*.githubId
GitHub id
Type: signed integer
Declared by:
meta.maintainers.*.matrix
Matrix ID
Type: null or string
Default:
null
Declared by:
meta.maintainers.*.name
name
Type: string
Default:
"‹name›"
Declared by:
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:
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:
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:
overrides.*.after
Items that this spec should be ordered after.
Type: list of string
Default:
[ ]
Declared by:
overrides.*.before
Items that this spec should be ordered before.
Type: list of string
Default:
[ ]
Declared by:
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:
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:
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:
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:
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:
pkgs
The nixpkgs pkgs instance to use.
Required in order to access .wrapper attribute,
either directly, or indirectly.
Type: Nixpkgs package set
Declared by:
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:
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:
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 mdbook-0.5.2>
Declared by:
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: