Crate cargo_build

Expand description

§Cargo build

§`cargo-build` is a wrapper around cargo instructions accesible in `build.rs` with better type safety and support for modern features.

Includes functions by default. Macros are optional, but do provide better experience when there is need to do formatting and variable number of arguments at the same time which is ideal for DSLs.

Add this crate as build-dependency

[build-dependencies]
cargo-build = "0.1.0" # no macros

[build-dependencies]
cargo-build = { version = "0.1.0", features = ["macros"] }

https://doc.rust-lang.org/cargo/reference/build-scripts.html

Those instructions are usually implemented by println!("cargo::") call. This crate provides easy to use wrapper-functions around those instructions.

Benefits:

Less code.
Easier to modify later.
Harder to make typos.

§With `cargo-build` using functions:

cargo_build::rustc_link_arg_bin("server", "-Wl,--cref");

cargo_build::rustc_link_arg_bin("client", [
        "-mlongcalls",
        "-ffunction-sections",
        "-Wl,--cref",
]);

§Without `cargo-build`:

println!("cargo::rustc-link-arg-bin=server=-Wl,--cref");
println!("cargo::rustc-link-arg-bin=client=-mlongcalls");
println!("cargo::rustc-link-arg-bin=client=-ffunction-sections");
println!("cargo::rustc-link-arg-bin=client=-Wl,--cref");

§With `cargo-build` using functions:

cargo_build::rustc_check_cfgs("cuda");
cargo_build::rustc_cfg("cuda");

cargo_build::rustc_check_cfg("api_version", ["1", "2", "3"]);
cargo_build::rustc_cfg(("api_version", "1"));

§Without `cargo-build`:

Note the inconsistancy of cfg
Note the need for escape sequences

println!("cargo::rustc-check-cfg=cfg(cuda)");
println!("cargo::rustc-cfg=cuda");

println!("cargo::rustc-check-cfg=cfg(api_version, values(\"1\", \"2\", \"3\"))");
println!("cargo::rustc-cfg=api_version-\"1\"");

§Macros example (enable `features = ["macros"]` in `Cargo.toml`):

let env_var = "HOST";

if std::env::var(env_var).is_ok() {
    cargo_build::warning!("Warning during compilation: {} is not set", env_var);
    cargo_build::error!("Unable to finish compilation: {} is not set", env_var);
}

cargo_build::rustc_link_arg!(cdylib: "-mlongcalls"; "-ffunction-sections");

cargo_build::rustc_link_arg!(
    bin "client":
      "-mlongcalls";
      "-ffunction-sections";
      "-Wl,--cref";
      "stack-size={}", { 8 * 1024 * 1024 };
);

cargo_build::rustc_link_lib!(
    static: "+whole-archive", "+verbatim", "+bundle" =
      "nghttp2";
      "libssl";
      "libcrypto";
      "mylib:{}", "renamed_lib";
);

cargo_build::rustc_check_cfg!("api_version": "1", "2", "3");
cargo_build::rustc_cfg!("api_version" = "1");

Why use cargo-build when cargo emit already exists:

Support for modern features (such as error, rustc_check_cfg).
Support for ‘keywords’ (such as link-lib:KIND is not a string but defined set of values (static, dylib, framework)).
Better syntax overall (such as static: "lib1"; "lib2:{}", "renamed_lib2"; "lib3" in macros - no need to declare each lib static).
Extended examples and documentation for modern use cases.
Macros are feature - library works even without macros. Enable them by using features = ["macros"] in Cargo.toml

Note: The order of instructions in the build script may affect the order of arguments that cargo passes to rustc. In turn, the order of arguments passed to rustc may affect the order of arguments passed to the linker. Therefore, you will want to pay attention to the order of the build script’s instructions. For example, if object foo needs to link against library bar, you may want to make sure that library bar’s rustc-link-lib instruction appears after instructions to link object foo.\

https://doc.rust-lang.org/cargo/reference/build-scripts.html

Modules§

build_out

Functions§

error: Displays an error on the terminal.
metadata: Metadata, used by links scripts.
rerun_if_changed: Tells Cargo to re-run the build script ONLY if file or directory with given name changes.
rerun_if_env_changed: Tells Cargo to re-run the build script if environment variable with the given name has changed.
rustc_cfg: Enables custom compile-time cfg settings.
rustc_check_cfg: Define expected cfg names and values. Those names are used when checking the reachable cfg expressions with the unexpected_cfgs lint.
rustc_check_cfgs: Define expected config names. Those names are used when checking the reachable cfg expressions with the unexpected_cfgs lint.
rustc_env: Sets an environment variable.
rustc_flags: Passes certain flags to the compiler.
rustc_link_arg: Passes custom flags to a linker for benchmarks, binaries, cdylib crates, examples, and tests.
rustc_link_arg_benches: Passes custom flags to a linker for benches.
rustc_link_arg_bin: Passes custom flags to a linker for specific binary name.
rustc_link_arg_bins: Passes custom flags to a linker for binaries.
rustc_link_arg_cdylib: Passes custom flags to a linker for cdylib crates.
rustc_link_arg_examples: Passes custom flags to a linker for examples.
rustc_link_arg_tests: Passes custom flags to a linker for tests.
rustc_link_lib: Adds a library to link.
rustc_link_lib_dylib: rustc_link_lib alternative that automatically passes dylib=.
rustc_link_lib_framework: rustc_link_lib alternative that automatically passes framework=.
rustc_link_lib_static: rustc_link_lib alternative that automatically passes static=.
rustc_link_search: Adds a directory to the library search path.
rustc_link_search_all: rustc_link_search alternative that automatically passes all=.
rustc_link_search_crate: rustc_link_search alternative that automatically passes crate=.
rustc_link_search_dependency: rustc_link_search alternative that automatically passes dependency=.
rustc_link_search_framework: rustc_link_search alternative that automatically passes framework=.
rustc_link_search_native: rustc_link_search alternative that automatically passes native=.
warning: Displays a warning on the terminal.