amble
First class, scalable rust project generator with batteries included. Amble is in beta π.
Install | User Docs | Crate Docs | Reference | Contributing | License
What is amble?
amble is a cli application for generating rust projects with batteries included. By using a workspace and sub-crates, amble scales to any number of crates.
You can think of amble as an extension of cargo init. Cargo provides convenience methods for generating new project structures, the two primary types being a library or a binary project. Below is an example of the directory structure generated by cargo init --lib. (A binary project would only differ in having a main.rs file instead of lib.rs).
project
ββ Cargo.toml
ββ src
ββ lib.rs
amble provides a more extensive cli command for generating project directory structures with workspaces. Library sub-crates are nested inside the cannonical crates/ directory, while binary crates are nested inside the bin/ directory. A top-level Cargo.toml file defines a workspace including the binaries and libraries as well as shared package metadata and dependencies, minimizing inconsistencies across the sub-crates. amble also exposes the --lib and --bin flags which fallback to cargo init and create the default cargo init file structure with all amble batteries included and available through cli flags.
Below is an example waterfall directory structure output for when amble is run with the argument project as the project name.
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 [email protected]:refcell/amble.git && cd amble
cargo build --release
To run amble, it is recommended to first run it in dry mode which will print a waterfall directory structure for the files that would be created when run without dry mode. Simply 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!
A pre-defined github action ci workflow can be automatically generated by passing in the --with-ci flag to amble. This would generate a directory structure as follows (amble --dry-run --with-ci).
.
ββ Cargo.toml
ββ bin
β ββ example
β ββ Cargo.toml
β ββ src
β ββ main.rs
ββ crates
β ββ common
β ββ Cargo.toml
β ββ src
β ββ lib.rs
ββ .github
ββ workflows
ββ ci.yml
Amble also provides fallthrough methods for generating cargo init library and binary projects with batteries such as a templated readme, github action ci workflows, and licensing. The flags to pass through to cargo init operations are injective, meaning amble --bin will pass through to cargo init --bin and amble --lib will pass through to cargo init --lib. As usual, any other valid amble flag can be provided along with the --lib and --bin flags.
CLI Flags
Below is an inexhaustive list of the main cli flags. These are subject to change and new ones can be added. To view a more up-to-date list, run the amble --help command locally.
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 not execute commands, printing the directories and files that would be created instead
--overwrite Overwrite existing files. If this flag is provided, the cli will overwrite existing files
-n, --name <NAME> The project name. This will be used for the binary application name [default: example]
-w, --with-ci Add github actions ci workflow
-c, --ci-yml <CI_YML> Copy the specified ci workflow file to the project's `.github/workflows/` directory
-a, --authors <AUTHORS> Override the project authors
-b, --bin Builds a cargo binary project
-l, --lib Builds a cargo library project
--full Full generates a full project structure including license, ci, gitignore, etc
--etc Adds an `etc/` directory to the project. This _Et Cetera_ directory is used for storing miscellaneous files
--license Adds an MIT License to the project. The MIT License type can be overridden with the `--with-license` flag
--gitignore Adds a Gitignore file to the project
-d, --description <DESCRIPTION> Specifies the description of the project in the top-level `Cargo.toml` workspace
--dependencies <DEPENDENCIES> Adds these dependencies to the top-level `Cargo.toml` workspace alongside the default dependencies
--list Lists the default dependencies
--with-license <WITH_LICENSE> License Override. This will override the default MIT License. The license type must be a valid SPDX license identifier
-h, --help Print help
-V, --version Print version
You can generate this output by running amble --help.
Contributing
All contributions are welcome! Experimentation is highly encouraged and new issues are welcome.
Troubleshooting & Bug Reports
Please check existing issues for similar bugs or open an issue if no relevant issue already exists.
License
This project is licensed under the MIT License. Free and open-source, forever. All our rust are belong to you.
3 Dec 30, 2022
326 Dec 21, 2022
5 Jul 8, 2023
23 Jan 3, 2023
1 Apr 10, 2022
2 Oct 2, 2021
2 Jul 13, 2023
269 Dec 29, 2022
6 Apr 23, 2023
2 Aug 4, 2022
4 May 9, 2023
129 Dec 24, 2022
3 Dec 30, 2022
3 Sep 11, 2023
6 Apr 11, 2022
18 Apr 11, 2023
9 Aug 30, 2023
6 Mar 1, 2024
15 Sep 28, 2024