From: Steve Klabnik Date: Mon, 27 Jul 2015 19:14:42 +0000 (-0400) Subject: Consolidate and document environment variables X-Git-Tag: archive/raspbian/0.35.0-2+rpi1~3^2^2^2^2^2^2^2~22^2~17^2~102^2 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=e596ed3e2b3738b05aa10f41d65366b7211d34b9;p=cargo.git Consolidate and document environment variables These were spread out before, now they're in one place. Fixes #1538 --- diff --git a/src/doc/build-script.md b/src/doc/build-script.md index 5f829e390..c4b7ec875 100644 --- a/src/doc/build-script.md +++ b/src/doc/build-script.md @@ -35,39 +35,12 @@ the build command works. ## Inputs to the Build Script When the build script is run, there are a number of inputs to the build script, -all passed in the form of environment variables: - -* `OUT_DIR` - the folder in which all output should be placed. This folder is - inside the build directory for the package being built, and it is - unique for the package in question. -* `TARGET` - the target triple that is being compiled for. Native code should be - compiled for this triple. Some more information about target - triples can be found in [clang's own documentation][clang]. -* `HOST` - the host triple of the rust compiler. -* `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can - be useful to pass a `-j` parameter to a system like `make`. -* `CARGO_MANIFEST_DIR` - The directory containing the manifest for the package - being built (the package containing the build - script). Also note that this is the value of the - current working directory of the build script when it - starts. -* `OPT_LEVEL`, `DEBUG` - values of the corresponding variables for the - profile currently being built. -* `PROFILE` - name of the profile currently being built (see - [profiles][profile]). -* `CARGO_FEATURE_` - For each activated feature of the package being - built, this environment variable will be present - where `` is the name of the feature uppercased - and having `-` translated to `_`. -* `DEP__` - For more information about this set of environment - variables, see the section below about [`links`][links]. - -In addition to the above environment variables, the build script's current -directory is the source directory of the build script's package. - -[profile]: manifest.html#the-[profile.*]-sections -[links]: #the-links-manifest-key -[clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple +all passed in the form of [environment variables][env]. + +In addition to environment variables, the build script's current directory is +the source directory of the build script's package. + +[env]: environment-variables.html ## Outputs of the Build Script diff --git a/src/doc/config.md b/src/doc/config.md index d189bb6c5..ff7b11d6b 100644 --- a/src/doc/config.md +++ b/src/doc/config.md @@ -89,16 +89,8 @@ target-dir = "target" # path of where to place all generated artifacts # Environment Variables -Cargo recognizes a few global environment variables to configure how it runs: - -* `CARGO_HOME` - Cargo maintains a local cache of the registry index and of git - checkouts of crates. By default these are stored under `$HOME/.cargo`, but - this variable overrides the location of this directory. -* `RUSTC` - Instead of running `rustc`, Cargo will execute this specified - compiler instead. -* `RUSTDOC` - Instead of running `rustdoc`, Cargo will execute this specified - `rustdoc` instance instead. -* `CARGO_TARGET_DIR` - Location of where to place all generated artifacts, - relative to the current working directory. - -Settings specified via config files take precedence over those specified via environment variables. +Cargo recognizes a few global [environment variables][env] to configure itself. +Settings specified via config files take precedence over those specified via +environment variables. + +[env]: environment-variables.html diff --git a/src/doc/environment-variables.md b/src/doc/environment-variables.md new file mode 100644 index 000000000..898b0ef7d --- /dev/null +++ b/src/doc/environment-variables.md @@ -0,0 +1,65 @@ +% Environment Variables + +Cargo sets a number of environment variables which your code can detect. To get +the value of any of these variables in a Rust program, do this: + +``` +let version = env!("CARGO_PKG_VERSION") +``` + +`version` will now contain the value of `CARGO_PKG_VERSION`. + +Here are a list of the variables Cargo sets, organized by when it sets them: + +# Environment variables Cargo reads + +* `CARGO_HOME` - Cargo maintains a local cache of the registry index and of git + checkouts of crates. By default these are stored under `$HOME/.cargo`, but + this variable overrides the location of this directory. +* `CARGO_TARGET_DIR` - Location of where to place all generated artifacts, + relative to the current working directory. +* `RUSTC` - Instead of running `rustc`, Cargo will execute this specified + compiler instead. +* `RUSTDOC` - Instead of running `rustdoc`, Cargo will execute this specified + `rustdoc` instance instead. + +# Environment variables Cargo sets for build scripts + +* `CARGO_PROFILE` - either `debug` or `release`. +* `CARGO_MANIFEST_DIR` - The directory containing the manifest for the package + being built (the package containing the build + script). Also note that this is the value of the + current working directory of the build script when it + starts. +* `CARGO_FEATURE_` - For each activated feature of the package being + built, this environment variable will be present + where `` is the name of the feature uppercased + and having `-` translated to `_`. +* `OUT_DIR` - the folder in which all output should be placed. This folder is + inside the build directory for the package being built, and it is + unique for the package in question. +* `TARGET` - the target triple that is being compiled for. Native code should be + compiled for this triple. Some more information about target + triples can be found in [clang's own documentation][clang]. +* `HOST` - the host triple of the rust compiler. +* `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can + be useful to pass a `-j` parameter to a system like `make`. +* `OPT_LEVEL`, `DEBUG` - values of the corresponding variables for the + profile currently being built. +* `PROFILE` - name of the profile currently being built (see + [profiles][profile]). +* `DEP__` - For more information about this set of environment + variables, see build script documentation about [`links`][links]. + +[links]: build-script.html#the-links-manifest-key +[profile]: manifest.html#the-[profile.*]-sections +[clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple + +# Environment variables Cargo sets for crates + +* `CARGO_PKG_VERSION` - The full version of your package. +* `CARGO_PKG_VERSION_MAJOR` - The major version of your package. +* `CARGO_PKG_VERSION_MINOR` - The minor version of your package. +* `CARGO_PKG_VERSION_PATCH` - The patch version of your package. +* `CARGO_PKG_VERSION_PRE` - The pre-release version of your package. + diff --git a/src/doc/header.html b/src/doc/header.html index e70fecfcb..3a1ec6ac7 100644 --- a/src/doc/header.html +++ b/src/doc/header.html @@ -38,6 +38,7 @@
  • Build Scripts
  • Configuration
  • Package ID specs
    • +
  • Environment Variables