cargo-make 0.1.1

Rust task runner and build tool.
cargo-make-0.1.1 is not a library.
Visit the last successful build: cargo-make-0.37.10

cargo-make

crates.io Build Status Build status codecov license Libraries.io for GitHub Documentation downloads cargo-make

Rust task runner and build tool.

Currently in initial development

Overview

The cargo-make task runner enables to define and configure sets of tasks and run them as a flow. A task is a command or a script to execute. Tasks can have depedencies which are also tasks that will be executed before the task itself. With a simple toml based configuration file, you can define a multi platform build script that can run build, test, documentation generation, bench tests execution, security validations and more by running a single command.

Installation

In order to install, just run the following command

cargo install cargo-make

This will install cargo-make in your ~/.cargo/bin. Make sure to add ~/.cargo/bin directory to your PATH variable.

Usage

When using cargo-make, all tasks are defined and configured via toml files. Below are simple instructions to get your started off quickly.

Simple Example

In order to run a set of tasks, you first must define them in a toml file. For example, if we would like to have a script which:

  • Formats the code
  • Cleans old target directory
  • Runs build
  • Runs tests

We will create a toml file as follows:

install_crate = "rustfmt"
command = "cargo"
args = ["fmt", "--", "--write-mode=overwrite"]

[tasks.clean]
command = "cargo"
args = ["clean"]

[tasks.build]
command = "cargo"
args = ["build"]
depedencies = ["clean"]

[tasks.test]
command = "cargo"
args = ["test"]
depedencies = ["clean"]

[tasks.my-flow]
depedencies = [
    "format",
    "build",
    "test"
]

We would execute the flow with the following command:

cargo make -b simple-example.toml -t my-flow

The output would look something like this:

