<commit_before>% Build Script Support - Cargo Documentation

Some packages need to compile third-party non-Rust code, for example C
libraries. Other packages need to link to C libraries which can either be
located on the system or possibly need to be built from source. Others still
need facilities for functionality such as code generation before building (think
parser generators).

Cargo does not aim to replace other tools that are well-optimized for
these tasks, but it does integrate with them with the `build` configuration
option.

```toml
[package]
# ...
build = "build.rs"
```

The Rust file designated by the `build` command (relative to the package root)
will be compiled and invoked before anything else is compiled in the package,
allowing your Rust code to depend on the built or generated artifacts. Note
that there is no default value for `build`, it must be explicitly specified if
required.

Some example use cases of the build command are:

* Building a bundled C library.
* Finding a C library on the host system.
* Generating a Rust module from a specification.
* Performing any platform-specific configuration needed for the crate.

Each of these use cases will be detailed in full below to give examples of how
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

## Outputs of the Build Script

All the lines printed to stdout by a build script that start with `cargo:`
are interpreted by Cargo and must be of the form `key=value`.

Example output:

```notrust
cargo:rustc-link-lib=static=foo
cargo:rustc-link-search=native=/path/to/foo
cargo:root=/path/to/foo
cargo:libdir=/path/to/foo/lib
cargo:include=/path/to/foo/include
```

The `rustc-link-lib` key indicates that Cargo should pass a `-l` option to
rustc. Similarly, `rustc-link-search` indicates that Cargo should pass a `-L`
option.

The `rustc-flags` key is special and indicates the flags that Cargo will
pass to Rustc. Currently only `-l` and `-L` are accepted. Using
`rustc-link-lib` and `rustc-link-search` is more robust.

Any other element is a user-defined metadata that will be passed to
dependencies. More information about this can be found in the [`links`][links]
section.

## Build Dependencies

Build scripts are also allowed to have dependencies on other Cargo-based crates.
Dependencies are declared through the `build-dependencies` section of the
manifest.

```toml
[build-dependencies.foo]
git = "https://github.com/your-packages/foo"
```

The build script **does not** have access to the dependencies listed in the
`dependencies` or `dev-dependencies` section (they're not built yet!). All build
dependencies will also not be available to the package itself unless explicitly
stated as so.

## The `links` Manifest Key

In addition to the manifest key `build`, Cargo also supports a `links` manifest
key to declare the name of a native library that is being linked to:

```toml
[package]
# ...
links = "foo"
build = "build.rs"
```

This manifest states that the packages links to the `libfoo` native library, and
it also has a build script for locating and/or building the library. Cargo
requires that a `build` command is specified if a `links` entry is also
specified.

The purpose of this manifest key is to give Cargo an understanding about the set<commit_msg>Fix a typo in the description of the links manifest key<commit_after>% Build Script Support - Cargo Documentation

Some packages need to compile third-party non-Rust code, for example C
libraries. Other packages need to link to C libraries which can either be
located on the system or possibly need to be built from source. Others still
need facilities for functionality such as code generation before building (think
parser generators).

Cargo does not aim to replace other tools that are well-optimized for
these tasks, but it does integrate with them with the `build` configuration
option.

```toml
[package]
# ...
build = "build.rs"
```

The Rust file designated by the `build` command (relative to the package root)
will be compiled and invoked before anything else is compiled in the package,
allowing your Rust code to depend on the built or generated artifacts. Note
that there is no default value for `build`, it must be explicitly specified if
required.

Some example use cases of the build command are:

* Building a bundled C library.
* Finding a C library on the host system.
* Generating a Rust module from a specification.
* Performing any platform-specific configuration needed for the crate.

Each of these use cases will be detailed in full below to give examples of how
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

## Outputs of the Build Script

All the lines printed to stdout by a build script that start with `cargo:`
are interpreted by Cargo and must be of the form `key=value`.

Example output:

```notrust
cargo:rustc-link-lib=static=foo
cargo:rustc-link-search=native=/path/to/foo
cargo:root=/path/to/foo
cargo:libdir=/path/to/foo/lib
cargo:include=/path/to/foo/include
```

The `rustc-link-lib` key indicates that Cargo should pass a `-l` option to
rustc. Similarly, `rustc-link-search` indicates that Cargo should pass a `-L`
option.

The `rustc-flags` key is special and indicates the flags that Cargo will
pass to Rustc. Currently only `-l` and `-L` are accepted. Using
`rustc-link-lib` and `rustc-link-search` is more robust.

Any other element is a user-defined metadata that will be passed to
dependencies. More information about this can be found in the [`links`][links]
section.

## Build Dependencies

Build scripts are also allowed to have dependencies on other Cargo-based crates.
Dependencies are declared through the `build-dependencies` section of the
manifest.

```toml
[build-dependencies.foo]
git = "https://github.com/your-packages/foo"
```

The build script **does not** have access to the dependencies listed in the
`dependencies` or `dev-dependencies` section (they're not built yet!). All build
dependencies will also not be available to the package itself unless explicitly
stated as so.

## The `links` Manifest Key

In addition to the manifest key `build`, Cargo also supports a `links` manifest
key to declare the name of a native library that is being linked to:

```toml
[package]
# ...
links = "foo"
build = "build.rs"
```

This manifest states that the package links to the `libfoo` native library, and
it also has a build script for locating and/or building the library. Cargo
requires that a `build` command is specified if a `links` entry is also
specified.

The purpose of this manifest key is to give Cargo an understanding about the set
{'fraction_non_alphanumeric': 0.06803989188181564, 'fraction_numerical': 0.0, 'mean_word_length': 3.3671143671143673, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6476418', 'n_tokens_mistral': 2784, 'n_tokens_neox': 2673, 'n_words': 1447}