Aqua Env - Sustainable Envs

Aquaenv makes the shell-environment available to Aqua (macOS GUI) applications.

Aquaenv is a macOS (only) utility which makes shell-environment available to Aqua (macOS GUI) applications. It is designed to be run as a persistent LaunchAgent daemon per user. Environment variables can be white-listed (marked to be exported) and files can watched in order to refresh the exported environment (e.g. re-export the environment variables when a shell configuration file is changed).

Aquaenv has no user interface. The Configuration is performed using the standard defaults command line tool. See below.

Inner workings

When Aquaenv starts, it calls the login shell (auto detected) of the current user to determine the exported variables, filters the variables by the configured whitelist and exports the remaining variables to launchd via launchctl setenv VARIABLE VALUE. This process is called exporting the shell-environment.

Optionally, configuration files can be watched, to re-export the shell-environment on configuration changes (e.g. editing your shells configuration file).

The configuration file of Aquaenv is automatically watched.

Installation

Rust is required.

shell cargo install aquaenv aquaenv -i defaults write org.antbear.aquaenv whitelist -array-add \ MY_IMPORTANT_VAR1 \ MY_IMPORTANT_VAR2

Aquaenv can be configured to be started automatically as LaunchAgent via aquaenv -i. The plist file will be created at ~/Library/Preferences/org.antbear.aquaenv.plist and launchd will be instructed to start the agent.

The installation can be reversed (i.e. uninstall) via aquaenv -u, which unloads the plist and removes it.

Logging is enabled and outputted to the file ~/Library/Logs/aquaenv.log. The time-stamps of the log-file are written in UTC.

Configuration

A empty default configuration is created during the first startup. It contains no white-listed environment variables and no files to be watched. Only SHELL_PATH will be exported (the original PATH of the shell).

Aquaenv is configured in the domain org.antbear.aquaenv. It supports the following configuration keys:

• whitelist (type: array of strings): environment variables from shell to be exported.
• watch (type: array of strings): files to be watched for configuration changes.

Example configuration for zsh

``` shell defaults write org.antbear.aquaenv whitelist -array \ XDGCONFIGHOME \ XDGCACHEHOME \ XDGDATAHOME \ CARGOHOME \ RUSTUPHOME

defaults write org.antbear.aquaenv watch -array \ $HOME/.zshenv \ $HOME/.zshrc ```

For completeness, the above configuration manifests in the following XML configuration which is shown via plutil as follows:

shell plutil -convert xml1 -o /dev/stdout \ ~/Library/Preferences/org.antbear.aquaenv.plist

Output:

xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>watch</key> <array> <string>/Users/user/.zshenv</string> <string>/Users/user/.zshrc</string> </array> <key>whitelist</key> <array> <string>XDG_CONFIG_HOME</string> <string>XDG_CACHE_HOME</string> <string>XDG_DATA_HOME</string> <string>CARGO_HOME</string> <string>RUSTUP_HOME</string> </array> </dict> </plist>

Limitations

Launchd does not support to set the PATH because launchd ignores the PATH set via launchctl setenv PATH foo:bar. As a bonus, Aquaenv exports the PATH as the variable SHELL_PATH, which can be used in configurable applications like GNU Emacs via custom configuration.

License

Aquaenv is licensed under either of - Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) - MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.