Rust-Tinyrick: tinyrick a basic task dependency tool emphasizing Rust functions over raw shell commands.

tinyrick: a freeform Rust build system

       .---.              ^
     o{__ω__ o{          ^0^  -Let me out!
~~ ( // *|* \xx\)      xx`|'
        = =  xxxx&x      ' `

EXAMPLE

$ cd example

$ tinyrick
running 1 test
test smoketest ... ok

$ tinyrick -h
Usage: tinyrick [options]

Options:
    -l, --list          list available tasks
    -h, --help          print usage info
    -v, --version       print version info

ABOUT

I'm tinyrick (TINYRICK!) and I build Rust projects. With tinyrick, you configure your build in the same normal Rust code as the rest of your project. Or keep picking your nose with make, it's up to you.

Look at my pants! tinyrick! You think my pants are one size fits all? No, of course not! So get the pants that fit you. Get a tinyrick.rs that fits your workflow. Task dependency trees, get em while they're hot! Segfaults, get em while they're not. Smarter, butter, faster, stranger.

Don't shell out, lib out. Your build is more portable that way. tinyricktinyricktinyrick. If you look closely, that last period is actually a micro rick rendered in ASCII; even tinier tinyrick!

CRATE

https://crates.io/crates/tinyrick

API DOCUMENTATION

https://docs.rs/tinyrick/

RUNTIME REQUIREMENTS

SETUP

tinyrick.rs

Write some tasks in a tinyrick.rs build configuration script at the top-level directory of your Rust project:

fn banner() {
    println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
}

fn test() {
    tinyrick::exec!("cargo", &["test"]);
}

fn build() {
    tinyrick::deps(test);
    tinyrick::exec!("cargo", &["build", "--release"]);
}

fn publish() {
    tinyrick::exec!("cargo", &["publish"]);
}

fn clean() {
    tinyrick::exec!("cargo", &["clean"]);
}

fn main() {
    tinyrick::phony!(clean);
    tinyrick::wubba_lubba_dub_dub!(build; banner, test, publish, clean);
}

Cargo.toml

Now, wire up the tinyrick command line interface by configuring your top-level Cargo.toml:

[package]
name = "derpmobile"
description = "hyperadvanced derpmobiles"
version = "3.1.4"

[dependencies]
tinyrick = { version = "0.0.10", optional = true }

[features]
letmeout = ["tinyrick"]

[[bin]]
name = "tinyrick"
path = "tinyrick.rs"
required-features = ["letmeout"]

Launch a terminal session in your project directory. Install and run the tinyrick tool:

$ cargo install tinyrick
$ tinyrick

Watch how he behaves... I hope tinyrick is practicing good manners :P

What happens when you run:

  • tinyrick banner?
  • tinyrick test?
  • tinyrick clean?
  • tinyrick build?
  • tinyrick -h?
  • tinyrick --list?
  • VERBOSE=1 tinyrick build?

I bet the freakin' moon explodes if you run VERBOSE=1 tinyrick build build build! (Hold onto your pants~)

DEBRIEFING

Where are my pants? Let's break down the code so far:

  • fn name() { ... } declares a task named name.
  • deps(requirement) caches a dependency on task requirement.
  • exec!(...) spawns raw shell command processes.
  • VERBOSE=1 enables command string emission during processing.
  • phony!(...) disables dependency caching for some tasks.
  • wubba_lubba_dub_dub!(default; ...) exposes a default task and some other tasks to the tinyrick command line.
  • letmeout is a feature gate, so that neither the tinyrick package, nor your tinyrick binary escape with your Rust package when you tinyrick publish.

DoN't UsE sHelL cOmMaNdS!1

Just because the tinyrick library offers several supremely convenient macros for executing shell commands doesn't mean that you should always shell out. No way, man!

Whenever possible, use regular Rust code, as in the banner() example. There's like a ba-jillion crates of prewritten Rust code, so you might as well use it!

CONTRIBUTING

For more details on developing tinyrick itself, see DEVELOPMENT.md.

SEE ALSO

  • Inspired by the excellent mage build system for Go projects
  • GNU make, a classic task runner
  • cmake for C/C++ projects
  • dale offers similar task runner features for D projects
  • vast for UNIX shell script projects

EVEN MORE EXAMPLES

  • The included example project provides a fully qualified demonstration of how to build projects with tinyrick.
  • For a more practical example, see ios7crypt-rs, a little modulino library + command line tool for deliciously dumb password encryption.
  • tinyrick_extras defines some common workflow tasks as plain old Rust functions, that you can sprinkle onto your tinyrick just like any other Rust crate.

Comments

  • Fix tinyrick clean <more tasks>
    Fix tinyrick clean

    Dec 29, 2018

    Cordon off the execution of tasks, so users can run tinyrick clean <task> [<task> [<task>...]] without cargo locks interfering.

    As a workaround, do tinyrick clean; tinyrick <task> [<task>...]

    Reply
  • Simplify macros with Kleene operator
    Simplify macros with Kleene operator

    Jan 17, 2019

    Reduce the code involved in the shell-related macros by using the new Kleene operator.

    https://github.com/rust-lang/rust/issues/48075

    Note: This requires updating Rust to v1.32.0+.

    Reply
  • Fix clean task
    Fix clean task

    Jan 24, 2019

    Use decorators to implement customizable clean tasks, to resolve the problem where clean wipes out tinyrick sandbox and breaks the rest of the command line execution.

    Reply
  • Soft assertions
    Soft assertions

    Jan 24, 2019

    Allow tasks to declare that the rest of a build should continue, such as applying more linters, so that the full report is visible, while still presenting an accurate overall exit status code based on any failing tasks.

    Reply
  • Drop redundant tasks
    Drop redundant tasks

    Feb 18, 2020

    Use a proper tree data structure to prune redundant tasks.

    For example, when task build depends on test and users invoke tinyrick build test, then the code inside of test should only be executed once.

    Reply
  • s/build.sh/make/
    s/build.sh/make/

    Feb 18, 2020

    For better Windows compatibility

    Reply
  • Wrap cargo doc
    Wrap cargo doc

    Oct 20, 2018

                                                                                                                                                                                                           
    Reply
  • fix docs
    fix docs

    Oct 21, 2018

                                                                                                                                                                                                           
    Reply
  • Publish bugfix release
    Publish bugfix release

    Oct 22, 2018

    Publish latest edition to crates.io, to fix bugs in the previous macros.

    Reply
  • Help developers easily port Rust applications
    Help developers easily port Rust applications

    Oct 20, 2018

    Experiment with Cargo.toml configurations for generating ports, in a way that works from any environment, to any environment. Build configurations that work only when running from specific host OS's are no bueno.

    (Preferably without using tonixxx, Vagrant, or any VM's/containers.)

    Reply
  • Express some dependencies in terms of directories and other files
    Express some dependencies in terms of directories and other files

    Nov 20, 2018

    As a developer, I want my builds to run faster, by skipping unnecessary rebuilds when enough of the file artifacts are already up to date.

    • [ ] Expand the dependency notation, giving programmers a make-like way to declare dependencies on files.
    • [x] File dependencies can be placed on raw files.
    • [ ] File dependencies can be placed on directories.
    • [ ] File dependencies can be placed on symbolic links.
    • [ ] Tasks can declare that they emit / are responsible for, generating named file/directory patterns.
    • [ ] Include conventional file and recursive directory glob patterns out of the box, so that tinyrick maintains a high level of cross-platform, cross-shell interpreter support.
    • [ ] Query Cargo TOML configurations to automatically identify file dependencies.
    Reply
  • Publish arithmancy
    Publish arithmancy

    Oct 20, 2018

    For completeness of example :)

    Reply