[cargo-make] info - Using Build File: ./examples/simple-example.toml
[cargo-make] info - Task: my-flow
[cargo-make] info - Running Task: format
[cargo-make] info - Execute Command: "cargo" "fmt" "--" "--write-mode=overwrite"
[cargo-make] info - Running Task: clean
[cargo-make] info - Execute Command: "cargo" "clean"
[cargo-make] info - Running Task: build
[cargo-make] info - Execute Command: "cargo" "build"
   Compiling vec_map v0.8.0
   Compiling serde v1.0.8
   Compiling unicode-width v0.1.4
   Compiling quote v0.3.15
   Compiling unicode-xid v0.0.4
   Compiling libc v0.2.24
   Compiling ansi_term v0.9.0
   Compiling bitflags v0.9.1
   Compiling unicode-segmentation v1.1.0
   Compiling strsim v0.6.0
   Compiling synom v0.11.3
   Compiling syn v0.11.11
   Compiling term_size v0.3.0
   Compiling atty v0.2.2
   Compiling textwrap v0.6.0
   Compiling clap v2.25.0
   Compiling serde_derive_internals v0.15.1
   Compiling toml v0.4.2
   Compiling serde_derive v1.0.8
   Compiling cargo-make v0.1.0 (file:///home/ubuntu/workspace/rust/cargo-make)
    Finished dev [unoptimized + debuginfo] target(s) in 253.16 secs
[cargo-make] info - Running Task: test
[cargo-make] info - Execute Command: "cargo" "test"
   Compiling cargo-make v0.1.0 (file:///home/ubuntu/workspace/rust/cargo-make)
    Finished dev [unoptimized + debuginfo] target(s) in 12.80 secs
     Running target/debug/deps/cargo_make-542f1253498e7764

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

[cargo-make] info - Running Task: my-flow

We now created a build script that can run on any platform.

Tasks, Depedencies and Aliases

In many cases, certain tasks depend on other tasks. For example you would like to format the code before running build and run the build before running tests. Such flow can be defined as follows:

[tasks.format]
install_crate = "rustfmt"
command = "cargo"
args = ["fmt", "--", "--write-mode=overwrite"]

[tasks.build]
command = "cargo"
args = ["build"]
depedencies = ["format"]

[tasks.test]
command = "cargo"
args = ["test"]
depedencies = ["build"]

When you run:

cargo make -b ./my_build.toml -t test

It will try to run test, see that it has depedencies and those have other depedencies. Therefore it will create an execution plan for the tasks based on the tasks and their depedencies. In our case it will invoke format -> build -> test.

The same task will never be executed twice so if we have for example:

[tasks.A]
depedencies = ["B", "C"]

[tasks.B]
depedencies = ["D"]

[tasks.C]
depedencies = ["D"]

[tasks.D]
script = [
    "echo hello"
]

In this example, A depdends on B and C, and both B and C are depedended on D. Task D however will not be invoked twice. The output of the execution will look something like this:

[cargo-make] info - Task: A
[cargo-make] info - Setting Up Env.
[cargo-make] info - Running Task: D
[cargo-make] info - Execute Command: "sh" "/tmp/cargo-make/CNuU47tIix.sh"
hello
[cargo-make] info - Running Task: B
[cargo-make] info - Running Task: C
[cargo-make] info - Running Task: A

As you can see, 'hello' was printed once by task D as it was only invoked once. But what if we want to run D twice? Simple answer would be to duplicate task D and have B depend on D and C depend on D2 which is a copy of D. But duplicating can lead to bugs and to huge makefiles, so we have alias for that. An alias task has its own name and points to another task. All of the definitions of the alias task are ignored. So now, if we want to have D execute twice we can do the following:

[tasks.A]
depedencies = ["B", "C"]

[tasks.B]
depedencies = ["D"]

[tasks.C]
depedencies = ["D2"]

[tasks.D]
script = [
    "echo hello"
]

[tasks.D2]
alias="D"

Now C depends on D2 and D2 is an alias for D. Execution output of such make file would like as follows:

[cargo-make] info - Task: A
[cargo-make] info - Setting Up Env.
[cargo-make] info - Running Task: D
[cargo-make] info - Execute Command: "sh" "/tmp/cargo-make/HP0UD7pgoX.sh"
hello
[cargo-make] info - Running Task: B
[cargo-make] info - Running Task: D2
[cargo-make] info - Execute Command: "sh" "/tmp/cargo-make/TuuZJkqCE2.sh"
hello
[cargo-make] info - Running Task: C
[cargo-make] info - Running Task: A

Now you can see that 'hello' was printed twice.

Default Tasks and Extending

There is no real need to define the tasks that were shown in the previous example. cargo-make comes with a built in toml file that will serve as a base for every execution. The optional external toml file that is provided while running cargo-make will only extend and add or overwrite tasks that are defined in the default toml. Lets take the build task definition which comes alrady in the default toml:

[tasks.build]
command = "cargo"
args = ["build"]

If for example, you would like to add verbose output to it, you would just need to change the args and add the --verbose as follows:

[tasks.build]
args = ["build", "--verbose"]

There is no need to redefine existing properties of the task, only what needs to be added or overwritten. The default toml file comes with many steps and flows already built in, so it is worth to check it first.

Environment Variables

You can also define env vars to be set as part of the execution of the flow in the env block, for examle:

[env]
RUST_BACKTRACE="1"

All env vars defined in the env block and in the default toml will be defined before running the tasks.

Continues Integration

cargo-make comes with a predefined flow for continues integration build executed by internal or online services such as travis-ci and appveyor. For travis-ci, simple change the script to invoke the cargo-make installation and invocation as follows:

script:
  - cargo install --debug cargo-make
  - cargo make --task ci-flow

For online CI services, it is better to install with the debug flag to enable a much faster installation.

Cli Options

These are the following options available while running cargo-make:

USAGE:
    cargo-make make [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -b, --buildFile <FILE>        Build toml file containing the build descriptor (default: Makefile.toml if exists)
    -l, --loglevel <LOG LEVEL>    The log level (default: info) [values: verbose, info, error]
    -t, --task <TASK NAME>        The task name to execute (default: default)

Roadmap

The cargo-make task runner is still in initial development and there are many things planned for the comming release. Here are a few of the top priorities:

  • Support platform specific task overrides
  • Git related task definitions in default toml
  • Crate publishing task definitions in default toml
  • Setup a website with more in depth explanations and examples

API Documentation

See full docs at: API Docs

Contributing

See contributing guide

Release History

Date Version Description
2017-06-24 v0.1.1 Added support for env vars, task alias and crate installation
2017-06-23 v0.1.0 Initial release.

License

Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.