First class, scalable rust project generator with batteries included.

Overview

amble

Build Status License Docs Latest Version rustc 1.31+

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.

Comments
  • fix(root): Prompt User on CI Overwrite

    fix(root): Prompt User on CI Overwrite

    Description

    Currently, amble only checks if a Cargo.toml exists in the directory and then prompts the user if they want to proceed and overwrite the file unless the --overwrite flag was passed into amble.

    If the --with-ci flag is passed and --overwrite is not, amble should prompt the user if ci is present and it didn't already prompt the user if a Cargo.toml exists.

    opened by refcell 1
  • chore(root): Fetch or Construct Repository and Homepage Manifest Fields Dynamically

    chore(root): Fetch or Construct Repository and Homepage Manifest Fields Dynamically

    Description

    Currently the repository and homepage manifest fields are empty in the top-level Cargo.toml.

    These could be populated by constructing urls using the project name and author like so:

    https://github.com/{author}/{project}
    

    There should also be cli flags to allow the user to override this construction with --repository and --homepage fields.

    opened by refcell 1
  • feat(root): Et Cetera Directory

    feat(root): Et Cetera Directory

    Description

    Create an etc (et cetera) directory to hold things like a project logo, banner, et cetera.

    This should automatically be created when the --full flag is provided.

    opened by refcell 0
  • feat(cli): Full Flag

    feat(cli): Full Flag

    Description

    As the number of graceful and prompt-fallible flags grow, it becomes cumbersome to run amble without forgetting flags.

    This ticket is to introduce a --full flag that will automatically enable common flags including (but not limited too):

    • ci
    • gitignore
    • licensing
    opened by refcell 0
  • feat(root): Graceful Gitignore Generation

    feat(root): Graceful Gitignore Generation

    Description

    Often, .gitignore files will be pre-generated by github or other project initializers.

    amble should have a --gitignore bool flag that either creates the default rust .gitignore file or gracefully appends rust gitignore entries to an existing .gitignore file.

    opened by refcell 0
  • feat(root): License Override

    feat(root): License Override

    Description

    Following #10, amble has a --with-license flag to allow the user to specify the type of license to use, overriding the default MIT selection.

    Even though a different, valid spdx license identifier can be specified, amble doesn't support dynamic license fetching and requires the mit license, prompting the user to "fallback" on this license type. This issue is to add support for fetching licenses in a dynamic way, or if not possible, supporting license generation for a host of popular, widely used licenses.

    Note, the github rest api requires a bearer token to auth license requests. There may be a clean ux approach to querying github through gh or some other local user-level config if available.

    opened by refcell 0
  • feat(root): License Generation

    feat(root): License Generation

    Description

    Automatically generate an MIT LICENSE file at the root. If it already exists and the user didn't pass --overwrite, prompt the user for confirmation to overwrite the file.

    opened by refcell 0
  • feat(root): Description Override

    feat(root): Description Override

    Description

    Add a --description flag to amble that allows the user to override the top-level workspace package description.

    This issue should not touch the binary description - that should be artificially enhanced and will be tackled in another issue.

    opened by refcell 0
  • chore(root): Allow Dependency Overrides

    chore(root): Allow Dependency Overrides

    Description

    Currently, dependencies are hardcoded in the root module.

    There should be a cli argument that allows the user to override the dependencies with a list of dependency crate names as a list of strings. Their versions should then be fetched dynamically following #2.

    opened by refcell 0
  • chore(root): Dynamically Fetch Dependency Versions

    chore(root): Dynamically Fetch Dependency Versions

    Description

    Right now, dependencies are hardcoded inside the root module manifest creation.

    They should be fetched dynamically. For potential reference, see the cargo add command.

    opened by refcell 0
  • feat(bin): CLI Stub and Telemetry Setup

    feat(bin): CLI Stub and Telemetry Setup

    Description

    Following a refactor in #30, the binary crate stub should optionally create a cli application (maybe by default and require --bare for a blank/empty binary app?) using clap and amble telemetry. This should also apply to the cargo init fallthrough.

    opened by refcell 0
  • feat: Refactor Crate

    feat: Refactor Crate

    Description

    Refactor out amble modules into a separate library crate. This would allow amble to generate projects that import amble's library crate itself for utility functions such as telemetry and other future added helpers, especially for binary apps.

    A follow-on issue should split out the work to add this library to binary projects and automatically construct a cli application using clap and amble telemetry.

    amble's minor version can be bumped following the refactor done here. This should be a sizable change.

    opened by refcell 0
  • feat(ci): Release + Cargo Publish Workflow Dispatch

    feat(ci): Release + Cargo Publish Workflow Dispatch

    Description

    Add a github action workflow yaml that triggers a release and a cargo publish.

    This should live next to ci.yml in the .github/workflows/ directory and be called release.yml.

    C: Good First Issue 
    opened by refcell 0
  • fix(license): Dynamic License Imputation

    fix(license): Dynamic License Imputation

    Description

    Dynamically fetched licenses from spdx use a host of template string styles for substitution.

    Currently, amble only imputes the MIT License <year> and <copyright holders> template strings, but a more clever heuristic should be used to impute other template strings. An example for this is running amble with --with-license apache, which fails to substitute the values [yyyy] and [name of copyright owner] for the chrono year and fetched username.

    C: Good First Issue 
    opened by refcell 0
  • fix(cargo): Fallthrough Cargo TOML Stubs

    fix(cargo): Fallthrough Cargo TOML Stubs

    Description

    When using the fall through cargo init binary and library creation methods, the generated Cargo.tomls are defaults with minimal info.

    Workspace-level package metadata should be applied to the Cargo.toml manifests for these fall through amble --lib and --bin flags, as well as dependencies.

    opened by refcell 0
