I'm loading a crate in my project and this crate has a feature called object-pooling that is not thread safe. Someone suggested I remove this functionality from the crate but I don't know how to do that. Is there a special entry that I can add to my Cargo.toml file and disables features from dependencies?
The syntax in your CARGO.TOML is:
crate_name = {version="version_numer", features=[feature1, feature2]}
If you want or don't want to have a specific feature you can adapt the features list.
Check out the crates documentation or sourcecode if you want to know which features provide which functionality.
You can find the available features of your specific crate here:
https://github.com/brave/adblock-rust/blob/master/Cargo.toml#L86
Related
Right now I'm working on a project with multiple separate crates.
I would prefer lib.rs to be renamed to the crate's name itself, as when I open multiple at the same time it takes me an extra second to find the one I'm looking for, not a big deal just curious if it's possible or a good idea.
ne_log/lib.rs into: ne_log/ne_log.rs
Yes, in each Cargo.toml add a lib section with the desired path:
[lib]
path = "src/some_other_file.rs"
Read more here: Cargo Targets
As to whether its a good idea or not; it will make your file structure non-standard, but the option is available since there are plenty of non-standard workflows. Use your own discretion.
Background
I'm currently in the process of writing a crate that's bindings for a C library and I need the user to specify where the built library is. Previously, I've seen this handles by the llvm-sys crate using environment variables. However, having used this a lot it can become quite cumbersome to have to write this every time I want to run a project.
similar questions
I found this post that asked a similar thing, but seemed to only be able to use specified tags, so not able to specify a path.
What I want to do
I would like to know if there's any way I can have a specific custom value in the Cargo.toml file. The idea being the crate I'm writing would require a specific value (I'll call it example here) that can take any string value. so when this crate were to be used in another project, that projects Cargo.toml file would be similar to this::
[package]
name = "some-other-project"
version = "0.1.0"
edition = "2021"
[dependencies.my_crate]
version = "0.1.0"
example = "something goes here"
This value would then be accessible by the crate I'm writing (the dependency in regards to the above manifest file) and usable in some way.
You can set environment variables using a Cargo configration file (.cargo/config.toml) then you can retrieve them in downstream crates by using e.g. env!()/option_env!()/build scripts.
This section of the Rust book seems to imply that it is possible to keep Rust documentation in separate .md files, but it does not say how these .md files can then be included back. How does this work?
The syntax for putting Rust module documentation in separate Markdown files is:
#![doc = include_str!("path/to/some-documentation.md")]
/* content of the module */
This is supported since stable Rust 1.54.0.
On old nightly compilers from 1.50.0-nightly through 1.53.0-nightly, an unstable feature is required in order for the above to be available.
#![feature(extended_key_value_attributes)]
#![doc = include_str!("path/to/some-documentation.md")]
On nightly compilers 1.24.0-nightly through 1.53.0-nightly, the following alternative syntax is available, but has since been removed.
#![feature(external_doc)]
#![doc(include = "path/to/some-documentation.md")]
It doesn't. That section on describing the functionality of rustdoc is saying that it can process individual .md files. The third paragraph touches on this:
Documentation can be generated in two ways: from source code, and from standalone Markdown files.
Insofar as I am aware, there is no extant way to put code documentation in external files. It would be theoretically possible to do so using a procedural derive macro, but I'm not aware of any crate that actually does this.
In stable Rust, you can mimic the unstable external-doc feature through clever macros.
An easy way to do this is to use the doc-comment crate:
#[macro_use]
extern crate doc_comment;
// If you want to test examples in your README file.
doctest!("../README.md");
// If you want to document an item:
doc_comment!(include_str!("another_file.md"), pub struct Foo {});
You can see a complicated version of this in my crate SNAFU, where I use it for the user's guide.
The "by-hand" version involves passing the thing to be documented along with the included markdown:
macro_rules! inner {
($text:expr, $($rest: tt)*) => {
#[doc = $text]
$($rest)*
};
}
inner! {
include_str!("/etc/hosts"),
mod dummy {}
}
See also:
Is it possible to emit Rust attributes from within macros?
How to embed a Rust macro variable into documentation?
Generating documentation in macros
I have the following piece in the crate documentation:
//! # Examples
//! ```rust,no_run
//! extern crate stm32f103xx;
//! // ...
//! ```
The problem is that the dependency on stm32f103xx crate is optional. Everything works fine if I enable feature stm32f103xx by default, but I don't want to make it default. Is there any way to enable that feature only when rustdoc verifies examples?
No. Features are chosen by the end user of the crate, and you aren't the only person who chooses to run the tests. If you could do what you are asking, you'd actually force anyone who wanted to run the tests to download and compile the "optional" dependency, making it not very optional.
What you can do instead is only include that piece of the documentation when the feature is enabled. It's not obvious, but documentation comments are transformed into the attribute syntax (#[doc = "..."]). Combined with cfg_attr, you can conditionally include documentation, thus conditionally compile and run an example:
#![cfg_attr(feature = "alpha", doc = "
# Examples
```rust
fn alpha() {}
```
")]
Likewise, you can have the opposite case for a bit of documentation that says "check out this awesome feature!".
See also:
doc attribute documentation
How would one achieve conditional compilation with Rust projects that have doctests?
Generating documentation in macros
In order to always have a dependency when compiling any parts of the project (including tests such as that one), Development Dependencies are a good fit.
[dev-dependencies]
stm32f103xx = "0.7.5"
As you mention that the crate is also optional as a main dependency, you can keep it as so in your manifest.
[dependencies]
stm32f103xx = { version = "0.7.5", optional = true }
I would like to enable a feature gate for my entire Cargo project. For example, I would like #![feature(non_ascii_idents)] added to every source file. Is there a place to list them in Cargo.toml?
No, though you don't add feature gates to every source file; they are crate attributes. That is, you set them on the crate, not on every module.
There are two types of attributes:
file attributes (starting with #). They apply to the whole file only.
crate attributes (starting with #!). They apply to the whole crate at once.
What you want (#![feature(non_ascii_idents)]) is a crate attribute, so you need to place it once at the top of the crate's main file. That main file is usually:
src/main.rs for binaries
src/lib.rs for libraries