Your goal: You want to define various constants for your code at compile time based on environment variables.
Your problem: Its only possible to do this for &'static str constants in today's Rust.
rust
const MY_STR: &'static str = env!("SOME_ENV");
You cannot similarly initialize other types such as constant u32s, bools, or
other primitive types. See issues and
workarounds.
Eventually you will be able to do so once support for running parse and unwrap in
const fn lands, but for now this crate offers an easy workaround that you can use today.
| Feature name | Enabled by default? | Requires nightly? | Description |
|---|---|---|---|
| tracked | No | yes | Use the unstable procmacrotracked_env feature to inform the build system about the used environment variables. |
Add the dependency. If your crate uses nightly, enable the tracked feature for better
build dependency tracking.
```toml
[dependencies] const_env = "0.1"
[dependencies] const_env = { version = "0.1", features = ["tracked"] } ```
At the top of your file import the from_env! macro.
rust
use const_env::from_env;
Use the macro to override the value of constants based on environment variables at build time.
```rust
const FOO: u32 = 123;
// This test will PASS if invoked as FOO=456 cargo test
fn test() { assert_eq!(456, FOO); } ```
By default, the macro looks for an environment variable with the same name as the constant that it is attached to.
``rust
// UseFOO=true cargo build` to configure the value.
const FOO: bool = false; ```
But you can specify a name explicitly too.
``rust
// UseBAR=true cargo build` to configure the value.
const FOO: bool = false; ```
The expression that you assign in your source acts as a default in case the environment variable does not exist.
```rust // If env var FOO is not set then the FOO constant will have the default value of '🦀'.
const FOO: char = '🦀'; ```
Both const and static declarations are supported.
``rust
// Both of these may be set byFOO=abc BAZ=def cargo build`.
const FOO: &'static str = "hello";
static BAR: &'static [u8] = b"world"; ```
Strings!
```rust
const FOO: &'static str = "hello";
// example: FOO=abc cargo build
// results in:
const FOO: &'static str = "abc";
```
Byte strings!
```rust
const FOO: &'static [u8] = b"hello";
// example: FOO=world cargo build
// results in:
const FOO: &'static [u8] = b"world";
```
Bytes! ```rust
const FOO: u8 = b'âš™';
// example: FOO=🦀 cargo build
// results in:
const FOO: u8 = b'🦀';
```
Characters!
```rust
const FOO: char = 'âš™';
// example: FOO=🦀 cargo build
// results in:
const FOO: car = '🦀';
```
Integers of all shapes and sizes!
```rust
const FOO: u32 = 123;
const BAR: i64 = 456;
const BAZ: usize = 0;
// example: FOO=321 BAR=-456 BAZ=1usize cargo build
// results in:
const FOO: u32 = 321;
const BAR: i64 = -456;
const BAZ: usize = 1usize;
```
Floats of all shapes and sizes!
```rust
const FOO: f32 = 123.0;
const BAR: f64 = 456.0;
const BAZ: f32 = 0.0;
// example: FOO=321.0 BAR=-456.0 BAZ=1f32 cargo build
// results in:
const FOO: f32 = 321.0;
const BAR: f64 = -456.0;
const BAZ: f32 = 1f32;
```
Booleans!
```rust
const FOO: bool = false;
// example: FOO=true cargo build
// results in:
const FOO: bool = true;
```
const and static declarations are supported.build.rs script which looks at the env vars and generates code based on them. This is conceptually similar to how this crate works, except that this crate uses a procedural macro instead of a build script.static FOO: u32 = std::option_env!("FOO").map(|val| val.parse::<u32>().unwrap_or(0)).unwrap_or(0);,
so once you can simply write that code this crate will become superfluous.