amble

First class, scalable rust project generator with batteries included.

Install | User Book | Developer Docs | Crate Docs

The project is still work in progress, see the disclaimer below.

What is amble?

amble is a fairly minimal cli application for generating rust projects with batteries included and with an architecture that scales well, using a workspace and sub-crates.

You can think of amble as an extension of cargo new. Where cargo new provides convenience methods for generating new project structures, either creating a library or a binary project. Below is an example of the library output (binary just writes a main.rs file instead of lib.rs).

project
├─ Cargo.toml
└─ src
 └─ lib.rs

This directory structure doesn't lend itself to building large rust projects that use workspaces. This necessity is where amble was born. amble creates a scalable directory structure using the canonical bin/ and crates/ directories to hold their respective cargo crate types (bin being binaries, and crates being libraries). The top-level Cargo.toml file in the waterfall directory structure below uses workspaces to manage the interface between binaries and libraries.

project
├─ Cargo.toml
├─ bin
│  └─ example
│     ├─ Cargo.toml
│     └─ src
│        └─ main.rs
└─ crates
   └─ common
      ├─ Cargo.toml
      └─ src
         └─ lib.rs

As detailed in Usage below, this output is generated by running amble project --dry-run.

Usage

Install amble using cargo.

cargo install amble

Alternatively, amble can be built from source.

git clone git@github.com:refcell/amble.git && cd amble
cargo build --release

To run amble, we first recommend running it in dry mode which will print a waterfall directory structure for the files that will be created when run in normal mode. Just run amble <project_name> --dry-run, where <project_name> is the name of the project/directory you want to create.

By default, amble uses the current directory for the project name, so it is perfectly acceptable to run amble --dry-run, which will just use . as the project path. Note, amble will exit if it finds cargo artifacts in the directory you chose to execute in.

To run amble out of dry mode, just run amble!

CLI Flags

Below is an inexhaustive list of (core) cli flags.

First class, scalable rust project generator with batteries included.

Usage: amble [OPTIONS] [PROJECT_DIR]

Arguments:
  [PROJECT_DIR]  The path to the project directory. By default, the current working directory is used. If any rust artifacts are detected in the specified or unspecified directory, an error will be thrown [default: .]

Options:
  -v, --v...         Verbosity level (0-4)
      --dry-run      Dry run mode. If this flag is provided, the cli will no execute commands, printing the directories and files that would be created instead
  -n, --name <NAME>  The project name. This will be used for the binary application name [default: example]
  -h, --help         Print help
  -V, --version      Print version

You can generate this output by running amble --help.

Status

amble is in https://github.com/refcell/amble/labels/alpha mode, and should be used for experimentation only.

Local and devnet experimentation is highly encouraged. New issues are also welcome.

In the meantime, contribute, experiment, and have fun!

Troubleshooting & Bug Reports

Please check existing issues for similar bugs or open an issue if no relevant issue already exists.

Contributions

All contributions are welcome!

License

This project is licensed under the MIT License. Free and open-source, forever.

All our rust are belong to you.