% COMMAND-WRAPPER-DIRENV-LIBRARY(7) Bash Library | v1.0.0 % Peter Trsko % 19th March 2020
command-wrapper-direnv-library - Direnv library for Command Wrapper
integration with Direnv.
Library that provides basic functions to build a Command Wrapper subcommand, in
Bash, that respects Command Wrapper Subcommand Protocol (see
command-wrapper-subcommand-protocol(7) manual page for details).
Some of the functions provided by the library are documented in this manual page, however, it is not in any way comprehensive documentation. See LIBRARY DOCUMENTATION section on how to access documentation embedded in the library.
Command Wrapper provides snippet of code that describes the best way to import
its Direnv library in .envrc files. Paste output of the following command
into your script:
TOOLSET_COMMAND completion --library --direnv --importFor more information see command-wrapper-completion(1) manual page.
In Vim/Neovim you can use following ex command to insert the code snippet
(don't forget to substitute TOOLSET_COMMAND with what you're using):
:r!TOOLSET_COMMAND completion --library --direnv --importDirenv library is self-documented, the easiest way how to see the embedded
documentation is to run (if you're using less as pager, if not read further):
TOOLSET_COMMAND completion --library --direnv [--content] | lessWhen we're not using less then change the last command in the pipeline to be
your preferred pager. If we're on Debian-like system then you can also use
sensible-pager command instead of directly calling a specific one.
If bat, or any other cat-like command
with syntax highlighting functionality is installed, then it is better to use:
TOOLSET_COMMAND completion --library --direnv [--content] | bat -l bashWhere -l is short for --language and allows bat to use syntax
highlighting for Bash.
For more information see command-wrapper-completion(1) manual page.
Basic Command Wrapper toolset configuration in Direnv environment is done by
use\_command\_wrapper function invoked via use Direnv clause. See USAGE
and EXAMPLES subsections on how to invoke it.
See USING AND CACHING ADDITIONAL CONFIGURATION FILES section for additional customisation of configuration of toolset and its subcommands.
use command_wrapper TOOLSET_NAME CONFIG_DIR
TOOLSET_NAME : Name of the toolset we setting up environment for.
CONFIG_DIR
: Project-specific (local environment setup by direnv) configuration
directory for Command Wrapper. Directory ${CONFIG_DIR}/${TOOLSET_NAME}
is where the toolset will be looking for its configuration.
What should be in `${CONFIG_DIR}`:
```
${CONFIG_DIR}/
├── config/
│ ├── ${toolset}/
│ │ ├── default/
│ │ │ └── constructor.dhall
│ │ └── default.dhall <<< Will be generated by this function if
│ │ 'default/constructor.dhall' exists.
│ └── lib/
│ ├── CommandWrapper <<< Will be generated by this function.
│ ├── Exec <<< Will be generated by this function.
│ ├── Prelude <<< Will be generated by this function.
│ └── * <<< Local Dhall library used by configs.
│ These are optional.
├── libexec/
│ └── ${TOOLSET_NAME}-* <<< Additional subcommands. This directory
│ is optional, therefore,
│ 'config/${toolset}/default/constructor.dhall'
│ is expected to reference it for it to be
│ used.
│
└── man/ <<< Additional manual pages. This directory
├── man1/ is optional, therefore,
│ └── *.1[.gz] 'config/${toolset}/default/constructor.dhall'
└── man7/ is expected to reference it for it to be
└── *.7[.gz] used.
```
If you're using version control system then make sure that generated
files are ignored.Environment variable that are constant even if we are using multiple toolsets
start with COMMAND_WRAPPER_ prefix. Those that are toolset-specific start
with a ${TOOLSET_PREFIX}_ string, where ${TOOLSET_PREFIX} is the name of
the toolset converted to upper case and all non-alphanumerical character
exchanged for '_' character. For example, if our toolset is named
this-is-my-toolset:number-1 then the value of ${TOOLSET_PREFIX} will be
THIS_IS_MY_TOOLSET_NUMBER_1.
COMMAND_WRAPPER_PRELUDE_LIB
: Dhall expression representing Dhall Prelude library.
Usage example:
```Dhall
let Prelude = env:COMMAND_WRAPPER_PRELUDE_LIB
let List/map = Prelude.List.map
in List/map
```COMMAND_WRAPPER_LIB
: Dhall expression representing Command Wrapper Dhall library.
Library is documented on
<https://github.com/trskop/command-wrapper/tree/master/command-wrapper/dhall/CommandWrapper>.COMMAND_WRAPPER_EXEC_LIB
: Dhall expression representing Command Wrapper Exec Dhall library.
Library is documented on
<https://github.com/trskop/command-wrapper/tree/master/command-wrapper/dhall/Exec>.${TOOLSET_PREFIX}_BASH_COMPLETION
: Variable contains file path to Bash completion for a specific toolset
indicated by TOOLSET_PREFIX. Value of TOOLSET_PREFIX is the name of
the toolset converted to upper case and all non-alphanumerical character
exchanged for '_' character.
Usage example for toolset named `dev-tools`:
```Bash
source "${DEV_TOOLS_BASH_COMPLETION}"
```${TOOLSET_PREFIX}_FISH_COMPLETION
: Variable contains file path to Fish completion for a specific toolset
indicated by TOOLSET_PREFIX. Value of TOOLSET_PREFIX is the name of
the toolset converted to upper case and all non-alphanumerical character
exchanged for '_' character.
${TOOLSET_PREFIX}_ZSH_COMPLETION
: Variable contains file path to Zsh completion for a specific toolset
indicated by TOOLSET_PREFIX. Value of TOOLSET_PREFIX is the name of
the toolset converted to upper case and all non-alphanumerical character
exchanged for '_' character.
COMMAND_WRAPPER_LOCAL_CONFIG_DIR
: This is set to the value CONFIG_DIR passed to use command_wrapper.
Toolset will then look for its configuration in:
```Bash
${COMMAND_WRAPPER_LOCAL_CONFIG_DIR}/${TOOLSET}
```
More information about this environment variable can be found in
`command-wrapper(1)` manual page.Snipped of .envrc that configures Command Wrapper toolset named yx. Notice
that it needs to be already available in PATH, i.e. if Direnv is installing
it, via e.g. Nix, then that has to be done before.
# ...
# shellcheck source=/dev/null
source <(yx completion --library --direnv --content)
use command_wrapper 'yx' './.command-wrapper'
# ...With Nix setup you may want to write output of this command:
TOOLSET completion --library --direnv --contentInto a file and expose path to it in an environment variable:
COMMAND_WRAPPER_DIRENV_LIBWith that setup the .envrc setup would look like:
# ...
# shellcheck source=/dev/null
source "${COMMAND_WRAPPER_DIRENV_LIB}"
use command_wrapper 'yx' './.command-wrapper'
# ...Same as Direnv's watch_file, but allows to specify multiple file paths at the
same time.
Q: Why not use direnv_layout_dir?
A: There's a lot of stuff that can be safely shared beteween invocations and Direnv environments when content hash is part of the generated file name.
watch_files [FILE ...]
FILE : File path of a file which should be watched by Direnv for changes. If its contents change Direnv will reload the environment.
Get the value of Command Wrapper cache directory for given toolset and Direnv purposes.
Real content is stored in directory returned by:
command_wrapper_dhall_cache TOOLSET_NAMEThat allows us to safely share content between different environments since Dhall files stored there contain integrity hash in their name.
command_wrapper_cache_dir TOOLSET_NAME
TOOLSET_NAME : Name of the toolset we setting up environment for.
Create a cached Dhall expression.
command_wrapper_dhall_cache TOOLSET_NAME FILE_NAME TARGET_DIR [INPUT_FILE]
TOOLSET_NAME : Name of the toolset we setting up environment for.
FILE_NAME : Base name of the file that we are creating, i.e. it doesn't contain any path separators (e.g. slashes).
TARGET_DIR : Where the resulting symbolic link is created.
INPUT_FILE
: If provided then command_wrapper_dhall_cache will read this file
instead of standard input. Be aware that when standard input is read
then the content can be arbitrary Dhall expression whereas INPUT_FILE
has to be a file path.
command-wrapper(1), command-wrapper-completion(1), command-wrapper-config(1)
bat(1), less(1)
batis a variant ofcatcommand with various improvements includingsyntax-highlightingand automatic pager support.