rad 💯

A general purpose build tool.

  • Concise, statically typed, batteries included.
  • No DSL, no stringly typed tasks, no malarkey.
  • Command tasks, function tasks, and make-like tasks supported.

Jump to:

  1. Documentation site
  2. Usage
  3. Install
  4. What
  5. Why not <my-favorite-build-tool>?
  6. Manual
branch status
main main
next next

Usage

Rad is generally used as a CLI:

$ rad <task-name> [--help]

For example, $ rad build or $ rad --log-level=info test!

It can be used as a library too :).

Rad always consumes a rad.ts file, such as the one shown here:

// rad.ts
import { Task, Tasks } from "https://deno.land/x/rad@v8.0.1/src/mod.ts";

// command/shell tasks
// [name: string, cmd: string]
const format = ["format", `prettier --write`];
const test = ["test", `deno test`];

// function tasks
const compile: Task = {
  dependsOn: [format],
  fn: ({ sh, ...toolkit }) => sh("tsc"),
  // name: "compile" [optional]
};
const greet = {
  fn: ({ fs }) => fs.writeFile("/tmp/hello", "world"),
};

// make-style tasks
const transpile: Task = {
  target: "phony",
  prereqs: ["prereq1", "prereq2"],
  async onMake({ logger }, { changedPrereqs /*, prereqs */ }) {
    for await (const req of changedPrereqs) {
      logger.info(`req: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>r</mi><mi>e</mi><mi>q</mi><mi mathvariant="normal">.</mi><mi>p</mi><mi>a</mi><mi>t</mi><mi>h</mi></mrow><annotation encoding="application/x-tex">{req.path} </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">re</span><span class="mord mathnormal" style="margin-right:0.03588em;">q</span><span class="mord">.</span><span class="mord mathnormal">p</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">h</span></span></span></span></span>{req.isFile}`);
    }
  },
};

export const tasks: Tasks = {
  compile,
  format,
  greet,
  test,
};

Install

There are a few formal ways to use rad. Regardless of the route you choose, know that all strategies support using pinned versions, adherent to semver. See the releases page.

usage install-method install-steps
cli deno deno install --global -f -A -n rad https://raw.githubusercontent.com/cdaringe/rad/v8.0.1/src/bin.ts
cli docker docker pull cdaringe/rad 1
cli curl curl -fsSL https://raw.githubusercontent.com/cdaringe/rad/v8.0.1/assets/install.sh | sh (versioned)
curl -fsSL https://raw.githubusercontent.com/cdaringe/rad/main/assets/install.sh | sh (latest)
library deno import * as rad from https://github.com/cdaringe/rad/blob/main/v8.0.1/mod.ts

1For docker users, consider making a nice shell alias

# shell profile, e.g. .bash_profile
function rad() {
  docker run --rm -v <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>P</mi><mi>W</mi><mi>D</mi><mo>:</mo><mi mathvariant="normal">/</mi><mi>r</mi><mi>a</mi><mi>d</mi><mi>c</mi><mi>d</mi><mi>a</mi><mi>r</mi><mi>i</mi><mi>n</mi><mi>g</mi><mi>e</mi><mi mathvariant="normal">/</mi><mi>r</mi><mi>a</mi><mi>d</mi><mo>−</mo><mo>−</mo><mi>l</mi><mi>o</mi><mi>g</mi><mo>−</mo><mi>l</mi><mi>e</mi><mi>v</mi><mi>e</mi><mi>l</mi><mi>i</mi><mi>n</mi><mi>f</mi><mi>o</mi><mi mathvariant="normal">&quot;</mi></mrow><annotation encoding="application/x-tex">PWD:/rad cdaringe/rad --log-level info &quot;</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6833em;"></span><span class="mord mathnormal" style="margin-right:0.13889em;">P</span><span class="mord mathnormal" style="margin-right:0.13889em;">W</span><span class="mord mathnormal" style="margin-right:0.02778em;">D</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord">/</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">a</span><span class="mord mathnormal">d</span><span class="mord mathnormal">c</span><span class="mord mathnormal">d</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">in</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal">e</span><span class="mord">/</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">a</span><span class="mord mathnormal">d</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord">−</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">in</span><span class="mord mathnormal" style="margin-right:0.10764em;">f</span><span class="mord mathnormal">o</span><span class="mord">&quot;</span></span></span></span>@";
}

What is it

A build tool! It competes with make, npm-scripts, velociraptor, bazel, gradle, ant, gulp, or any of the other many tools out there! On various metrics, rad is subjectively better than some of the outstanding tools out there, and in some cases, not-so-much. We invite you to understand some of its core characteristics and interfaces.

rad offers:

  • simple, programmable task interfaces
  • easy to understand, declarative build steps
  • type-checked tasks
  • no quirky DSLs (make, gradle, and friends 😢). your build is code, not an arbitrary language or stringly (read: bummerly) typed script runner.
  • productive toolkit API for nuanced tasks that benefit from programming. see toolkit
  • bottom-up, make-style build targets
    • fast builds, skip redundant work when inputs haven’t changed
  • cli mode, or library mode
  • portability. build automation for any language or project, in many environments (*limited to Deno target architectures, for the time being. long term, we may package this in Rust)
  • great UX
  • debug-ability. 🐛 inspect your data, tasks, or even rad itself
  • employs a real scripting language–not bash/sh! shell languages are great for running other programs, not for plumbing data

See why not <my-favorite-build-tool>?

Read more on our documentation site