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 5f829e390851d00fe13e93917078c7575c0b8107..c4b7ec875924d51e0157d687a9fcfefb830f9c93 100644 (file)
--- 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_<name>` - For each activated feature of the package being
-                           built, this environment variable will be present
-                           where `<name>` is the name of the feature uppercased
-                           and having `-` translated to `_`.
-* `DEP_<name>_<key>` - 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 d189bb6c5fe7702e20de49d39933e8465680a974..ff7b11d6ba7694992f93473238d0bb2c5bedbfe6 100644 (file)
--- 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 (file)
index 0000000..898b0ef
--- /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_<name>` - For each activated feature of the package being
+                           built, this environment variable will be present
+                           where `<name>` 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_<name>_<key>` - 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 e70fecfcb492aa326be5f3fe47b122cb5ef8c29a..3a1ec6ac71300d2fb16f81fa28c6b72e577b1c5e 100644 (file)
--- a/src/doc/header.html
+++ b/src/doc/header.html
@@ -38,6 +38,7 @@
                 <li><a href='build-script.html'>Build Scripts</a></li>
                 <li><a href='config.html'>Configuration</a></li>
                 <li><a href='pkgid-spec.html'>Package ID specs</a></li>
+                <li><a href='environment-variables.html'>Environment Variables</a></li>
             </ul>
         </div>
     </div>