According to doc.rust-lang.org
cargo rustdoc
build[s] a package's documentation, using specified custom flags
cargo doc
build[s] a package's documentation
What is the difference between the two? From what I understand cargo rustdoc is just like cargo doc, but it allows for more lints—for instance:
#![deny(rustdoc::broken_intra_doc_links)]
Is this correct? Oddly enough, cargo rustdoc will also fail in certain situations where cargo doc doesn't. For instance
some/folder on some-branch [$!] via 🦀 v1.60.0-nightly
❯ cargo doc
Finished dev [unoptimized + debuginfo] target(s) in 0.53s
some/folder on some-branch [$!] via 🦀 v1.60.0-nightly
❯ cargo rustdoc
error: manifest path `some/folder/Cargo.toml` is a virtual manifest, but this command requires running against an actual package in this workspace
Also, cargo doc does not support adding the -D option, whereas cargo rustdoc does.
❯ cargo doc -- -D rustdoc::broken_intra_doc_links
error: Found argument '-D' which wasn't expected, or isn't valid in this context
USAGE:
cargo doc [OPTIONS]
For more information try --help
Their relationship is like between cargo build and cargo rustc: cargo doc performs all the usual work, for an entire workspace, including dependencies (by default). cargo rustdoc allows you to pass flags directly to rustdoc, and only works for a single crate.
Here is the execution code for cargo rustdoc. Here is the code for cargo doc. The only differences is that cargo rustdoc always specify to not check dependencies while cargo doc allows you to choose (by default it does, but you can specify the flag --no-deps), and that cargo rustc allows you to pass flags directly to rustdoc with the flags after the --.
Related
What is the difference between cargo new <project_name> --bin and cargo new <project_name>?
It seems both commands make exactly the same project; all components are consistent.
I think --bin stands for "binary", but I don't know when to use this option or not.
There is no difference between cargo new and cargo new --bin. From First Steps with Cargo, emphasis mine:
To start a new package with Cargo, use cargo new:
$ cargo new hello_world
Cargo defaults to --bin to make a binary program. To make a library, we would pass --lib, instead.
Likewise, Cargo's command line help tells you the same thing. From cargo new --help, with some irrelevant lines removed:
% cargo new --help
OPTIONS:
--bin Use a binary (application) template [default]
--lib Use a library template
See also
Why does `cargo new` create a binary instead of a library?
What is the difference between library crates and normal crates in Rust?
I am using a Rust dependency which allows being built with a --debug or --verbose flag.
I am running my test as follows:
cargo test --package mw-btc-swap --bin mw-btc-swap -- grin::grin_core::test::test_fin_tx --exact --nocapture
Now my question is how can I configure cargo to only compile this specific dependency with the desired flag. I tried using RUSTFLAGS=--debug environment variable but then the flag seems to be passed to all compilations which makes most of them fail, as they don't support this flag.
I have also looked through https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html in hope I could somehow specify the flags in the cargo.toml which doesn't seem to be the case.
I want to run tests with release optimisations using 1 test thread.
I can do these individually:
cargo test -- --test-threads=1
cargo test --release
How would I put these together?
You can use both in a single command like this:
cargo test --release -- --test-threads=1
How Cargo interprets these arguments ?
According to test subcommand's synopsis in reference :
cargo test [OPTIONS] [TESTNAME] [-- TEST-OPTIONS]
Cargo interprets input as :
Arguments before separator (--) will be used as an option for test subcommand. In your case cargo test accepts profile parameter as an option since it builds the project. Available options can be found under this title, or by running cargo test --help.
Arguments after the separator will be passed to the test binaries. In Rust project, Cargo uses rustc's libtest to run unit tests. In your case --test-threads=1 will be an argument for libtest.
This interpretation might not be valid for other subcommands, it is best to check other cargo commands from here. Checking synopsis section will give you a huge hint about capabilities of cargo's subcommands.
See also:
Since arguments after the dash will be sent to the rustc's libtest you can see available options for testing by: cargo test -- --help.
Profile options can be found under this title
The output of rustup target list --toolchain nightly does not contain x86_64-apple-ios-macabi, even though it is in src/librustc_target on the Rust master branch.
How do I build for Mac Catalyst / x86_64-apple-ios-macabi?
The x86_64-apple-ios-macabi target is available on the nightly (5c5b8afd8 2019-11-16) compiler. Just because a target is available does not mean that the standard library and friends are compiled or available to rustup:
% rustc +nightly --print target-list | grep macabi
x86_64-apple-ios-macabi
Rust has a tier system (which is the subject of a proposed RFC). This target is so new it's not even listed on the tier list, but it's undoubtedly going to be tier 3. Tier 2.5 says (emphasis mine):
Tier 2.5 platforms can be thought of as "guaranteed to build", but without builds available through rustup
In the meantime, you will need to build your own libcore / libstd from source. I don't have the time nor ability to actually test that the compilation works, but something like these choices are the general starting path:
build-std
The unstable -Z build-std flag can be used to build the standard library:
% cargo +nightly build -Z build-std --target x86_64-apple-ios-macabi
Xargo
Building the standard library can be done using the xargo tool.
% rustup override set nightly
info: using existing install for 'nightly-x86_64-apple-darwin'
info: override toolchain for '/private/tmp/example' set to 'nightly-x86_64-apple-darwin'
nightly-x86_64-apple-darwin unchanged - rustc 1.41.0-nightly (5c5b8afd8 2019-11-16)
% cat > Xargo.toml
[target.x86_64-apple-ios-macabi.dependencies.std]
# features = ["jemalloc"] # Whatever is appropriate
% xargo build --target x86_64-apple-ios-macabi
# Iterate until libcore and libstd compile and work for your platform
#shepmaster 's answer is correct. In detail, you have to:
Install Xargo:
cargo install xargo
cd in your project
use the nighly build:
rustup override set nightly
create the Xargo.toml file with content:
[target.x86_64-apple-ios-macabi.dependencies.std]
In your projects Cargo.toml, make sure the [profile.release] section contains panic = "abort". If it does not, add it.
When building the project, use xargoinstead of cargo.
Shepmaster's answer is a little outdated. Cargo now supports the -Zbuild-std command. Using it, you can target any of the targets that rustc itself supports even if they aren't listed on rustup +nightly target list. Simply:
rustc +nightly --print target-list
and
cargo +nightly build -Z build-std --target x86_64-apple-ios-macabi
should be enough now. You don't need xargo to build the standard lib anymore.
If you have an old installation of rust, you might need to remove old nightly (or at least for me it fails to update nightly):
rustup toolchain remove nightly
rustup update
rustup toolchain install nightly
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").