Aqua Env - Sustainable Envs

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

Aquaenv is a macOS (only) utility, making shell-environment available to Aqua (macOS GUI) applications. It is designed to be run as a persistent LaunchAgent daemon for each user. Environment variables can be white-listed (i.e. marked for exporting), and files can be watched in order to refresh the exported environment variables (e.g. re-exporting 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 is launched, it calls up the login-shell (auto detected) of the current user to determine the variables to be exported, 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.

As an option, configuration files can be watched, to re-export the shell-environment based on configuration changes (e.g. editing the configuration file of your shell).

The configuration file of Aquaenv is automatically watched.

Installation

Rust is required.

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

For Nix see: See https://github.com/bwolf/aquaenv.nix.

Aquaenv can be configured to be started automatically start up 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. uninstalled) via aquaenv -u, which unloads the plist and deletes 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 (array of strings): environment variables from the shell to be exported.
• watch (array of strings): files to be watched for configuration changes.

Exemplary configuration for zsh

defaults write org.antbear.aquaenv whitelist -array \
    XDG_CONFIG_HOME \
    XDG_CACHE_HOME \
    XDG_DATA_HOME \
    CARGO_HOME \
    RUSTUP_HOME

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

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

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

Output:

<?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 setting 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 the

• Apache License, Version 2.0 (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)

or the

• MIT license (LICENSE-MIT / http://opensource.org/licenses/MIT).