When I document my project by 'cargo doc' then it can happen that the name of my own project shadows a dependend crate which is then invisible.
So I do not see that a crate with the same name exists and this crate then keeps undocumented.
How can I tackle this problem?
The best workaround is to just avoid this situation from the beginning. Just make sure you're not shadowing any public crates names. You can check on crates.io if your desired name is available, if it's not I strongly recommend you choose a different name since if you ever want to publish it you'd have to rename it anyways.
Related
On crates.io we can easily see the direct dependencies of a crate by just clicking on the Dependencies tab. Is there a way to also easily see the sub-dependencies of a crate? Perhaps in a tree-like view, similar to what cargo tree would display. Or at least the number of all (sub)dependencies.
I think that can be helpful, for example, when we need to decide which crate to use among alternatives. By having an indicator of the total number of (sub)dependencies, we would have a better idea on how "heavy" a library actually is. I think that can be especially useful for a language like Rust where the build speed seems to heavily depend on the number of dependencies.
I have accidentally published my private crate to crates.io. How do I delete it? I checked the documentation but it seems like there is no way to delete a published crate.
Prevention
To avoid this situation in the future, ensure that you include:
[package]
# ...
publish = false
in your crate's Cargo.toml. See documentation.
Mitigation
Immediately yank the crate using:
cargo yank --vers <your-version>
This will prevent any other crate to accidentally start depending on it.
If any secret was accidentally published (passwords, keys, ...), consider them no longer secret and take appropriate steps to replace them with fresh ones.
Removal
Contact help at crates.io and explain the situation, asking for removal.
If your explanation is well-founded, and the crate has not been downloaded and thus depended on, they have no reason to refuse helping.
Please be patient; once the crate is yanked nobody can start depending on it anyway, so there should be little time pressure. Give the team a few days to actually perform the removal.
If the matter is time sensitive for some reason, you can hop on IRC or Discourse and grab the attention of someone with the powers to perform the removal. Ask and you'll be directed to such a person.
The Crates.io policies say this under Removal:
We will do what the law requires us to do, and address flagrant violations of the Rust Code of Conduct. […] Crates.io will respect Mozilla Legal’s decisions with regards to content that is hosted.
I suggest to send mail to help#crates.io as a start, and if they prove uncooperative, escalate to Mozilla Legal. Only as a last resort, add a deliberate Code of Conduct violation to trigger the removal.
EDIT I agree that this is not a desirable situation, so I submitted a pull request with a proposed policy change.
You cannot delete a crate once it is published. However, you can yank it to mark your crate as not usable: basically, nobody will use it, and no or few people will want to see the content. This policy allows to forbid the arbitrary breakage of other crates that use your package as a dependency.
If you have code or information in this crate that you do not want to be public, refer to the other answer.
By forking and playing with some code, I noticed that Cargo can download and bundle multiple versions of the same crate in the same project (native-tls 0.1.5 and 0.2.1, for example). I have wasted so much time by looking at the documentation of the wrong version.
I have looked for some information about this behaviour but I was not able to find anything. Is this documented somewhere?
Is there an easy way to determine/detect the version used by the code you're working on (current edited file)? Or can we tell Cargo to show some warnings/prevent the build if two versions the same crate are required?
It was a conscious decision when designing Rust to allow multiple versions of the same crate.
You have probably heard of Dependency Hell before, which occurs when 2 (or more) dependencies A and B have a common dependency C but each require a version which is incompatible with the other.
Rust was designed to ensure that this would not be an issue.
In general, cargo will attempt to find a common version which satisfies all requirements. As long as crate authors use SemVer correctly, and the requirements give enough leeway, a single version of the dependency can be computed and used successfully.
Sometimes, however, multiple versions of the same dependency are necessary, such as in your case since 0.1.x and 0.2.x are considered two different major versions. In this case, Rust has two features to allow the two versions to be used within the same binary:
a unique hash per version is appended to each symbol.
the type system considers the same type Foo from two versions of C to be different types.
There is a limitation, of course. If a function of A returns an instance of C::Foo and you attempt to pass it to a function of B, the compiler will refuse it (it considers the two types to be different). This is an intractable problem1.
Anytime the dependency on C is internal, or the use of C is isolated, it otherwise works automatically. As your experience shows, it is so seamless that the user may not even realize it is happening.
1 See the dtolnay trick that crate authors can use to allow some types to be interchangeable.
Cargo can indeed link multiple versions of some crate, but only one of those versions can be a direct dependency. The others are indirect references.
The direct reference is always the version referenced by Cargo.toml and on top-level of Cargo.lock (while the indirect references are in the dependencies subsections).
I am not sure how much it is documented, unfortunately.
I was wondering how are Rust crates are implemented.
For example, there is a crate named num_cpus. This crate has this basic method num_cpus::get() which tells number of CPUs in your computer.
My questions:
How is the method num_cpus::get() implemented (is it done using another language?)
Can the same result be achieved with plain Rust code without using any crates?
... in Rust. There's no reason to believe it'd be anything else.
You can also check this by just looking at the source code, easily done by:
Search crates.io for "num_cpus"..
Select the num_cpus crate.
Select "Repository" for the source code.
Open the only .rs source file in the repository, src/lib.rs.
I am looking for a Rust library to parse dates and I found the documentation for time which looks official.
I wanted to report a bug so I went to the Crates.io page, which led me to the Github repository which sneakily redirected to the rust-deprecated Github account.
Is this library deprecated or not? How can I find out? There's no indication in the documentation or the code.
One problem here is that libraries often become deprecated because the maintainer doesn't have time. So the person who has the power to say "deprecated" also isn't in the position to do it.
The next release of Rust (1.9) will contain a "deprecated" attribute, which would allow someone to mark any part of an API as deprecated, and I guess it could be applied to a whole crate too.
That said, for "time", "deprecated" has a very specific meaning: it's a crate that was almost official, but is not any more, and has not had a new maintainer yet. If anyone wants to take over maintenance, they can request it, and it will be given to them. This only applies to crates that are in the rust-lang-nursery organization, and even that is a bit of history. In the future, I doubt many crates will end up "deprecated" in this way.