nix-wrapper-modules
A Nix library to create wrapped executables via the module system.
Are you annoyed by rewriting modules for every platform? nixos, home-manager, nix-darwin, devenv?
Then this library is for you!
What is this for?
When configuring programs using nix, one of the highlights for most is the module system.
The main "configuration.nix" file of NixOS and "home.nix" for home-manager contain all sorts of shortlist options. For a while, it's great!
But then you need to use your configuration somewhere else. Pulling in your home-manager configuration on some other machine is usually overkill, takes too long, and is often a destructive action, as it will link files into the home directory and move the old files.
You don't want to pull in your entire home environment, you just needed to do some pair programming and wanted to use some of your tools, not destroy your co-workers dotfiles. Can't you make like, a shell, or a derivation or something and use that directly?
In addition, you often have some modules that might be duplicated because NixOS or home-manager options can be different. And you can't use any of that in a shell. It is starting to wear on you a bit.
So you hear about this thing called "wrapping" a package. This means, writing a script that launches the program with specific arguments or variables set, and installing that instead.
Then, you could have your configured tools as derivations you can just install via any means nix has of installing something.
Nix makes this concept very powerful, as you can create files and pull in other programs without installing them globally.
Your first attempt, you might write something that looks like this:
pkgs.writeShellScriptBin "alacritty" (let
tomlcfg = pkgs.writeText "alacritty.toml" ''
[terminal.shell]
program = "${pkgs.zsh}/bin/zsh"
args = [ "-l" ]
'';
in ''
exec ${pkgs.alacritty}/bin/alacritty --config-file ${tomlcfg} "$@"
'')
This is good! Kinda. If you install it, it will install the wrapper script instead of the program, and the script tells it where the config is! And it doesn't need home-manager or NixOS!
But on closer inspection, its missing a lot. What if this were a package with a few more things you could launch? Where is the desktop file? Man pages?
So, your next attempt might look more like this:
pkgs.symlinkJoin (let
tomlcfg = pkgs.writeText "alacritty.toml" ''
[terminal.shell]
program = "${pkgs.zsh}/bin/zsh"
args = [ "-l" ]
'';
in {
name = "alacritty";
paths = [ pkgs.alacritty ];
nativeBuildInputs = [ pkgs.makeWrapper ];
postBuild = ''
wrapProgram $out/bin/alacritty --add-flag --config-file --add-flag ${tomlcfg}
'';
})
Ok. So maybe that isn't your second try. But you get there eventually.
This is a little closer to how stuff like nixvim works, if you have heard of it. It just has a lot more on top of that.
But even this has problems. If you want to have any sensible ability to override this later, for example, you will need to add that ability yourself.
You also now have a desktop file that might point to the wrong place. And if all you wanted to do was set a setting or 2 and move on, all of that will still be necessary to deal with.
You eventually are reduced to going to the source code of a bunch of modules in nixpkgs or home-manager and copy pasting what they did into your wrapper.
What if I told you, you can solve all those problems, and gain a really nice, consistent, and flexible way to do this, and make sure it can always be overridden later?
And it uses something you already know! The module system!
inputs.nix-wrapper-modules.wrapperModules.alacritty.wrap {
inherit pkgs;
settings.terminal.shell.program = "${pkgs.zsh}/bin/zsh";
settings.terminal.shell.args = [ "-l" ];
}
The above snippet does everything the prior 2 examples did, and then some!
That's a full module (defined like this and with docs here) but just for that package, and the result is a fully portable derivation, just like the wrapper scripts above!
And you can call .wrap on it as many times as you want! You can define your own options
to easily toggle things for your different use cases and re-export it in a flake and change them on import, etc.
And you do not lose your ability to use .override or .overrideAttrs on the original package!
The arguments will be passed through to the value of config.package,
and the result will persist within the module system for future evaluations!
As a result it is safe to replace the vast majority of packages with their wrapped counterpart in an overlay directly.
There are included modules for several programs already, but there are rich and easy to use options defined for creating your own modules as well!
If you make one, you are encouraged to submit it here for others to use if you wish!
For more information on how to do this, check out the getting started documentation, and the descriptions of the module options you have at your disposal!
Long-term Goals
It is the ideal of this project to become a hub for everyone to contribute, so that we can all enjoy our portable configurations with as little individual strife as possible.
In service of that ideal, the immediate goal would be to transfer this repo to nix-community the moment that becomes an option.
Eventually I hope to have wrapper modules in nixpkgs, but again, nix-community would be the first step.
Short-term Goals
Help us add more modules! Contributors are what makes projects like these which contain modules for so many programs amazing!
Why rewrite lassulus/wrappers?
Yes, I know about this comic (xkcd 927), but it was necessary that I not heed the warning it gives.
For those paying attention to the recent nix news, you may have heard of a similar project which was released recently.
This excellent video by Vimjoyer was made, which mentions the project this one is inspired by at the end.
The video got that repository a good amount of attention. And the idea of the .apply interface was quite good, although I did implement it in my own way.
Most of the video is still applicable though! It is short and most of its runtime is devoted to explaining the problem being solved. So, if you still find yourself confused as to what problem this repository is solving, please watch it!
But the mentioned project gives you very little control from within the module system over what is being built as your wrapper derivation. (the thing you are actually trying to create)
It was designed around a module system which can supply some of the arguments of some separate builder function designed to be called separately, which itself does not give full control over the derivation.
This repository was designed around giving you absolute control over the derivation your wrapper is creating from within the module system, and defining modules for making the experience making wrapper modules great.
In short, this repo is more what it claims to be. A generalized and effective module system for creating wrapper derivations, and offers far more abilities to that effect to the module system itself.
In fact, the only attribute of the final derivation you cannot directly override is buildCommand.
And even for buildCommand you can still change its contents entirely if desired, although I think you will find wlib.modules.default provides very sensible defaults and that you will not need to do this yourself often.
This allows you to easily modify your module with extra files and scripts or whatever else you may need!
Maybe you want your tmux wrapper to also output a launcher script that rejoins a session, or creates one? You can do that using this project with, for example, a postBuild hook just like in a derivation, and you can even use "${placeholder "out"}" in it!
But you can supply it from within the module system! You could then define an option to customize its behavior later!
In addition, the way it is implemented allows for the creation of helper modules that wrap derivations in all sorts of ways, which you could import instead of wlib.modules.default if you wanted. We could have similar modules for wrapping projects via bubblewrap or into docker containers with the same ease with which this library orchestrates regular wrapper scripts.
It makes many more improvements as well, things like, ordering of flags on a fine-grained basis, customizing of escaping function per item, and more...
In short, while both projects have surface level similarities, you would be leaving a lot on the table to not use this one instead!
I did originally try to contribute my changes, but for numerous reasons, this did not work out.
The original changes suggested were not as sweeping as the changes made when rewriting it for this repository, and did not break any existing functionality.
That being said, contributing to a project by entirely rewriting it and then trying to get that accepted is not a good way to get changes to happen.
But nothing short of that would have made sense. The architecture was the problem, and the core of the project, which I was altering, was very short. Given that I was deleting one of the core features (the separate builder function), and rolling it directly into the module system, breaking it up further was not very possible without leaving it in a broken state.
Overview
This library provides two main components:
lib.evalModule: Function to create reusable wrapper modules with type-safe configuration options- And related,
lib.wrapPackage: an alias forevalModulewhich returns the package directly and pre-imports thewlib.modules.defaultmodule for convenience
- And related,
wrapperModules: Pre-built wrapper modules for common packages (tmux,wezterm, etc.)
Usage
Note: there are also template(s) you can access via nix flake init -t github:Birdeehub/nix-wrapper-modules
They will get you started with a module file and the default one also gives you a flake which imports it, for quickly testing it out!
Using Pre-built Wrapper Modules
{
inputs.wrappers.url = "github:BirdeeHub/nix-wrapper-modules";
outputs = { self, wrappers }: {
packages.x86_64-linux.default =
wrappers.wrapperModules.wezterm.wrap ({ lib, ... }: {
pkgs = wrappers.inputs.nixpkgs.legacyPackages.x86_64-linux;
luaInfo = {
keys = [
{
key = "F12";
mods = "SUPER|CTRL|ALT|SHIFT";
action = lib.generators.mkLuaInline "wezterm.action.Nop";
}
];
};
});
};
}
{
inputs.wrappers.url = "github:BirdeeHub/nix-wrapper-modules";
inputs.wrappers.inputs.nixpkgs.follows = "nixpkgs";
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
outputs = { self, nixpkgs, wrappers }: let
forAllSystems = with nixpkgs.lib; genAttrs platforms.all;
in {
packages = forAllSystems (system: {
default = wrappers.wrapperModules.mpv.wrap (
{config, wlib, lib, pkgs, ...}: {
pkgs = import nixpkgs { inherit system; };
scripts = [ pkgs.mpvScripts.mpris ];
"mpv.conf".content = ''
vo=gpu
hwdec=auto
'';
"mpv.input".content = ''
WHEEL_UP seek 10
WHEEL_DOWN seek -10
'';
}
);
});
};
}
Extending Configurations
The .eval function allows you to extend an already-applied configuration with additional modules, similar to extendModules in NixOS.
The .apply function works the same way, but automatically grabs .config from the result of .eval for you,
so you can have .wrap and .apply more easily available without evaluating.
The .wrap function works the same way, but automatically grabs .config.wrapper (the final package) from the result of .eval for you.
The package (via passthru) and the modules under .config both offer all 3 functions.
# Apply initial configuration
# you can use `.eval` `.apply` or `.wrap` for this.
initialConfig = (wrappers.wrapperModules.tmux.eval ({config, pkgs, ...}{
# but if you don't plan to provide pkgs yet, you can't use `.wrap` or `.wrapper` yet.
# config.pkgs = pkgs;
# but we can still use `pkgs` before that inside!
config.plugins = [ pkgs.tmuxPlugins.onedark-theme ];
config.clock24 = false;
})).config;
# Extend with additional configuration!
extendedConfig = initialConfig.apply {
modeKeys = "vi";
statusKeys = "vi";
vimVisualKeys = true;
};
# Access the wrapper!
# apply is useful because we don't need to give it `pkgs` but it gives us
# top level access to `.wrapper`, `.wrap`, `.apply`, and `.eval`
# without having to grab `.config` ourselves
actualPackage = extendedConfig.wrap { inherit pkgs; };
# since we didn't supply `pkgs` yet, we must pass it `pkgs`
# before we are given the new value of `.wrapper` from `.wrap`
# Extend it again! You can call them on the package too!
apackage = (actualPackage.eval {
prefix = "C-Space";
}).config.wrapper; # <-- `.wrapper` to access the package direcly
# and again! `.wrap` gives us back the package directly
# all 3 forms take modules as an argument
packageAgain = apackage.wrap ({config, pkgs, ...}: {
# list definitions append when declared across modules by default!
plugins = [ pkgs.tmuxPlugins.fzf-tmux-url ];
});
Creating Custom Wrapper Modules
{ wlib, lib }:
(wlib.evalModule ({ config, wlib, lib, pkgs, ... }: {
# You can only grab the final package if you supply pkgs!
# But if you were making it for someone else, you would want them to do that!
# config.pkgs = pkgs;
imports = [ wlib.modules.default ]; # <-- includes wlib.modules.symlinkScript and wlib.modules.makeWrapper
options = {
profile = lib.mkOption {
type = lib.types.enum [ "fast" "quality" ];
default = "fast";
description = "Encoding profile to use";
};
outputDir = lib.mkOption {
type = lib.types.str;
default = "./output";
description = "Directory for output files";
};
};
config.package = pkgs.ffmpeg;
config.flags = {
"-preset" = if config.profile == "fast" then "veryfast" else "slow";
};
config.env = {
FFMPEG_OUTPUT_DIR = config.outputDir;
};
})) # .config.wrapper to grab the final package! Only works if pkgs was supplied.
wrapProgram comes with wlib.modules.default already included, and outputs the package directly!
Use this for quickly creating a custom wrapped program within your configuration!
{ pkgs, wrappers, ... }:
wrappers.lib.wrapProgram ({ config, wlib, lib, ... }: {
inherit pkgs; # you can only grab the final package if you supply pkgs!
package = pkgs.curl;
extraPackages = [ pkgs.jq ];
env = {
CURL_CA_BUNDLE = "${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt";
};
flags = {
"--silent" = true;
"--connect-timeout" = "30";
};
flagSeparator = "="; # Use --flag=value instead of --flag value (default is " ")
runShell = [
''
echo "Making request..." >&2
''
];
})
Troubleshooting
If your package is failing at the step where it actually builds the final derivation, even with basic usage such as:
wlib.wrapPackage { inherit pkgs; package = pkgs.niri; }
error: Cannot build '/nix/store/8gi38b4750xiinahnzbv2y9r76gp17bp-niri.drv'.
Reason: builder failed with exit code 1.
Output paths:
/nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri
/nix/store/z8h2j2g8cqldwd7hjxm3vd4rxf04bk8p-niri-doc
Last 12 log lines:
> /nix/store/dbgpyfkf1z9a1pvpr8nq17qgzl33ab8r-niri-25.11/bin:
> niri: File exists
> Patching self-references in specified files...
> Running phase: updateAutotoolsGnuConfigScriptsPhase
> Running phase: updateAutotoolsGnuConfigScriptsPhase
> Running phase: buildPhase
> Running phase: installPhase
> Running phase: fixupPhase
> shrinking RPATHs of ELF executables and libraries in /nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri
> checking for references to /build/ in /nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri...
> moving /nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri/lib/systemd/user/* to /nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri/share/systemd/user
> mv: '/nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri/lib/systemd/user/niri-shutdown.target' and '/nix/store/8xjhbi4xnjd9g4gnjhjbi0yx52y814iy-niri/share/systemd/user/niri-shutdown.target' are the same file
You will want to disable the stdenv fixupPhase for the wrapper derivation like this:
wlib.wrapPackage { inherit pkgs; package = pkgs.niri; drv.dontFixup = true; }
This will not disable the fixupPhase for the package, but rather, the fixupPhase for the wrapper derivation,
which in some cases can come into conflict with the one from the package.
However, this will also prevent drv.preFixup and drv.postFixup hooks from running.
This issue may be fixed in the future, for more info, see this github issue
Core (builtin) Options set
These are the core options that make everything else possible.
They include the .apply, .eval, and .wrap functions, and the .wrapper itself
They are always imported with every module evaluation.
They are very minimal by design.
The default symlinkScript value provides no options.
The default wrapperFunction is null.
wlib.modules.default provides great values for these options, and creates many more for you to use.
But you may want to wrap your package via different means, provide different options, or provide modules for others to use to help do those things!
Excited to see what ways to use these options everyone comes up with! Docker helpers? BubbleWrap? If it's a derivation, it should be possible!
package
The base package to wrap.
This means config.symlinkScript will be responsible
for inheriting all other files from this package
(like man page, /share, …)
The config.package value given by this option already has all
values from config.overrides applied to it.
Type: package
Declared by:
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: function that evaluates to a(n) raw value (read only)
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.
If set as an empty string, symlinkScript or wrapperFunction may behave unpredictably, depending on its implementation.
Type: string
Default:
"hello"
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.symlinkScript
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: function that evaluates to a(n) raw value (read only)
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.
If set as an empty string, symlinkScript or wrapperFunction may behave unpredictably, depending on its implementation.
Type: string
Default:
"bin/hello"
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
meta.maintainers.*.github
GitHub username
Type: string
meta.maintainers.*.githubId
GitHub id
Type: signed integer
meta.maintainers.*.matrix
Matrix ID
Type: null or string
Default:
null
meta.maintainers.*.name
name
Type: string
Default:
"‹name›"
meta.platforms
Supported platforms
Type: list of 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 the value of config.package.outputs or [ "out" ]
Type: 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 { type, data, name ? null, before ? [], after ? [] }
type is a string like override or overrideAttrs
config.package = pkgs.mpv;
config.overrides = [
{
after = [ "MPV_SCRIPTS" ];
type = "override";
data = (prev: {
scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.visualizer ];
});
}
{
name = "MPV_SCRIPTS";
type = "override";
data = (prev: {
scripts = (prev.scripts or []) ++ config.scripts;
});
}
{
type = "override";
data = (prev: {
scripts = (prev.scripts or []) ++ [ pkgs.mpvScripts.autocrop ];
});
}
];
The above will add config.scripts, then pkgs.mpvScripts.visualizer and finally pkgs.mpvScripts.autocrop
Type: DAG LIST (with extra field: `type`) of (attribute set of raw value) or function that evaluates to a(n) attribute set of raw value
Default:
[ ]
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: unspecified value
Declared by:
sourceStdenv
Whether to call $stdenv/setup to set up the environment before the symlinkScript
If any phases are enabled, also runs the enabled phases after the config.symlinkScript command has ran.
NOTE: often you may prefer to use things like drv.dontFixup = true;,
or even drv.phases = [ ... "buildPhase" etc ... ]; instead,
to override this choice in a more fine-grained manner
Type: boolean
Default:
true
Declared by:
symlinkScript
Outside of importing wlib.modules.symlinkScript module,
which is included in wlib.modules.default,
This is usually an option you will never have to redefine.
This option takes a function receiving the following arguments:
module arguments + wrapper + pkgs.callPackage
{
wlib,
config,
wrapper,
... # <- anything you can get from pkgs.callPackage
}:
The function is to return a string which will be added to the buildCommand of the wrapper.
It is in charge of 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 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.
If it returns a function, 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.override,
passthru.overrideAttrs, and config.sourceStdenv will be handled for you.
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:
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: function that evaluates to a(n) package (read only)
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: package (read only)
Default:
<derivation hello>
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 symlinkScript 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:
wlib.modules.default
This module imports both wlib.modules.makeWrapper and wlib.modules.symlinkScript for convenience
wlib.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.
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.
wlib.modules.symlinkScript
Adds extra options compared to the default symlinkScript option value.
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib documentation
Generated documentation for the wlib library.
Contains the main module evaluation function, and various other useful items.
wlib main set documentation
wlib.evalModules
calls nixpkgs.lib.evalModules with the core module imported and wlib added to specialArgs
wlib.evalModules takes the same arguments as nixpkgs.lib.evalModules
wlib.evalModule
evalModule = module: wlib.evalModules { modules = if builtins.isList module then module else [ module ]; };
Evaluates the module along with the core options, using lib.evalModules
Takes a module as its argument. Returns the result from lib.evalModules directly.
To submit a module to this repo, this function must be able to evaluate it.
The wrapper module system integrates with NixOS module evaluation:
- Uses
lib.evalModulesfor configuration evaluation - Supports all standard module features (imports, conditionals, mkIf, etc.)
- Provides
configfor accessing evaluated configuration - Provides
optionsfor introspection and documentation
wlib.wrapModule
Creates a reusable wrapper module.
Imports wlib.modules.default then evaluates the module. It then returns .config so that .wrap is easily accessible!
Use this when you want to quickly create a wrapper but without providing it a pkgs yet.
Equivalent to:
wrapModule = (wlib.evalModule wlib.modules.default).config.apply;
Example usage:
helloWrapper = wrapModule ({ config, wlib, pkgs, ... }: {
options.greeting = lib.mkOption {
type = lib.types.str;
default = "hello";
};
config.package = pkgs.hello;
config.flags = {
"--greeting" = config.greeting;
};
};
# This will return a derivation that wraps the hello package with the --greeting flag set to "hi".
helloWrapper.wrap {
pkgs = pkgs;
greeting = "hi";
};
wlib.wrapPackage
Imports wlib.modules.default then evaluates the module. It then returns the wrapped package.
Use this when you want to quickly create a wrapped package directly. Requires a pkgs to be set.
Equivalent to:
wrapModule = (wlib.evalModule wlib.modules.default).config.wrap;
wlib.mkOutOfStoreSymlink
mkOutOfStoreSymlink :: pkgs -> path -> { out = ...; ... }
Lifted straight from home manager, but requires pkgs to be passed to it first.
Creates a symlink to a local absolute path, does not check if it is a store path first.
Returns a store path that can be used for things which require a store path.
wlib.getPackageOutputsSet
getPackageOutputsSet :: Derivation -> AttrSet
Given a package derivation, returns an attribute set mapping each of its output names (e.g. "out", "dev", "doc") to the corresponding output path.
This is useful when a wrapper or module needs to reference multiple outputs of a single derivation. If the derivation does not define multiple outputs, an empty set is returned.
Example: getPackageOutputsSet pkgs.git => { out = /nix/store/...-git; man = /nix/store/...-git-man; }
wlib.escapeShellArgWithEnv
Escape a shell argument while preserving environment variable expansion.
This escapes backslashes and double quotes to prevent injection, then
wraps the result in double quotes.
Unlike lib.escapeShellArg which uses single quotes, this allows
environment variable expansion (e.g., $HOME, ${VAR}).
Caution! This is best used by the nix backend for wlib.modules.makeWrapper to escape things,
because the shell and binary implementations pass their args to pkgs.makeWrapper at build time,
so allowing variable expansion may not always do what you expect!
Example
escapeShellArgWithEnv "$HOME/config.txt"
=> "\"$HOME/config.txt\""
escapeShellArgWithEnv "/path/with\"quote"
=> "\"/path/with\\\"quote\""
escapeShellArgWithEnv "/path/with\\backslash"
=> "\"/path/with\\\\backslash\""
wlib.dag set documentation
wlib.dag.dagOf
A directed acyclic graph of some inner type.
Arguments:
elemType:type
Accepts an attrset of elements
The elements should be of type elemType
or sets of the type { data, name ? null, before ? [], after ? [] }
where the data field is of type elemType
name defaults to the key in the set.
Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap
Note, if the element type is a submodule then the name argument
will always be set to the string "data" since it picks up the
internal structure of the DAG values. To give access to the
"actual" attribute name a new submodule argument is provided with
the name dagName.
The config.optionname value from the associated option
will be normalized such that all items are DAG entries
If you wish to alter the type, you may provide different options
to wlib.dag.dagWith by updating this type wlib.dag.dagOf // { strict = false; }
wlib.dag.dagWith
Arguments:
-
settings:strict ? true:falseaddsfreeformType = wlib.types.attrsRecursiveand adjusts the conversion logic to accomodate. See Notes section below.defaultNameFn ? ({ config, name, isDal, ... }@moduleArgs: if isDal then null else name): Function to compute the defaultnamefor entries. Recieves the submodule arguments.dataTypeFn?(elemType: { config, name, isDal, ... }@moduleArgs: elemType): Can be used if the type of thedatafield needs to depend upon the submodule arguments.dontConvertFunctions ? false:trueallows passing function-type submodules as dag entries. If yourdatafield's type may contain a function, or is a submodule type itself, this should be left asfalse.- ...other arguments for
lib.types.submoduleWith(modules,specialArgs, etc...) Passed through to configure submodules in the DAG entries.
-
elemType:typeThe type of the DAG entries’datafield. You can provide the type, OR an entry for each item. In the resultingconfig.optionnamevalue, all items are normalized into entries.
Notes:
dagWithaccepts an attrset as its first parameter (thesettings) beforeelemType.- Setting
strict = falseallows entries to have unchecked extra attributes beyonddata,name,before, andafter. If your item is a set, and might have adatafield, you will want to keepstrict = trueto avoid false positives. - To add extra type-checked fields, use the
modulesattribute, which is passed through tosubmoduleWith. The allowed dag fields will be automatically generated from the base set of modules passed. - The
config.optionnamevalue from the associated option will be normalized so that all items become valid DAG entries. - If
elemTypeis a submodule, anddataTypeFnis not provided, adagNameargument will automatically be injected to access the actual attribute name.
wlib.dag.dalOf
A DAG LIST or (DAL) or dependency list of some inner type
Arguments:
elemType:type
Accepts a LIST of elements
The elements should be of type elemType
or sets of the type { data, name ? null, before ? [], after ? [] }
where the data field is of type elemType
If a name is not given, it cannot be targeted by other values.
Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap
Note, if the element type is a submodule then the name argument
will always be set to the string "data" since it picks up the
internal structure of the DAG values. To give access to the
"actual" attribute name a new submodule argument is provided with
the name dagName.
The config.optionname value from the associated option
will be normalized such that all items are DAG entries
If you wish to alter the type, you may provide different options
to wlib.dag.dalWith by updating this type wlib.dag.dalOf // { strict = false; }
wlib.dag.dalWith
Arguments:
-
settings:strict ? true:falseaddsfreeformType = wlib.types.attrsRecursiveand adjusts the conversion logic to accomodate. See Notes section below.defaultNameFn ? ({ config, name, isDal, ... }@moduleArgs: if isDal then null else name): Function to compute the defaultnamefor entries. Recieves the submodule arguments.dataTypeFn?(elemType: { config, name, isDal, ... }@moduleArgs: elemType): Can be used if the type of thedatafield needs to depend upon the submodule arguments.dontConvertFunctions ? false:trueallows passing function-type submodules as dag entries. If yourdatafield's type may contain a function, or is a submodule type itself, this should be left asfalse.- ...other arguments for
lib.types.submoduleWith(modules,specialArgs, etc...) Passed through to configure submodules in the DAG entries.
-
elemType:typeThe type of the DAL entries’datafield. You can provide the type, OR an entry for each item. In the resultingconfig.optionnamevalue, all items are normalized into entries.
Notes:
dalWithaccepts an attrset as its first parameter (thesettings) beforeelemType.- Setting
strict = falseallows entries to have UNCHECKED extra attributes beyonddata,name,before, andafter. If your item is a set, and might have adatafield, you will want to keepstrict = trueto avoid false positives. - To add extra type-checked fields, use the
modulesattribute, which is passed through tosubmoduleWith. The allowed dag fields will be automatically generated from the base set of modules passed. - The
config.optionnamevalue from the associated option will be normalized so that all items become valid DAG entries. - If
elemTypeis a submodule, anddataTypeFnis not provided, adagNameargument will automatically be injected to access the actual attribute name.
wlib.dag.isEntry
Determines whether a value is a valid DAG entry (allows extra values)
wlib.dag.isDag
determines whether a value is of the attrset type and all values are dag entries
Allows entries to have extra values
wlib.dag.isDal
determines whether a value is of the list type and all values are dag entries
Allows entries to have extra values
wlib.dag.topoSort
Takes an attribute set containing entries built by entryAnywhere, entryAfter, and entryBefore to a topologically sorted list of entries.
Alternatively, it can take a dal (dependency list) instead.
Which is a list of such entries.
Requires values to all be DAG entries (in other words, have a value.data field)
Internally this function uses the topoSort function in
<nixpkgs/lib/lists.nix> and its value is accordingly.
Specifically, the result on success is
{ result = [ { name = ?; data = ?; } … ] }
For example
nix-repl> topoSort {
a = entryAnywhere "1";
b = entryAfter [ "a" "c" ] "2";
c = entryBefore [ "d" ] "3";
d = entryBefore [ "e" ] "4";
e = entryAnywhere "5";
} == {
result = [
{ data = "1"; name = "a"; }
{ data = "3"; name = "c"; }
{ data = "2"; name = "b"; }
{ data = "4"; name = "d"; }
{ data = "5"; name = "e"; }
];
}
true
And the result on error is
{
cycle = [ { after = ?; name = ?; data = ? } … ];
loops = [ { after = ?; name = ?; data = ? } … ];
}
For example
nix-repl> topoSort {
a = entryAnywhere "1";
b = entryAfter [ "a" "c" ] "2";
c = entryAfter [ "d" ] "3";
d = entryAfter [ "b" ] "4";
e = entryAnywhere "5";
} == {
cycle = [
{ after = [ "a" "c" ]; data = "2"; name = "b"; }
{ after = [ "d" ]; data = "3"; name = "c"; }
{ after = [ "b" ]; data = "4"; name = "d"; }
];
loops = [
{ after = [ "a" "c" ]; data = "2"; name = "b"; }
];
}
true
dag
: Function argument
wlib.dag.gmap
Applies a function to each element of the given DAG.
Requires values to all be DAG entries (in other words, have a value.data field)
wlib.dag.mapDagToDal
wlib.dag.gmap but returns the result as a DAL
Requires values to all be DAG entries (in other words, have a value.data field)
wlib.dag.dagToDal
converts a DAG to a DAL
Requires values to all be DAG entries (in other words, have a value.data field)
wlib.dag.lmap
Applies a function to each element of the given DAL.
Requires values to all be DAG entries (in other words, have a value.data field)
wlib.dag.entryBetween
Creates a DAG entry with specified before and after dependencies.
wlib.dag.entryAnywhere
Create a DAG entry with no particular dependency information.
wlib.dag.entryAfter
Convenience function to create a DAG entry that should come after certain nodes.
wlib.dag.entryBefore
Convenience function to create a DAG entry that should come before certain nodes.
wlib.dag.entriesBetween
Given a list of entries, this function places them in order within the DAG. Each entry is labeled "${tag}-${entry index}" and other DAG entries can be added with 'before' or 'after' referring these indexed entries.
The entries as a whole can be given a relation to other DAG nodes. All generated nodes are then placed before or after those dependencies.
wlib.dag.entriesAnywhere
Convenience function for creating multiple entries without specific dependencies.
wlib.dag.entriesAfter
Convenience function for creating multiple entries that must be after another entry
wlib.dag.entriesBefore
Convenience function for creating multiple entries that must be before another entry
wlib.dag.sortAndUnwrap
Convenience function for resolving a DAG or DAL and getting the result in a sorted list of DAG entries
Unless you make use of mapIfOk, the result is still a DAL, but sorted.
Arguments:
{
name ? "DAG", # for error message
dag,
mapIfOk ? null,
}
Requires values to all be DAG entries (in other words, have a value.data field)
wlib.types set documentation
wlib.types.dalOf
A DAG LIST or (DAL) or dependency list of some inner type
Arguments:
elemType:type
Accepts a LIST of elements
The elements should be of type elemType
or sets of the type { data, name ? null, before ? [], after ? [] }
where the data field is of type elemType
If a name is not given, it cannot be targeted by other values.
Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap
Note, if the element type is a submodule then the name argument
will always be set to the string "data" since it picks up the
internal structure of the DAG values. To give access to the
"actual" attribute name a new submodule argument is provided with
the name dagName.
The config.optionname value from the associated option
will be normalized such that all items are DAG entries
If you wish to alter the type, you may provide different options
to wlib.dag.dalWith by updating this type wlib.types.dalOf // { strict = false; }
wlib.types.dagOf
A directed acyclic graph of some inner type.
Arguments:
elemType:type
Accepts an attrset of elements
The elements should be of type elemType
or sets of the type { data, name ? null, before ? [], after ? [] }
where the data field is of type elemType
name defaults to the key in the set.
Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap
Note, if the element type is a submodule then the name argument
will always be set to the string "data" since it picks up the
internal structure of the DAG values. To give access to the
"actual" attribute name a new submodule argument is provided with
the name dagName.
The config.optionname value from the associated option
will be normalized such that all items are DAG entries
If you wish to alter the type, you may provide different options
to wlib.dag.dagWith by updating this type wlib.types.dagOf // { strict = false; }
wlib.types.dalWithEsc
same as dalOf except with an extra field esc-fn
esc-fn is to be null, or a function that returns a string
used by wlib.modules.makeWrapper
wlib.types.dagWithEsc
same as dagOf except with an extra field esc-fn
esc-fn is to be null, or a function that returns a string
used by wlib.modules.makeWrapper
wlib.types.stringable
Type for a value that can be converted to string "${like_this}"
used by wlib.modules.makeWrapper
wlib.types.fixedList
Arguments:
length:int,elemType:type
It's a list, but it rejects lists of the wrong length.
Still has regular list merge across multiple definitions, best used inside another list
wlib.types.wrapperFlags
Arguments:
length:int,
len: wlib.types.dalOf (wlib.types.fixedList len wlib.types.stringable)
wlib.types.wrapperFlag
DAL (list) of (stringable or list of stringable)
More flexible than wlib.types.wrapperFlags, allows single items, or lists of items of varied length
wlib.types.file
File type with content and path options
Arguments:
pkgs: nixpkgs instance
Fields:
content: File contents as stringpath: Derived path using pkgs.writeText
wlib.types.attrsRecursive
Like lib.types.anything, but allows contained lists to also be merged
wlib.types.withPackagesType
The kind of type you would provide to pkgs.lua.withPackages or pkgs.python3.withPackages
This type is a function from a set of packages to a list of packages.
If you set it in multiple files, it will merge the resulting lists according to normal module rules for a listOf package.
wlib.modules
In this subsection are what we will call "helper modules".
They are just regular modules. The distinction is that they do not set config.package
Instead, their purpose is to create convenience options for you to use to define your own wrappers!
The example you will become most familiar with are the helper modules imported by wlib.modules.default
wlib.modules.default gets its options by importing 2 other modules, wlib.modules.symlinkScript and wlib.modules.makeWrapper.
But you could choose to have modules that have different abilities!
For example, someone may want to make a set of convenience options for wrapping your program with bubblewrap or some other sandboxing tool instead!
They could make a module for that, and submit it here for everyone to enjoy!
wlib.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.
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.modules.symlinkScript
Adds extra options compared to the default symlinkScript 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:
wlib.wrapperModules
wrapper modules are modules which set config.package and define convenience options for wrapping that package with a configuration.
They are specific to that program, and make configuring programs in an ad-hoc way stress-free!
They include shortlist options for common configuration settings, and/or for providing a config file to use.
wlib.wrapperModules contains paths to these wrapper modules.
The flake also exports wrapper modules that have been partially evaluated for convenience.
This allows you to do something like inputs.nix-wrapper-modules.wrapperModules.tmux.wrap { inherit pkgs; prefix = "C-Space"; }, to build a package with a particular configuration quickly!
You can then export that package, and somebody else could call .wrap on it as well to change it again!
wlib.wrapperModules.alacritty
settings
Configuration of alacritty.
See alacritty(5) or https://alacritty.org/config-alacritty.html
Type: TOML value
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.foot
settings
Configuration of foot terminal.
See foot.ini(5)
Type: attribute set of section of an INI file (attrs of INI atom (null, bool, int, float or string))
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.fuzzel
settings
Configuration of fuzzel.
See fuzzel.ini(5)
Type: attribute set of section of an INI file (attrs of INI atom (null, bool, int, float or string))
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.git
Nix uses git for all sorts of things. Including fetching flakes!
So if you put this one in an overlay, name it something other than pkgs.git!
Otherwise you will probably get infinite recursion.
The vast majority of other packages do not have this issue. And,
due to the passthrough of .override and .overrideAttrs,
most other packages are safe to replace with their wrapped counterpart in overlays directly.
configFile
Generated git configuration file.
Type: submodule
Default:
{
path = <derivation gitconfig>;
}
Declared by:
configFile.content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
configFile.path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
settings
Git configuration settings.
See git-config(1) for available options.
Type: attribute set of attribute set of (INI atom (null, bool, int, float or string) or attribute set of (INI atom (null, bool, int, float or string)))
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.helix
extraSettings
Extra lines appended to the config file. This can be used to maintain order for settings.
Type: strings concatenated with “\n”
Default:
""
Declared by:
ignores
List of paths to be ignored by the file-picker. The format is the same as in .gitignore.
Type: list of non-empty string
Default:
[ ]
Declared by:
languages
Language specific settings See https://docs.helix-editor.com/languages.html
Type: TOML value
Default:
{ }
Declared by:
settings
General settings See https://docs.helix-editor.com/configuration.html
Type: TOML value
Default:
{ }
Declared by:
themes
Themes to add to config. See https://docs.helix-editor.com/themes.html
Type: attribute set of (TOML value or strings concatenated with “\n”)
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.jujutsu
settings
Configuration for jujutsu. See https://jj-vcs.github.io/jj/latest/config/
Type: TOML value
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.mako
"--config"
Path to the generated Mako configuration file.
The file is built automatically from the settings option using the
iniWithGlobalSection formatter. You can override this path to use a
custom configuration file instead.
Example: –config=/etc/mako/config
Type: submodule
Default:
{
path = <derivation mako-settings>;
}
Declared by:
"--config".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"--config".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
settings
Configuration settings for mako. Can include both global settings and sections. All available options can be found here: https://github.com/emersion/mako/blob/master/doc/mako.5.scd.
Type: attribute set of (INI atom (null, bool, int, float or string) or attribute set of (INI atom (null, bool, int, float or string)))
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.mpv
"mpv.conf"
The main MPV configuration file.
Provide .content to inline configuration options or .path to reference an existing mpv.conf.
This file controls playback behavior, default options, video filters, and output settings.
It is included by MPV using the --include flag.
Type: submodule
Default:
{
content = "";
}
Declared by:
"mpv.conf".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"mpv.conf".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
"mpv.input"
The MPV input configuration file.
Provide .content to inline bindings or .path to use an existing input.conf.
This file defines custom key bindings and command mappings.
It is passed to MPV using --input-conf.
Type: submodule
Default:
{
content = "";
}
Declared by:
"mpv.input".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"mpv.input".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
scripts
A list of MPV user scripts to include via package override.
Each entry should be a derivation providing a Lua script or plugin
compatible with MPV’s scripts/ directory.
These are appended to MPV’s build with pkgs.mpv.override.
Type: list of package
Default:
[ ]
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.notmuch
configFile
Path or inline definition of the generated Notmuch configuration file.
By default, this is automatically created from the settings option
using the INI format generator.
Type: submodule
Default:
{
path = "/nix/store/rvl2f91wxz2h2ws42y7v42hgzxs44xq0-notmuch.ini";
}
Declared by:
configFile.content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
configFile.path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
settings
INI-style configuration for Notmuch.
This option defines the contents of the notmuch.ini configuration file.
Use attribute sets to specify sections and key-value pairs.
Example:
settings = {
user = { name = "Alice"; primary_email = "alice@example.org"; };
database = { path = "Maildir"; };
};
Type: attribute set of section of an INI file (attrs of INI atom (null, bool, int, float or string))
Default:
{
database = {
mail_root = "Maildir";
path = "Maildir";
};
}
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.nushell
"config.nu"
The main Nushell configuration file.
Provide either .content to inline the file contents or .path to reference an existing file.
This file is passed to Nushell using --config, and controls general shell behavior,
key bindings, and built-in command settings.
Type: submodule
Default:
{
content = "";
}
Declared by:
"config.nu".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"config.nu".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
"env.nu"
The Nushell environment configuration file.
Provide either .content to inline the file contents or .path to reference an existing file.
This file is passed to Nushell using --env-config, and is typically used to define
environment variables or startup commands that apply to all shells.
Type: submodule
Default:
{
content = "";
}
Declared by:
"env.nu".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"env.nu".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.opencode
settings
Sets OPENCODE_CONFIG for github:sst/opencode
Type: JSON value
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.rofi
"config.rasi"
The main Rofi configuration file (config.rasi).
Provide either .content to inline the generated Rasi text or .path to reference an external file.
By default this file is auto-generated from the values in settings and the selected theme.
It is passed to Rofi using -config.
Type: submodule
Default:
{
content = ''
configuration {
location: 0;
xoffset: 0;
yoffset: 0;
}
'';
}
Declared by:
"config.rasi".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"config.rasi".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
plugins
List of rofi plugins to be installed
Type: list of package
Default:
[ ]
Declared by:
settings
Configuration settings for rofi.
Type: (attribute set of (string or signed integer or boolean or (Rasi literal string) or list of (string or signed integer or boolean or (Rasi literal string)))) or string
Default:
{
location = 0;
xoffset = 0;
yoffset = 0;
}
Declared by:
theme
The Rofi theme specification.
Can be:
- a string or path to an existing
.rasitheme file, - or an attribute set describing Rasi sections and key/value pairs.
When an attribute set is provided, it is rendered to Rasi syntax automatically.
The theme is included in "config.rasi" via an @theme directive.
Type: null or string or absolute path or attribute set of ((attribute set of (string or signed integer or boolean or (Rasi literal string) or list of (string or signed integer or boolean or (Rasi literal string)))) or string)
Default:
null
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.tealdeer
settings
Configuration of tealdeer. See <tealdeer-rs.github.io/tealdeer/config.html>
Type: TOML value
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.tmux
aggressiveResize
Value for setw -g aggressive-resize.
Type: boolean
Default:
false
Declared by:
allowPassthrough
Value for set -gq allow-passthrough.
Type: boolean
Default:
true
Declared by:
baseIndex
Value for set -g base-index.
Type: signed integer
Default:
1
Declared by:
clock24
use 24 hour clock instead of 12 hour clock
Type: boolean
Default:
true
Declared by:
configAfter
configuration to run after all tmux plugins are sourced
Type: strings concatenated with “\n”
Default:
""
Declared by:
configBefore
configuration to run before all tmux plugins are sourced
Type: strings concatenated with “\n”
Default:
""
Declared by:
disableConfirmationPrompt
disable the confirmation prompt for kill-window and kill-pane keybindings.
Type: boolean
Default:
true
Declared by:
displayPanesColour
Value for set -g display-panes-colour.
Type: string
Default:
"default"
Declared by:
escapeTime
Value for set -s escape-time.
Type: signed integer
Default:
500
Declared by:
historyLimit
Value for set -g history-limit.
Type: signed integer
Default:
2000
Declared by:
modeKeys
Value for set -g mode-keys.
Type: string
Default:
"emacs"
Declared by:
mouse
Enable mouse mode.
Type: boolean
Default:
true
Declared by:
paneBaseIndex
Value for setw -g pane-base-index.
Type: signed integer
Default:
1
Declared by:
plugins
List of tmux plugins to source.
Type: list of (package or (submodule))
Default:
[ ]
Declared by:
prefix
Set the prefix key for tmux.
Type: string
Default:
"C-b"
Declared by:
secureSocket
Store tmux socket under /run, which is more
secure than /tmp, but as a downside it doesn’t
survive user logout.
Type: boolean
Default:
false
Declared by:
setEnvironment
attrset of environment variables to set when the tmux session is created.
set-environment -g ${key} "${value}"
Type: attribute set of (string or package)
Default:
{ }
Declared by:
shell
set -g default-shell
Type: null or string
Default:
null
Declared by:
sourceSensible
Start with defaults from tmuxPlugins.sensible
Type: boolean
Default:
true
Declared by:
statusKeys
Value for set -g status-keys.
Type: string
Default:
"emacs"
Declared by:
terminal
Value for set -g default-terminal.
Type: string
Default:
"screen"
Declared by:
terminalOverrides
Value for set -ga terminal-overrides.
Type: null or string
Default:
null
Declared by:
updateEnvironment
List of environment variables to update when the tmux session is created.
set-option -ga update-environment <your list of variables>
Type: list of string
Default:
[
"TERM"
"TERM_PROGRAM"
]
Declared by:
vimVisualKeys
v and y keybindings for copy-mode-vi.
Type: boolean
Default:
false
Declared by:
visualActivity
Value for set -g visual-activity.
Type: boolean
Default:
false
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.wezterm
lua
The lua derivation used to evaluate the luaEnv option
Type: package
Default:
<derivation luajit-2.1.1741730670>
Declared by:
luaEnv
extra lua packages to add to the lua environment for wezterm
value is to be a function from config.lua.pkgs to list
config.lua.withPackages config.luaEnv
The result will be added to package.path and package.cpath
Type: function that evaluates to a(n) list of package
Default:
<function>
Declared by:
luaInfo
anything other than uncalled nix functions can be put into this option,
within your "wezterm.lua", you will be able to call require('nix-info')
and get the values as lua values
the default "wezterm.lua".content value is return require('nix-info')
This means, by default, this will act like your wezterm config file, unless you want to add some lua in between there.
${placeholder "out"} is useable here and will point to the final wrapper derivation
You may also call require('nix-info')(defaultval, "path", "to", "item")
This will help prevent indexing errors when querying nested values which may not exist.
Type: lua value
Default:
{ }
Declared by:
"wezterm.lua"
The wezterm config file. provide .content, or .path
Type: submodule
Default:
{
content = "return require('nix-info')";
}
Declared by:
"wezterm.lua".content
Content of the file. This can be a multi-line string that will be written to the Nix store and made available via the path option.
Type: strings concatenated with “\n”
Declared by:
"wezterm.lua".path
The path to the file. By default, this is automatically generated using pkgs.writeText with the attribute name and content.
Type: str|path|drv
Default:
"pkgs.writeText name <content>"
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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:
wlib.wrapperModules.xplr
defaultConfigLang
The default config language to use for generated config segments. Does not affect the luaInfo option.
Type: one of “fnl”, “lua”
Default:
"lua"
Declared by:
infopath
The default require path for the result of the luaInfo option. Don’t change this unless you have a really good reason to.
Type: string
Default:
"nix-info"
Declared by:
lua
The lua derivation used to evaluate the luaEnv option
Type: package
Default:
<derivation luajit-2.1.1741730670>
Declared by:
luaEnv
extra lua packages to add to the lua environment for xplr
value is to be a function from config.lua.pkgs to list
config.luaEnv = lp: [ lp.inspect ];
The result will be added to package.path and package.cpath
Type: function that evaluates to a(n) list of package
Default:
<function>
Declared by:
luaInfo
luaInfo is a Lua table that can hold arbitrary data you want to expose to your Lua environment.
This table is automatically converted to Lua code and made available under require "nix-info".
config.defaultConfigLang does NOT affect this value.
the name nix-info can be changed via config.infopath option
Type: lua value
Default:
{ }
Declared by:
luaInit
luaInit is a flexible configuration option for providing Lua code that will be executed when the Lua environment for xplr is initialized.
It can be either a simple string of Lua code or a structured DAG (directed acyclic graph) of Lua code snippets with dependencies between them.
The dag type has an extra opts field that can be used to pass in options to the lua code.
It is like the config.luaInfo option, but per entry.
You can then receive it in .data with local opts, name = ...
{ data, after ? [], before ? [], opts ? {}, enable ? true, plugin ? null, type ? config.defaultConfigLang }
Example usage:
luaEnv = lp: [ lp.inspect ];
luaInit.WillRunEventually = ''
print([[
you can also just put a string if you currently don't need opts,
don't have ordering requirements, etc...
config.luaInit.WillRunEventually.data will be this string.
You can still add other stuff later.
]])
'';
luaInit.TESTFILE_1 = {
opts = { testval = 1; };
data = /* lua */''
local opts, name = ...
print(name, require("inspect")(opts), "${placeholder "out"}")
return opts.hooks -- xplr configurations can return hooks
'';
};
luaInit.TESTFILE_2 = {
opts = { testval = 2; };
after = [ "TESTFILE_1" ];
type = "fnl";
data = /* fennel */ ''
(local (opts name) ...)
(print name ((require "inspect") opts) "${placeholder "out"}")
(. opts hooks) ;; xplr configurations can return hooks
'';
};
Here, TESTFILE_1 runs before TESTFILE_2, with their respective options passed in.
WillRunEventually will run at some point, but when is not specified. It could even run between TESTFILE_1 and TESTFILE_2
The resulting generated file is given the name GENERATED_WRAPPER_LUA in the DAG for the config.flags and config.addFlag options, and it is added using -c or --config flag.
xplr accepts an arbitrary number of config files passed via the -C or --extra-config flag to extend this configuration, so you may pass extra yourself if you wish.
Type: string or (DAG (with extra fields: `enable`, `opts`, `plugin`, `type`) of strings concatenated with “\n”)
Default:
{ }
Declared by:
plugins
Will be symlinked into a directory added to the LUA_PATH and LUA_CPATH
The name of the plugin via require will be the dag name for the value.
The name in config.infopath is not allowed (default nix-info)
Type: DAG (with extra field: `enable`) of str|path|drv
Default:
{ }
Declared by:
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:
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv or list of str|path|drv
Default:
[ ]
Example:
[
"-v"
"-f"
[
"--config"
"\${./storePath.cfg}"
]
[
"-s"
"idk"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/somewhere/on/your/machine";
}
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: DAG (with extra field: `esc-fn`) of str|path|drv
Default:
{ }
Example:
{
XDG_DATA_HOME = "/only/if/not/set";
}
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: DAG (with extra fields: `esc-fn`, `sep`) of null or boolean or str|path|drv or list of str|path|drv
Default:
{ }
Example:
{
"--config" = "\${./nixPath}";
}
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
prefixVar
–prefix ENV SEP VAL
Prefix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
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: DAG LIST (with extra field: `esc-fn`) of str|path|drv
Default:
[ ]
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: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Declared by:
suffixVar
–suffix ENV SEP VAL
Suffix ENV with VAL, separated by SEP.
Type: DAG LIST (with extra field: `esc-fn`) of (List of length 3)
Default:
[ ]
Example:
[
[
"LD_LIBRARY_PATH"
":"
"\${lib.makeLibraryPath (with pkgs; [ ... ])}"
]
[
"PATH"
":"
"\${lib.makeBinPath (with pkgs; [ ... ])}"
]
]
Declared by:
unsetVar
–unset VAR
Remove VAR from the environment.
Type: DAG LIST (with extra field: `esc-fn`) of string
Default:
[ ]
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: