A personal list of pain-points, rough edges, ambiguities, etc observed while trying to work on Rust projects (+adject tooling, cargo, crates.io, rust-analyzer, etc). This list is for personal reference, of personal experiences, not for "dunking" on the language or for flame wars. Multiple things in this list might be entirely incorrect / just undocumented.
The most common pattern for crate names is to use hypens. However, hypens are not valid identifiers in Rust. As such, these get implicitly converted to underscores.
If you have a crate named foobar-rs, all references to that package in Rust code will need to use foobar_rs.
At some point in the past, this was an explicit implementation detail, requiring the syntax:
extern crate "foobar-rs" as foobar_rs;
However, this is now a magic (undocumented?) internal detail of Cargo, and is highly dependent on the crate type (bin, [dy|cy]lib), target OS, output file type (wasm, js, debug symbols), and more.
- (Ctrl+F for "should_replace_hyphens"):
- https://github.com/rust-lang/cargo/blob/2f84e1a45c059df8aadee1d7548ef9d0a3d7c47f/src/cargo/core/compiler/build_context/target_info.rs#L392
Additionally, in order to prevent crate typo squatting, a check is done at the crates.io package registry level which only allows a single - or _ package. (e.g. if foo-bar exists, one cannot create foo_bar).
References:
- rust-lang/rust#44909
- https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
- https://internals.rust-lang.org/t/pre-rfc-resolve-support-for-hyphens-in-crate-names/1459
- https://internals.rust-lang.org/t/maybe-pre-rfc-improving---in-cargo-crates-io/5251
- rust-lang/cargo#1706
- rust-lang/cargo#9627
- rust-lang/cargo#9778
It is unfortune how common it is to google something Rust related to only find out that the answer is: This feature has existed as unstable/nightly for 5+ years, is widely used in various projects already and is de-facto stable, but is not marked as stable. You will need to ditch stable Rust to use this.
thiscallcalling convention rust-lang/rust#42202
If you make a struct tagged with #[derive(Debug)] and only use it for debug printing, then Rust will give you countless (invalid IMO) warnings claiming that the struct fields are never used. Despite the fact that they are used in a println! call.
The issue for this was closed with the general resolution being: just surpress the warnings with #[allow(unused)]. :/
warning: multiple fields are never read
--> src\main.rs:8:5
|
7 | struct MetalibHeader {
| ------------- fields in this struct
8 | magic: u16,
| ^^^^^
9 | build: u16,
| ^^^^^
10 | platform_arch: u32,
| ^^^^^^^^^^^^^
13 | size: i32,
| ^^^^
14 |
15 | field_c: u32,
| ^^^^^^^
16 | field_10: u32,
| ^^^^^^^^
17 | field_14: u32,
...