It seems that the default behavior of Cargo when searching for its configuration directory is to look in the current user's home directory (~/.cargo on my system). How can this behavior be modified to make Cargo look in a user-supplied directory instead?
Environment variables Cargo reads
You can override these environment variables to change Cargo's
behavior on your system:
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. Once a crate is cached it is not removed by the clean
command.
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.
RUSTC_WRAPPER — Instead of simply running rustc, Cargo will execute this specified wrapper instead, passing as its commandline
arguments the rustc invocation, with the first argument being rustc.
RUSTDOC — Instead of running rustdoc, Cargo will execute this specified rustdoc instance instead.
RUSTDOCFLAGS — A space-separated list of custom flags to pass to all rustdoc invocations that Cargo performs. In contrast with
cargo rustdoc, this is useful for passing a flag to all
rustdoc instances.
RUSTFLAGS — A space-separated list of custom flags to pass to all compiler invocations that Cargo performs. In contrast with cargo rustc,
this is useful for passing a flag to all compiler
instances.
CARGO_INCREMENTAL — If this is set to 1 then Cargo will force incremental compilation to be enabled for the current compilation,
and when set to 0 it will force disabling it. If this env var isn't
present then cargo's defaults will otherwise be used.
CARGO_CACHE_RUSTC_INFO — If this is set to 0 then Cargo will not try to cache compiler version information.
The Cargo documentation
Hierarchical structure
Cargo allows local configuration for a particular package as well as
global configuration, like git. Cargo extends this to a hierarchical
strategy. If, for example, Cargo were invoked in
/projects/foo/bar/baz, then the following configuration files would
be probed for and unified in this order:
/projects/foo/bar/baz/.cargo/config
/projects/foo/bar/.cargo/config
/projects/foo/.cargo/config
/projects/.cargo/config
/.cargo/config
$HOME/.cargo/config
With this structure, you can specify configuration per-package, and
even possibly check it into version control. You can also specify
personal defaults with a configuration file in your home directory.
The Cargo documentation
The default location can be changed by means of the environment variable $CARGO_HOME, it overrides the default location which is $HOME/.cargo.
Related
I want to find a way to pass rustflags to artifact dependency bin.
Below is the story.
I write my toy OS currently, and using artifact dependency because this is suggested at rust-osdev/bootloader repositiory(descriptions are Booting section of this README) and I thought this is a useful way. However, I find that this way seems not to pass rustflags I attached in .cargo/config.toml in my kernel workspace like below.
[build]
target = "x86_64-unknown-none"
rustflags = ["-C", "relocation-model=static", "-C", "link-arg=-no-pie"]
[unstable]
build-std = ["core", "compiler_builtins"]
build-std-features = ["compiler-builtins-mem"]
In above config, I expect that kernel elf type is EXEC, but actually, that type is DYN, i.e. I got PIE Elf file even though I write static and no pie flags.
I tried some patterns like below.
run cargo build directly in kernel workspace directory
set invalid rustflags like link-args=hoge and run cargo build in root project directory
As a result
non pie elf (Elf type is EXEC) is created with no errors.
no errors appeared while compile even if I run cargo clean before build.
That's why, I suspect the rustflags I wrote in .cargo/config.toml does not work when its workspace is treated as binary artifact dependency.
Reproduction code is here.
If there is a way to pass rustflags, please teach me.
Add your build.rs in workspace, <project root path>/<kernel workspace name>/build.rs in my case, and put script like below in it.
fn main() {
println!("cargo:rust-link-arg=-no-pie");
}
I'm implementing a custom Cargo subcommand that mostly runs cargo build followed by some processing on a successful invocation. Cargo itself supports several ways to customize defaults, (e.g. the --target selected when omitted), which this subcommand exposes as well.
The challenge now is to find the defaults that cargo build uses from the subcommand implementation. With build scripts getting access to all sorts of information, this isn't the case for subcommands. Running cargo metadata doesn't seem to produce that information either (such as the TARGET).
Is there any way to query Cargo about the configuration it will be using for a cargo build invocation, and make that available to a Cargo custom subcommand?
I want to set rustc-env=VAR=VALUE so that I could access it using env::var("VAR") in my code. However, I'm not clear on where to specify it. Can I set the environment variable VAR in the Makefile?
TL;DR
build.rs
fn main() {
println!("cargo:rustc-env=VAR=VALUE");
}
src/main.rs
fn main() {
let var = env!("VAR");
}
The documentation that you linked is for a Cargo build script:
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. By default Cargo looks up for "build.rs" file in a package root (even if you do not specify a value for build). Use build = "custom_build_name.rs" to specify a custom build name or build = false to disable automatic detection of the build script.
On the same page, there's a section that describes outputs of build.rs
All the lines printed to stdout by a build script are written to a file [...] Any line that starts with cargo: is interpreted directly by Cargo. This line must be of the form cargo:key=value, like the examples below:
cargo:rustc-env=FOO=bar
It then details rustc-env:
rustc-env=VAR=VALUE indicates that the specified environment variable will be added to the environment which the compiler is run within. The value can be then retrieved by the env! macro in the compiled crate. This is useful for embedding additional metadata in crate's code, such as the hash of Git HEAD or the unique identifier of a continuous integration server.
env! is a macro.
access it using env::var("VAR")
No. env::var is for reading environment variables set when the program runs, not when the program is compiled.
See also:
Is it possible to initialize a variable from an environment variable at compilation time when using no_std?
The program I'm writing runs much faster when the -C target-cpu=native flag is passed to rustc. I want to give users a simple, platform-independent way to enable this when compiling, so I added a Cargo feature cpu_native = [] in Cargo.toml and created this Cargo config in my project:
[target.'cfg(cpu_native)']
rustflags = ["-C", "target-cpu=native"]
However, this has no effect on my program, and passing --features cpu_native to Cargo does not even trigger a recompile. Changing to the following Cargo config does force re-compilation with faster instructions:
[build]
rustflags = ["-C", "target-cpu=native"]
However, this will compile with target-cpu=native with the default Cargo features, which was not what I wanted. From the Cargo book, what I want seems to be possible, but I don't see what I'm doing wrong.
I don't think this is supported (yet?). I enhanced Cargo to print out what config flags are checked against when resolving:
[
Name("debug_assertions"),
Name("proc_macro"),
KeyPair("target_arch", "x86_64"),
KeyPair("target_endian", "little"),
KeyPair("target_env", ""),
KeyPair("target_family", "unix"),
KeyPair("target_os", "macos"),
KeyPair("target_pointer_width", "64"),
Name("unix"),
]
[target.'cfg(cpu_native)']
This is the incorrect syntax for a Cargo feature; it would normally be cfg(feature = "cpu_native").
I created a "hello world" Rust app using cargo new. When I executed git status it showed a bunch of files:
A rust/welcomec/Cargo.lock
A rust/welcomec/Cargo.toml
A rust/welcomec/src/main.rs
A rust/welcomec/target/debug/.cargo-lock
A rust/welcomec/target/debug/.fingerprint/welcomec-2d68725c8fae6fd1/bin-welcome-2d68725c8fae6fd1
A rust/welcomec/target/debug/.fingerprint/welcomec-2d68725c8fae6fd1/bin-welcome-2d68725c8fae6fd1.json
A rust/welcomec/target/debug/.fingerprint/welcomec-2d68725c8fae6fd1/dep-bin-welcome-2d68725c8fae6fd1
A rust/welcomec/target/debug/deps/welcome-2d68725c8fae6fd1
A rust/welcomec/target/debug/welcome
A rust/welcomec/target/debug/welcome.d
Can I safely ignore any of these files and/or directories?
Summary
.gitignore for library crates
# Generated files
/target/
# The library shouldn't decide about the exact versions of
# its dependencies, but let the downstream crate decide.
Cargo.lock
.gitignore for executable crates
# Generated files
/target/
Details
You need one or two entries in your .gitignore, depending on what kind of crate you're building. The target/ folder can be ignore completely regardless of crate type; it only contains generated files (e.g. compile artifacts).
The Cargo.lock file should be included in the repository if you're writing an executable, and should be ignored if you're writing a library. You can read more about this in the FAQ. To quote the most important part:
The purpose of a Cargo.lock is to describe the state of the world at the time of a successful build. [...]
This property is most desirable from applications and projects which are at the very end of the dependency chain (binaries). As a result, it is recommended that all binaries check in their Cargo.lock.
For libraries the situation is somewhat different. [...] If a library ends up being used transitively by several dependencies, it’s likely that just a single copy of the library is desired (based on semver compatibility). If all libraries were to check in their Cargo.lock, then multiple copies of the library would be used, and perhaps even a version conflict.
Also, please note that cargo new and cargo init automatically generates a .gitignore file in the project, unless the parameter --vcs none is passed.
You can take some inspiration from GitHub's gitignore for Rust. At the time of writing, the file goes as follows:
# Generated by Cargo
# will have compiled files and executables
debug/
target/
# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
Cargo.lock
# These are backup files generated by rustfmt
**/*.rs.bk
# MSVC Windows builds of rustc generate these, which store debugging information
*.pdb