Rustdoc offers some pretty useful lints for documentation. I'd like to check these lints as part of continuous integration for all of the crates in my Cargo workspace.
Unfortunately, I've not been able to find a way to run these lints for all of my crates. You can do e.g.
cargo rustdoc -p crate -- -D rustdoc::broken-intra-doc-links
to run on a specific crate, but there's no --workspace flag on cargo rustdoc. Obviously I could do some hacky thing with xargs here, but that's pretty slow & annoying. Is there a supported way to run this check?
You can use RUSTDOCFLAGS and cargo doc:
RUSTDOCFLAGS="-D rustdoc::broken-intra-doc-links" cargo doc
Related
A fantastic crate is cargo watch, which allows, for example, for you to execute:
cargo watch -x run
to automatically rebuild/run on src change. This is amazing for development but one issue I have is that it seems to not support the --manifest-path argument that can be used with cargo run to explicitly specify the path to the .toml file of the project such that it can be run from a different pwd than the Cargo.toml file itself:
cargo run --manifest-path /home/user/project/Cargo.toml
The crate documentation doesn't mention anything about this, so I was wondering if anyone who uses this crate has found a way around this. When attempting to use the --manifest-path argument I receive:
error: Found argument '--manifest-path' which wasn't expected, or isn't valid in this context
USAGE:
cargo watch [FLAGS] [OPTIONS]
Which makes some sense as I know not all commands support the --manifest-path arg, but since the crate uses cargo run to run the project itself I'm guessing there is some way around this without using e.g. sh -c 'cd [path to .toml file] && cargo watch -x run'
Yes you can just use the invocation which lets you run arbitrary commands:
cargo watch -- cargo run --manifest-path=path/to/Cargo.toml
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 --.
I'm trying to work with the rust-http library, and I'd like to use it as the basis for a small project.
I have no idea how to use something that I can't install via rustpkg install <remote_url>. In fact, I found out today that rustpkg is now deprecated.
If I git clone the library and run the appropriate make commands to get it built, how do I use it elsewhere? I.e. how do I actually use extern crate http?
Since Rust 1.0, 99% of all users will use Cargo to manage the dependencies of a project. The TL;DR of the documentation is:
Create a project using cargo new
Edit the generated Cargo.toml file to add dependencies:
[dependencies]
old-http = "0.1.0-pre"
Access the crate in your code:
Rust 2021 and 2018
use old_http::SomeType;
Rust 2015
extern crate old_http;
use old_http::SomeType;
Build the project with cargo build
Cargo will take care of managing the versions, building the dependencies when needed, and passing the correct arguments to the compiler to link together all of the dependencies.
Read The Rust Programming Language for further details on getting started with Cargo. Specifying Dependencies in the Cargo book has details about what kinds of dependencies you can add.
Update
For modern Rust, see this answer.
Original answer
You need to pass the -L flag to rustc to add the directory which contains the compiled http library to the search path. Something like rustc -L path-to-cloned-rust-http-repo/build your-source-file.rs should do.
Tutorial reference
Not related to your post, but it is to your title. Also, cargo based.
Best practice:
external crate named foo
use ::foo;
module (which is part of your code/crate) named foo
use crate::foo;
In both the cases, you can use use foo; instead, but it can lead to confusion.
Once you've built it, you can use the normal extern crate http; in your code. The only trick is that you need to pass the appropriate -L flag to rustc to tell it where to find libhttp.
If you have a submodule in your project in the rust-http directory, and if it builds into its root (I don't actually know where make in rust-http deposits the resulting library), then you can build your own project with rustc -L rust-http pkg.rs. With that -L flag, the extern crate http; line in your pkg.rs will be able to find libhttp in the rust-http subfolder.
I ran into a similar issue. I ended up doing this in my Cargo.toml
[dependencies]
shell = { git = "https://github.com/google/rust-shell" }
Then in my main.rs I was able to add this and compile with success. Note that this cargo package is a macro in my case. Often you will not want to have the #[macro_use] before the extern call.
#[macro_use] extern crate shell;
I'm trying to build and test my Rust code with a CI, and I'm wondering whether cargo clippy (potentially with options) covers everything that cargo check does. Do I only need to run cargo clippy, or do I need to run both?
clippy itself runs cargo check.
Is it possible to run cargo clippy with an option so it will fix warnings automatically?
From the help message, it does not look like this option is supported at the moment.
As of June 2021 the autofix capability has been stabilized, you can apply changes using the following command
cargo clippy --fix
cargo fix can already apply some suggestions deriving from rustc's errors and warnings.
In nightly builds you can use cargo clippy --fix to apply some suggestions from Clippy. In some older Rust versions, the syntax is reversed: cargo fix --clippy.
If you are using a stable version of the Rust toolchain, you can opt-in to use a nightly build for just one command, by using +nightly to override the toolchain:
cargo +nightly clippy --fix -Z unstable-options