rustrust-cargo

Is there a way to name the root crate/module name of libraries?

I'm used to .NET's class libraries and namespaces. I can generate a structure like this:

I'm still new to Rust and I have a Cargo workspace with different crates. I'd like to replicate that a certain crate has its root module configurable so I can have things under a common my_project module - such as my_project::domain or my_project::web. Things seem to want to fall under the crate name first such as my_project_domain.

Is there a way to configure Cargo to change the root module name?

Solution

  • In the Rust language, an absolute path, e.g. ::std::string::String, always starts with the name of a crate. (The leading colons can be omitted when no item in the current scope shadows the crate name, and often are.) The root module has no name separate from the crate itself. There is no way to organize crates into larger namespaces that come first in absolute paths.

    However, it is very common to create umbrella crates; that is, you can create my_project/Cargo.toml and my_project/src/lib.rs, and in that lib.rs, put a set of re-exports of your other crates:

    pub use my_project_domain as domain;
pub use my_project_web as web;

    In this way, you can create a hierarchical namespace that suits your API. Your dependents no longer need to think about any of the individual crates. (Note that this umbrella crate cannot also be your ‘core’ crate that your other crates depend on; that would be circular.)

    In the future, Rust and Cargo will hopefully gain support for “packages as namespaces”. This planned feature will enable you to get a similar effect as the above, without explicitly creating a re-export package that must depend on all of its components.