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.

Classes

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

Mixins

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

Extensions

TaskPhaseString
TaskStatusString

Constants

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

Properties

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

Functions

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.

Enums

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

Typedefs

DeletionTasksByTask = Map<String, Set<String>>

Exceptions / Errors

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