Middleware/ios shortcut to setup alarms automatically based on the first class

Webuntis alarm This is a small little "middleware" / web server intended to connect to a webuntis timetable used in german schools which i wrote when

raizo 3 Dec 30, 2022
Rust-battery - Rust crate providing cross-platform information about the notebook batteries.

battery Rust crate providing cross-platform information about the notebook batteries. Table of contents Overview Supported platforms Install Examples

svartalf 326 Dec 21, 2022
Spoon Radio Echo Project, Lightweight and scalable broadcasting server.

Echo Project https://medium.com/p/3bd1434a163a Echo was initiated by a social network platform, Spoon Radio(https://www.spooncast.net). The main goal

Spoon Radio Inc. 23 Jan 3, 2023
A Rust based simple cli to delete all files included in `.gitignore` file from your repo

clean-local A simple CLI to remove all the files and folders included in the .gitignore file. Written in RUST Supports glob and wildcard paths in .git

Vilva Athiban P B 5 Jul 8, 2023
A Rust-based shell script to create a folder structure to use for a single class every semester. Mostly an excuse to use Rust.

A Rust Course Folder Shell Script PROJECT IN PROGRESS (Spring 2022) When completed, script will create a folder structure of the following schema: [ro

SebastiΓ‘n Romero Cruz 1 Apr 10, 2022
Baby's first Rust CLI project. Basic implementation of grep. Written in about 100 SLOC.

minigrep Coding project from Chapter 12 of the The Rust Programming Language book. Usage Compile and run as so minigrep QUERY FILENAME QUERY being the

Anis 2 Oct 2, 2021
First project in rust which will be to make an accounts system & Leaderboard/Score system

rust-backend this is my first project in rust which will be to make a backend for compsci project it will include: Accounts, Player Achievements (if I

NaughtyDog6000 2 Jul 13, 2023
Write Cross-platform application with React-like decralative UI framework and scalable ECS architecture all in Rust.

bevy_dioxus Dioxus Plugin for Bevy Write Cross-platform application with React-like decralative UI framework and scalable ECS architecture all in Rust

Junichi Sugiura 269 Dec 29, 2022
Infino - Fast and scalable service to store time series and logs - written in Rust

Infino 〽️ ?? β€” ?? ?? β€” βš–οΈ ?? Ingest Metrics and Logs β€” Query and Insights β€” Scale and Save $$ Infino is an observability platform for storing metrics

null 6 Apr 23, 2023
A truly zero-dependency crate providing quick, easy, reliable, and scalable access to the name "jordin"

jordin Finally! A truly zero-dependency crate providing quick, easy, reliable, and scalable access to the name "jordin". Additionally, this one-of-a-k

jordin 2 Aug 4, 2022
SKYULL is a command-line interface (CLI) in development that creates REST API project structure templates with the aim of making it easy and fast to start a new project.

SKYULL is a command-line interface (CLI) in development that creates REST API project structure templates with the aim of making it easy and fast to start a new project. With just a few primary configurations, such as project name, you can get started quickly.

Gabriel Michaliszen 4 May 9, 2023
World's first, but possibly worst, blinky for the pico in Rust

pico-blink-rs Running Rust code on the Raspberry Pi Pico Booting The RP2040 has external QSPI flash. There is an internal mask-ROM bootloader which ca

rp-rs 129 Dec 24, 2022
I'm currently learning Rust and these are my first programs with this language

learning-Rust I follow the Rust by example official doc for learning That is also available in 'doc pdf' alongside another great rust learning sheet I

null 3 Dec 30, 2022
The first web framework in Rust to adopt the Model-View-Controller (MVC) architecture

Integra Web Framework Integra is a sleek, performant web framework for Rust, harnessing the power of the hyper library. Will become the first highly p

null 3 Sep 11, 2023
try to find the correct word with only first letter and unknown letter count.

MOTUS Current dictionaries are provided in french and can contain some words not included in the official Motus dictionary. Additionally, dictionaries

Alexandre 6 Apr 11, 2022
Bolik Timeline is local-first software for keeping notes and files.

Bolik monorepo Bolik Timeline is local-first software for keeping notes and files. This repo contains alpha-quality software. This means that we are e

Bolik Oy 18 Apr 11, 2023
Local-first high performance codebase index engine designed for AI

CodeIndex CodeIndex is a local-first high performance codebase index engine designed for AI. It helps your LLM understand the structure and semantics

Jipiti AI 9 Aug 30, 2023
A CLI-based pride flag generator written in Rust

?? prideful (in development) A CLI-based pride flag generator written in Rust. How to run Build the project using cargo. Install cargo by following th

Angelo-F 35 Sep 3, 2022
A better customization password dictionary generator implementation by Rust.

abcdict A better customization password dictionary generator implementation by Rust. Features Cli Faster Customize Rules Build & Installation $> cargo

b23r0 6 Jun 2, 2022