Dartle Documentation

Dartle CLI

Dartle is mostly meant to be used as a CLI (Command-Line Interface) Application.

Users are expected to run commands on a terminal (or use other tools to do it) to drive a build.

In this page, features of the Dartle CLI are explained in detail.

Informational Options

Use -h, or --help to show usage:

$ dartle --help
Dartle 0.24.0

https://github.com/renatoathaydes/dartle

Usage: dartle [<options>] [<tasks>]

Runs a Dartle build.
Tasks are declared in the dartle.dart file. If no task is given, the
default tasks are run.

Options:
-l, --log-level              Set the log level.
[trace, debug, info (default), warn, error, profile]
-c, --[no-]color             Use ANSI colors to colorize output.
(defaults to on)
-f, --force-tasks            Force all selected tasks to run.
-p, --[no-]parallel-tasks    Allow tasks to run in parallel using Isolates.
(defaults to on)
-s, --show-tasks             Show all tasks in this build. Does not run any tasks when enabled.
-g, --show-task-graph        Show the task graph for this build. Does not run any tasks when enabled.
-z, --reset-cache            Reset the Dartle cache.
-v, --version                Show the Dartle version.
-h, --help                   Show this help message.
-d, --disable-cache          Whether to disable the Dartle cache.

When the informational options are used, i.e. --help, --show-tasks and --show-task-graph, no build tasks are run.

To see what tasks are available in a build, on a directory containing a dartle.dart script, use the -s flag:

$ dartle -s
======== Showing build information only, no tasks will be executed ========

Tasks declared in this build:

==> Setup Phase:
  * clean
==> Build Phase:
  * downloadMagnanimous [up-to-date]
      Download Magnanimous
  * runMagnanimous [default] [out-of-date]
      Builds the Dartle Website using Magnanimous
==> TearDown Phase:
  No tasks in this phase.

The following tasks were selected to run, in order:

  downloadMagnanimous
      runMagnanimous

The output depends on the build script, as that’s what defines the tasks in a build.

At the end of the output above, you can see the tasks that would’ve executed if the -s flag hadn’t been given.

Tasks further to the right are executed after tasks to the left. In the output above, that means downloadMagnanimous runs first, and then runMagnanimous runs once it completes.

Task may also be executed in parallel, in which case they are shown at the same level.

For example:

  taskA
  taskB
      taskC
          taskD
          taskE

This would mean that taskA and taskB execute simultaneously at first, then once they complete, taskC executes, and finally taskD and taskE execute in parallel.

The -g option shows a task graph, which makes it easy to understand the tasks’ dependencies:

$ dartle -g
======== Showing build information only, no tasks will be executed ========

Tasks Graph:

- clean
- downloadMagnanimous
- runMagnanimous
  \--- downloadMagnanimous

The following tasks were selected to run, in order:

  downloadMagnanimous
      runMagnanimous

In very simple builds, this may not look very helpful, but on more complex builds, like the one below from a test Java project built using jb (a Dartle-derived build system for Java), it can become quite handy:

Tasks Graph:

- clean
- compile
  +--- installCompileDependencies
  |     \--- writeDependencies
  \--- installProcessorDependencies
       \--- writeDependencies
- createEclipseFiles
  \--- installCompileDependencies ...
- dependencies
- downloadTestRunner
- installRuntimeDependencies
  \--- writeDependencies
- requirements
  \--- compile ...
- runJavaMainClass
  +--- compile ...
  \--- installRuntimeDependencies ...
- sample-task
- test
  +--- compile ...
  |--- downloadTestRunner
  \--- installRuntimeDependencies ...

The following tasks were selected to run, in order:

  writeDependencies
      installCompileDependencies
      installProcessorDependencies
          compile

The ... after some tasks shown above means that the dependencies of the task are not being shown as they appeared earlier in the graph already.

The graph shows task dependencies as child nodes, so in the graph above, while clean has no dependencies, compile depends on both installCompileDependencies and installProcessorDependencies directly, which both depend on writeDependencies, in turn.

Running Tasks

If you run dartle without any arguments, the default task(s) defined in the build will be executed. If no default task is defined, an error occurs.

To run one or more specific tasks, give the name of the task(s) as arguments. For example, to run compileJava and testJava:

$ dartle compileJava testJava

Dartle can match partial names when there’s no ambiguity, using capital letters as word separators.

An example should make it clear how that works.

Imagine a build with tasks compileJava, compileDart, testJava, testDart.

To run compileJava, you may run dartle compileJava, but also dartle compJ, or even dartle cJ because there’s no other tasks whose name start with c and then J. Using just dartle compile wouldn’t work because that could match either compileJava or compileDart.

Similarly, cD would match compileDart, tJ would match testJava, and tD matches testDart.

Task and Dartle arguments

By default, all arguments are passed directly to Dartle. The example below sets the log-level to debug and runs the example task:

$ dartle example -l debug

If you want to pass arguments to a task, prepend the argument with :… in the example below, the argument abc will be passed to the example task.

$ dartle example :abc -l debug

Changing the order of the arguments does not affect the result, so the invocation below is equivalent to the previous one:

$ dartle example -l debug :abc

When running more than one task, arguments are passed to the latest task specified.

In the example below, task taskA gets arguments 123 and 456, while taskB gets 789:

$ dartle taskA :123 :456 taskB :789

The order in which tasks run depends only on their interdependencies, not on the order in which the tasks are invoked. Hence, in the example above, if taskA and taskB have no interdependencies, they run immediately, in parallel. If taskA depends on taskB, taskB will run before taskA despite it being invoked last.