dartle library Null safety

A simple build system written in Dart.

Tasks are declared in a regular Dart file and can be executed in parallel or in sequence.

This library provides several Dart utilities useful for automating common tasks, such as copying/moving/transforming files and executing commands, but as build files are just regular Dart, any dev_dependencies can be used in build files.


An ArgsValidator which accepts anything.
A RunCondition which is always fullfilled.
A RunCondition that runs if all of its conditions runs.
Validates the the number of arguments passed to a Task.
A log message that should be displayed with a specific color.
A directory entry, usually used within a FileCollection.
An ArgsValidator which does not accept any arguments.
A collection of File and Directory which can be used to declare a set of inputs or outputs for a Task.
A FileCollection representing the union between multiple file collections.
A RunCondition that runs if any of its conditions runs.
A RunCondition which reports that a task should run at most every period.
A RunCondition which reports that a task should run whenever its inputs or outputs have changed since the last build.
A RunCondition that indicates that a Task will delete certain files and directories if they exist.
A consumer of stdout and stderr text streams.
A Dartle task whose action is provided by user code in order to execute some logic during a build run.
Phases of Tasks.
Result of executing a Task.
A Task including its transitive dependencies.
Task with its status, including its current invocation.


Validator of arguments passed to a Task.
A RunCondition that uses file-system inputs and outputs.
A run condition for a Task.
Base mixin for a RunCondition that combines other RunConditions.




dartleDir → const String
Location of the dartle directory within a project.
dartleFileMissingMessage → const String
'Missing dartle.dart file. ' 'Please create one to be able to use Dartle.'
dartleVersion → const String
profile → const Level
Custom log level used to report profiling results.
Level('PROFILE', 550)
taskArgumentPrefix → const String


dartleUsage String
Dartle usage message.
optionsDescription String
String describing Dartle's command-line options.
read / write


activateLogging(Level level, {bool colorfulLog = true, String? logName}) bool
Activate logging.
createCleanTask({required String name, String description = '', required Iterable<Task> tasks, TaskPhase phase = TaskPhase.setup}) Task
Create a "clean" task that removes all outputs of the given tasks.
createDartExe(File dartFile, [File? destination, DartleCache? dartleCache]) Future<File>
Compiles the given dartFile to an executable.
createTaskMap(Iterable<Task> tasks) Map<String, TaskWithDeps>
Create a Map from the name of a task to the corresponding TaskWithDeps.
deleteAll(FileCollection fileCollection) Future<void>
Delete all files and possibly directories included in the given fileCollection.
deleteOutputs(Iterable<Task> tasks) Future<void>
Deletes the outputs of all tasks.
dir(String directory, {Set<String> fileExtensions = const {}, Set<String> exclusions = const {}, bool recurse = true, bool includeHidden = false}) FileCollection
Create a FileCollection consisting of a directory, possibly filtering which files within that directory may be included.
dirs(Iterable<String> directories, {Set<String> fileExtensions = const {}, Set<String> exclusions = const {}, bool recurse = true, bool includeHidden = false}) FileCollection
Create a FileCollection consisting of multiple directories, possibly filtering which files within each directory may be included.
elapsedTime(Stopwatch stopwatch) String
entities(Iterable<String> files, Iterable<DirectoryEntry> directoryEntries) FileCollection
A File collection including the given files as well as DirectoryEntry's.
exec(Future<Process> process, {String name = '', dynamic onStdoutLine(String)?, dynamic onStderrLine(String)?}) Future<int>
Executes the given process, returning its exit code.
execProc(Future<Process> process, {String name = '', Set<int> successCodes = const {0}, StreamRedirectMode successMode = StreamRedirectMode.none, StreamRedirectMode errorMode = StreamRedirectMode.stdoutAndStderr}) Future<int>
Executes the given process, returning its exit code.
failBuild({required String reason, int exitCode = 1}) → void
Fail the build for the given reason.
file(String path) FileCollection
Create a FileCollection consisting of a single file.
files(Iterable<String> paths) FileCollection
Create a FileCollection consisting of multiple files.
getExeLocation(File dartFile, [DartleCache? dartleCache]) File
Get the location Dartle would store binaries created with the createDartExe method.
getInOrderOfExecution(List<TaskInvocation> invocations, [bool forceTasks = false, bool showTasks = false, DeletionTasksByTask tasksAffectedByDeletion = const {}]) Future<List<ParallelTasks>>
Get the tasks in the order that they should be executed, taking into account their dependencies and phases.
ignoreExceptions(FutureOr action()) FutureOr
Run the given action ignoring any Exceptions thrown by it.
isNoColorEnvVarSet() bool
Checks if the NO_COLOR environment variable is set.
parseInvocation(List<String> tasksInvocation, Map<String, TaskWithDeps> taskMap, Options options) List<TaskInvocation>
Parse the tasks invocation provided by the user.
parseOptions(List<String> args) Options
Parse the given args, setting the options as appropriate and returning the tasks the user requested to run.
run(List<String> args, {required Set<Task> tasks, Set<Task> defaultTasks = const {}, bool doNotExit = false}) Future<void>
Initializes the dartle library and runs the tasks selected by the user (or in the provided args).
runBasic(Set<Task> tasks, Set<Task> defaultTasks, Options options, DartleCache cache) Future<void>
Run a Dartle build with a "basic" setup.
runDartExe(File dartExec, {List<String> args = const [], String? workingDirectory, Map<String, String>? environment}) Future<Process>
Run a Dart binary created via the createDartExe method.
runSafely(List<String> args, bool doNotExit, FutureOr<void> action(Stopwatch, Options)) Future<void>
Run the given action in a safe try/catch block, allowing Dartle to handle any errors by logging the appropriate build failure.
runTask(TaskInvocation invocation, {required bool runInIsolate}) Future<TaskResult>
Run a task unconditionally.
runTaskPostRun(TaskResult taskResult) Future<void>
runTasks(List<ParallelTasks> tasks, {required bool parallelize}) Future<List<TaskResult>>
Calls runTask with each given task that must run.
runTasksPostRun(List<TaskResult> results) Future<List<Exception>>
verifyTaskInputsAndOutputsConsistency(Map<String, TaskWithDeps> taskMap) Future<DeletionTasksByTask>
Verify that all tasks in taskMap have inputs/outputs that are mutually consistent.
verifyTaskPhasesConsistency(Map<String, TaskWithDeps> taskMap) Future<void>
Verify that all tasks in taskMap lie in phases that are consistent with their dependencies.


Supported log colors.
Defines which stream(s) should be redirected to the calling process' streams from another running Process when using the execProc function.
Status of a task.


DeletionTasksByTask = Map<String, Set<String>>

Exceptions / Errors

Exception thrown when the build must be aborted immediately.
Indicates a fatal error during a dartle build.
A DartleException caused by multiple Exceptions, usually due to multiple asynchronous actions failing simultaneously.