Split a module across several files

by

Rust’s module system is actually incredibly flexible and will let you expose whatever kind of structure you want while hiding how your code is structured in files.

I think the key here is to make use of pub use, which will allow you to re-export identifiers from other modules. There is precedent for this in Rust’s std::io crate where some types from sub-modules are re-exported for use in std::io.

Edit (2019-08-25): the following part of the answer was written quite some time ago. It explains how to setup such a module structure with rustc alone. Today, one would usually use Cargo for most use cases. While the following is still valid, some parts of it (e.g. #![crate_type = ...]) might seem strange. This is not the recommended solution.

To adapt your example, we could start with this directory structure:

src/
  lib.rs
  vector.rs
main.rs

Here’s your main.rs:

extern crate math;

use math::vector;

fn main() {
    println!("{:?}", vector::VectorA::new());
    println!("{:?}", vector::VectorB::new());
}

And your src/lib.rs:

#[crate_id = "math"];
#[crate_type = "lib"];

pub mod vector; // exports the module defined in vector.rs

And finally, src/vector.rs:

// exports identifiers from private sub-modules in the current
// module namespace
pub use self::vector_a::VectorA;
pub use self::vector_b::VectorB;

mod vector_b; // private sub-module defined in vector_b.rs

mod vector_a { // private sub-module defined in place
    #[derive(Debug)]
    pub struct VectorA {
        xs: Vec<i64>,
    }

    impl VectorA {
        pub fn new() -> VectorA {
            VectorA { xs: vec![] }
        }
    }
}

And this is where the magic happens. We’ve defined a sub-module math::vector::vector_a which has some implementation of a special kind of vector. But we don’t want clients of your library to care that there is a vector_a sub-module. Instead, we’d like to make it available in the math::vector module. This is done with pub use self::vector_a::VectorA, which re-exports the vector_a::VectorA identifier in the current module.

But you asked how to do this so that you could put your special vector implementations in different files. This is what the mod vector_b; line does. It instructs the Rust compiler to look for a vector_b.rs file for the implementation of that module. And sure enough, here’s our src/vector_b.rs file:

#[derive(Debug)]
pub struct VectorB {
    xs: Vec<i64>,
}

impl VectorB {
    pub fn new() -> VectorB {
        VectorB { xs: vec![] }
    }
}

From the client’s perspective, the fact that VectorA and VectorB are defined in two different modules in two different files is completely opaque.

If you’re in the same directory as main.rs, you should be able to run it with:

rustc src/lib.rs
rustc -L . main.rs
./main

In general, the “Crates and Modules” chapter in the Rust book is pretty good. There are lots of examples.

Finally, the Rust compiler also looks in sub-directories for you automatically. For example, the above code will work unchanged with this directory structure:

src/
  lib.rs
  vector/
      mod.rs
      vector_b.rs
main.rs

The commands to compile and run remain the same as well.

More Related Contents:

  1. How to use one module from another module in a Rust cargo project?
  2. How do I do a basic import/include of a function from one module to another in Rust 2015?
  3. How do I use a macro across module files?
  4. Rust modules confusion when there is main.rs and lib.rs
  5. How do I make an Rust item public within a crate, but private outside it?
  6. How to reference private types from public functions in private modules?
  7. Can’t understand Rust module system
  8. ES6 export all values from object
  9. How do you USE Fortran 90 module data
  10. Unbound Graphics Module
  11. How do I reload a module in an active Julia session after an edit?
  12. Absolute module path resolution in TypeScript files in Visual Studio Code
  13. How to include files from same directory in a module using Cargo/Rust?
  14. When do I need a triple slash reference?
  15. Specify directory where gfortran should look for modules
  16. Execution of Python code with -m option or not
  17. Cannot borrow as mutable more than once at a time in one code – but can in another very similar
  18. Cannot move out of borrowed content when trying to transfer ownership
  19. How do you access enum values in Rust?
  20. Converting number primitives (i32, f64, etc) to byte representations
  21. What does it mean to pass in a vector into a `for` loop versus a reference to a vector?
  22. What is a module in .NET?
  23. Why does my variable not live long enough?
  24. how to test if one python module has been imported?
  25. Why are recursive struct types illegal in Rust?
  26. Extend lifetime of variable
  27. How to properly use relative or absolute imports in Python modules?
  28. Loading environment modules within a python script
  29. Is there any way to allocate a standard Rust array directly on the heap, skipping the stack entirely?
  30. Rust lifetime error expected concrete lifetime but found bound lifetime

Leave a Comment