The directory layout of a Rust project should look like this (source)
.
├── Cargo.lock
├── Cargo.toml
├── benches
│ └── large-input.rs
├── examples
│ └── simple.rs
├── src
│ ├── bin
│ │ └── another_executable.rs
│ ├── lib.rs
│ └── main.rs
└── tests
└── some-integration-tests.rs
What is the file simple.rs under examples? How do I execute it? How should the file look like?
Examples are useful in library crates to show how the crate is used.
An example can be an executable with a main method or a library; it can either be in a single file examples/example-name.rs or consist of several files in a subdirectory examples/example-name/, with the main method in main.rs. To compile a library example you need to specify its crate type in Cargo.toml:
[[example]]
name = "example-name"
crate-type = ["lib"]
Examples are compiled by cargo test to ensure that they are up to date with the crate. You can run a specific executable example by
cargo run --example <example-name>
and selectively build any example with
cargo build --example <example-name>
This is documented in the Cargo Reference.
Related
I am developing a code for my school's rocketry team and I have two programs, one meant to flash the on-board computer and another to run some data analysis on the flight data. The chip code uses no_std while the data analysis program uses std. The data-analysis code will run on my PC, and the chip code will run on the chip.
Here is my workspace root Cargo.toml and my project graph:
[workspace]
members = [
"chip",
"data-analysis",
]
.
├── Cargo.lock
├── Cargo.toml
├── chip
│ ├── Cargo.toml
│ ├── memory.x
│ ├── openocd.cfg
│ ├── openocd.gdb
│ └── src
│ └── main.rs
├── data-analysis
│ ├── Cargo.toml
│ └── src
│ └── main.rs
├── README.md
└── resources
├── 3m.mkd
├── data-stm32f103c8t6.pdf
├── links.txt
├── reference-stm32f103xx.pdf
├── schematic-stm32f103c8t6.png
└── todo.txt
I have decided to use a workspace to organize my code. When I attempt to build the workspace, I get the error:
error[E0463]: can't find crate for `std`
|
= note: the `thumbv7m-none-eabi` target may not support the standard library
= note: `std` is required by `data_analysis` because it does not declare `#![no_std]`
= help: consider building the standard library from source with `cargo build -Zbuild-std`
When I compile with cargo build -Zbuild-std I get the error:
error[E0463]: can't find crate for `panic_abort`
error[E0658]: use of unstable library feature 'restricted_std'
|
= help: add `#![feature(restricted_std)]` to the crate attributes to enable
However I need no_std and not restricted_std.
I understand that dependencies for all files are stored in Cargo.lock and presumably that's why it is producing this error. My question is, how do I express to the compiler that I need std for data_analysis but not for chip code? Should I even be using workspaces over just using one package with multiple binaries and using [features] in the Cargo.toml?
It seems like you're trying to complile data_analysis with the same target as chip. I recommend just getting rid of the root Cargo.toml and compiling the respective ones in the folders. You could make a Makefile to automate this easily
I'm using cargo-bundle to create an .app bundle for my Rust application built with fltk-rs.
There are assets in the application like images. While I'm developing, accessing these assets is no problem.
main.rs:
let mut my_img = SharedImage::load("imgs/smiley.png").unwrap();
.
├── Cargo.lock
├── Cargo.toml
├── app_icon_design.psd
├── imgs
│ └── smiley.PNG <--get this image
├── src
│ ├── app_icon.png
│ ├── app_icon#2x.png
│ ├── icon32x32.png
│ └── main.rs
└── target
├── CACHEDIR.TAG
├── debug
└── release
I then bundle to an .app with cargo build --release which gives me the following directory structure inside of my .app:
.
├── Info.plist
├── MacOS
│ └── build_to_app_bundle <--my executable
└── Resources
└── imgs
└── smiley.PNG<--get this image now
Now my application needs to get the image file from the /Resources folder:
println!("my resources folder is: {:?}", std::env::current_exe().unwrap().parent().unwrap().join(Path::new("Resources")));
let my_resources_path = std::env::current_exe().unwrap().parent().unwrap().join(Path::new("Resources"));
How can I make it so that every time I want to load an image from a path I do not need to explicitly reference the Resources value?
Let's say there is a vendored third-party cargo project consisting of a library plem and a binary plem_main that I want to extend with some functionality of my own. Crucially, the functionality needs to go in the library plem, not the binary plem_main (which can stay the same). I could write a wrapper my_plem around the library that offers the same interface to the binary, but with the extra functionality included. The project would be set up like this:
.
├── Cargo.toml
├── my_plem
│ ├── Cargo.toml
│ └── src
│ └── lib.rs
└── third-party
├── plem
│ ├── Cargo.toml
│ └── src
│ └── lib.rs
└── plem_main
├── Cargo.toml
└── src
└── main.rs
my_plem/src/lib.rs would depend on things in third-party/plem/src/lib.rs and reexport or overwrite the functions exported by the latter. Is there a good way to get cargo to build the binary plem_main on top of my_plem instead of plem?
"Best" here means that the solution has no or minimal merge conflicts when updating plem in my project and doesn't duplicate the code of plem_main. Ideally it does not touch third-party at all.
I'm writing a book about embedded Rust using mdbook as one git repository and then I have another repository created by cargo where I place the code.
I'd like to structure the code so it corresponds with the chapters in the book and therefore is in separate directory.
The structure for the book:
├── book
├── book.toml
└── src
├── chapter_1.md
├── chapter_2.md
├── chapter_3.md
├── chapter_4.md
├── chapter_5.md
├── chapter_6.md
└── SUMMARY.md
And the structure for the code:
├── aarch64-unknown-none.json
├── Cargo.lock
├── Cargo.toml
├── layout.ld
├── Readme.md
├── chapter1
│ └── main.rs
├── chapter2
│ ├── boot.rs
│ └── main.rs
└── chapter3
├── boot.rs
├── console.rs
└── main.rs
I'd prefer this structure as the reader can then look directly at the code for the chapter and not search git commits. I also sometimes need to modify something later therefore git commits are not a solution.
Is there a way to specify this format in Cargo.toml? To either build all the directories or specify which one on the command line.
The exact solution can be found in the second edition of the Rust book with an example.
I restructured the repository like this:
├── aarch64-unknown-none.json
├── Cargo.lock
├── Cargo.toml
├── layout.ld
├── Readme.md
├── chapter1
│ ├── Cargo.toml
│ └── main.rs
├── chapter2
│ ├── boot.rs
│ ├── Cargo.toml
│ └── main.rs
└── chapter3
├── boot.rs
├── Cargo.toml
├── console.rs
└── main.rs
Cargo.toml files in the chapter directories remain without any modification. Only the Cargo.toml in the root is modified to contain the following:
[workspace]
members = ["chapter1", "chapter2", "chapter3"]
One small drawback to this solution is that the members must have different crate names in their Cargo.toml as the output of all members is stored in the target dir in the root of the workspace. This is only a small issue and I appreciate the flexibility Cargo offers.
Where should one put the sources, examples, documentation, unit tests, integration tests, license, benchmarks etc?
Cargo, the official package manager for Rust, defines some conventions regarding the layout of a Rust crate:
.
├── Cargo.lock
├── Cargo.toml
├── benches
│ └── large-input.rs
├── examples
│ └── simple.rs
├── src
│ ├── bin
│ │ └── another_executable.rs
│ ├── lib.rs
│ └── main.rs
└── tests
└── some-integration-tests.rs
Cargo.toml and Cargo.lock are stored in the root of your project.
Source code goes in the src directory.
The default library file is src/lib.rs.
The default executable file is src/main.rs.
Other executables can be placed in src/bin/*.rs.
Integration tests go in the tests directory (unit tests go in each file they're testing).
Example executable files go in the examples directory.
Benchmarks go in the benches directory.
These are explained in more detail in the manifest description.
By following this standard layout, you'll be able to use Cargo's commands to build, run and test your project easily. Run cargo new to set up a new executable project or cargo new --lib to set up a new library project.
Additionally, documentation for libraries is often written in documentation comments (comments that start with /// before any item, or //! to document the parent item). Also, the license is usually put at the root.
Unit tests, as mentioned above, are written in the same module as the functions they're testing. Usually, they're put in an inner module. It looks like this (this is what Cargo generates for a new library with cargo new --lib):
#[cfg(test)]
mod tests {
#[test]
fn it_works() {
}
}