A Practical Guide on how to Structure and Maintain your Rust Projects
This guide offers advice on structuring and maintaining Rust projects, drawing from popular Rust projects and personal experience. It should not be viewed as a definitive guide, but rather as a collection of potential issues you might encounter and various ways to address them. Recognizing that some problems have multiple effective solutions, this guide presents a range of options. The hope is that it equips you with valuable advice, allowing your projects to benefit from the learnings of those that came before.
This book uses mdBook, a tool that is commonly used by the Rust ecosystem to write documentation in the style of books. It makes some modifications to the default mdBook configuration:
- The default font for text is Inter, a clean sans-serif typeface.
- The default font for code is Commit Mono, a clean monospaced typeface.
- The default font for diagrams is Routed Gothic, a recreation of the classic Gorton font used in technical drawings and machine labels.
- Tables have been modified to have higher rows, and a different color header.
- All diagrams are made with draw.io
In addition to that, there are some mdBook plugins that are used:
- mdbook-admonish
- mdbook-reading
- mdbook-files
In order to clone this repository, you need to have git-lfs setup.
This book uses Nix to make sure you have the right versions of the dependencies needed to build it. If you don't already have Nix, install it. Using Determinate is the recommended way to do so.
To fully build the book, run
nix build .?submodules=1
To work on it, first launch a development shell with:
nix develop
Within that shell, you can run the expected mdbook commands:
mdbook build
mdbook serve
To apply the automatic formatter to the markdown files, run this command from the root of the repository:
nix run .#fmt
This needs to be done before making a commit, otherwise CI will reject the changes.
For writing style, read the STYLE file.
