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 ? {}, disabled ? false, plugin ? null, type ? config.defaultConfigLang }
Example usage:
luaEnv = lp: [ lp.inspect ];
luaInit.WillRunEventually = "print('you can also just put a string if you dont want opts or need to run it before or after another')";
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 field(s): `disabled`, `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(s): `disabled`) 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(s): `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(s): `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(s): `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(s): `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(s): `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 field(s): `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.
Values may contain environment variable references using $ to expand at runtime
Type: DAG LIST (with extra field(s): `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(s): `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(s): `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.
Values may contain environment variable references using $ to expand at runtime
Type: DAG LIST (with extra field(s): `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(s): `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(s): `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: