https://github.com/steamclock/steamclenv
A library for handling environment variables in Swift
https://github.com/steamclock/steamclenv
Last synced: 3 months ago
JSON representation
A library for handling environment variables in Swift
- Host: GitHub
- URL: https://github.com/steamclock/steamclenv
- Owner: steamclock
- License: mit
- Created: 2023-03-14T18:49:22.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-02T20:45:46.000Z (over 1 year ago)
- Last Synced: 2025-11-20T04:03:10.619Z (7 months ago)
- Language: Swift
- Size: 63.5 KB
- Stars: 0
- Watchers: 9
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SteamclEnv
A library to make handling environment variables in Swift a little bit Nicer.
- [Usage](#usage)
- [Using `generate`](#using-generate)
- [Interfacing with CI](#interfacing-with-ci)
- [Bitrise](#bitrise)
- [Xcode Cloud](#xcode-cloud)
- [Installation](#installation)
- [License](#license)
# Usage
SteamclEnv is a small CLI tool that contains two main commands: `generate` to generate your `Environment.swift` file, usually via a build script when developing locally, and `ci-helper` to reproduce the same behaviour with various CI tools. See [interfacing with CI](#interfacing-with-ci) below for more info on the latter.
## Using `generate`
After [installation](#installation), you can call `steamclenv generate` and have things ✨just work✨, but we provide some additional options if desired:
| Command | Short | Description |
| ------ | ------ | ---------- |
| --debug | n/a | Toggle debug mode, which prints more information out to the console while running the script. |
| --dev | -d | Use `.env.dev` rather than `.env`. This is superseded by --path if provided. |
| --output-path | -o | Path your output file should write to, relative to your current directory. You can include a full or partial path. File name will default to Environment.swift if not provided. |
| --path | -p | Path to your environment file, relative to the current directory. This overrides --dev. |
| --plain-text | n/a | Turns off variable obfuscation. See [obfuscation](#obfuscation) for more information. |
## Obfuscation
Inspired by the folks at [NSHipster](https://nshipster.com/secrets/), by default the values generated in your `Environment.swift` file are obfuscated.
You can pass in the `--plain-text` command to turn this off if desired. While this isn't a perfect solution by any means, it adds a small but worthwhile layer of obscurity that's worth including.
# Interfacing with CI
SteamclEnv includes a `ci-helper` command that generates shell scripts to produce your Environment.swift in CI. We current support run scripts for Bitrise and Xcode Cloud.
The following additional commands are available:
| Command | Short | Description |
| ------- | ----- | ----------- |
| --example-path | -e | Full path to your example environment file, including file name, if you don't want to use the default. Relative to the current directory. |
| --environment-keys | n/a | A list of your environment variable keys, separated by commas. You can use this rather than passing in a .env.example file if desired. |
| --output-path | -o | Full path you'd like to output your finished environment file to, including filename, relative to the current directory. |
## Bitrise
1. In the Bitrise workflow editor, add your environment variables to the project, being sure to match the variable keys that are in your `.env` file.
2. Use the `ci-helper bitrise` command to generate your script, providing your environment keys using a `.env.example` file or passing them in with the `environmentKeys` option. Make sure you provide an `--output-path` if using a non-standard location for `Environment.swift` as well.
3. Add a new Script step to your workflow between your `Git Clone Repository` and `xcodebuild` steps, and copy the contents of the outputted `bitrise.sh` into that script.
4. Trigger a new build and your `Environment.swift` file should be generated as the script runs.
## Xcode Cloud
1. Add your environment variables to your workflow in App Store Connect, being sure to match the variable keys that are in your `.env` file.
2. Use the `ci-helper xcode` command to generate your script, providing your environment keys using a `.env.example` file or passing them in with the `environmentKeys` option. Make sure you provide an `--output-path` if using a non-standard location for `Environment.swift` as well.
3. Copy the resulting `ci_pre_xcodebuild.sh` file into your `ci_scripts` folder. Note this folder should be at the root directory of your project to ensure it is run. You may need to use `chmod +x ./ci_pre_xcodebuild.sh` to ensure your script runs. See the [Apple documentation](https://developer.apple.com/documentation/xcode/writing-custom-build-scripts) for more info.
4. Commit and push your changes with the new run script. Start a new build and your `Environment.swift` file should be generated as the script runs.
# Installation
SteamclEnv uses a build script to generate your `Environment.swift` file at build time, so set up is a little more involved than your usual package...
### 1. Install SteamclEnv through the [Swift Package Manager](https://swift.org/package-manager/).
a. In Xcode, click *File*, then *Add Package Dependencies*
b. In the search bar, enter: `git@github.com:steamclock/steamclenv.git`
c. Select the `SteamclEnv` package and add it to your project
### 2. Create your `.env` file(s)
By default, your `.env` file should live in the same directory as your `.xcodeproject` file. Your environment variables should use an `=` sign, with no leading or trailing spaces, to separate keys and values and include one pair per line. Like so:
```
KEY=VALUE
ANOTHER_KEY=ANOTHER_VALUE
```
You can see an example of each of these files in the [example project](https://github.com/steamclock/SteamclEnv/tree/main/SteamclEnv-Example).
It's sometimes helpful to commit a `.env.example` file that contains all the keys found in your environment file, but not the values, to help folks who pull down your project know which keys they need to track down. Doing so will make setting up your CI scripts easier as well.
Don't forget to add your `.env` files (and `Environment.swift`) to your `.gitignore` as well.
### 3. Setup and run code generation
SteamclEnv generates your `Environment.swift` file by parsing your `.env` file, so any time you make changes to your environment, you'll want to re-run SteamclEnv.
The easiest way to do this is with a build script, which requires you to install the SteamclEnv CLI. To make it easier to set up the CLI, you can run the bundled InstallCLI SPM plugin. This plugin builds the CLI and links the executable to your project.
To install it, right-click on your project in the Xcode file explorer, then select the `SteamclEnv > Install CLI` command near the bottom. You'll need to grant the plugin 'write' access to your project directory for it to work.
### 4. Create your run script
In Xcode, select your target, then Build Phases, and add a new Run Script. Drag this Run Script above the 'Compile Sources' step, and enter your run script. It should look like:
```
if which ./steamclenv; then
./steamclenv generate
else
echo "Warning: SteamclEnv was expected to run but is not installed."
fi
```
See [Usage](#usage) for a list of commands you can use to customize the generation.
### 6. Toggle User Script Sandboxing
You'll need to change a Build Setting to allow Steamclenv to read/write from inside your project directory.
Set "User Script Sandboxing" (ENABLE_USER_SCRIPT_SANDBOXING) to `NO` for your target to allow SteamclEnv to properly read your environment files.
### 7. Add your generated files to your target
Build your project and make sure your run script ran by checking to see if a new `Environment.swift` file was created.
By default your new file should be output to the root project directory. Add that file to your target, and you should be good to go!
### 6. Make nice apps! 🚀
# License
SteamclEnv is available under the MIT license. See [LICENSE.md](https://github.com/steamclock/steamclenv/blob/main/LICENSE.md) for more info.