dartle library
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.
- AnsiMessage
- A log message that may be displayed with ANSI modifiers (i.e. fore/background colors and styles).
- AnsiMessagePart
- ArgsCount
- Validates the the number of arguments passed to a Task.
- ChangeSet
- The change Set for an incremental action.
- CodeAnsiMessagePart
- 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.
- ExceptionAndStackTrace
- ExecReadResult
- Result of calling execRead.
- FileChange
- FileChange represents a file system entity change.
- 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.
- NoEncoding
- A no-op implementation of Converter.
- Options
- Dartle configuration options.
- OrCondition
- A RunCondition that runs if any of its conditions runs.
- ParallelTasks
- PlainMessage
- A Message that is always printed in "plain text" (i.e. no colors or styles, no log formatting).
- 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.
- 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.
- TextAnsiMessagePart
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.
Mixins
- ArgsValidator
- Validator of arguments passed to a Task.
- FilesCondition
- A RunCondition that uses file-system inputs and outputs.
- Message
- A Message that can be logged by the Dartle logger without using the logging pattern, and potentially adding terminal styling such as with ColoredLogMessage and AnsiMessage.
- ResolvedEntity
- RunCondition
- A run condition for a Task.
- RunConditionCombiner
- Base mixin for a RunCondition that combines other RunConditions.
Extensions
Constants
- dartleDir → const String
- Location of the dartle directory within a project.
- dartleFileMissingMessage → const String
- dartleVersion → const String
-
defaultSuccessfulStatusCodes
→ const Set<
int> - The default successful status codes for HTTP responses.
- profile → const Level
- Custom log level used to report profiling results.
- taskArgumentPrefix → const String
Properties
- dartleUsage → String
-
Dartle usage message.
no setter
- optionsDescription ↔ String
-
String describing Dartle's command-line options.
getter/setter pair
Functions
-
activateLogging(
Level level, {bool colorfulLog = true, String? logName}) → bool - Activate logging.
-
createCleanTask(
{String name = 'clean', String description = '', required Iterable< Task> tasks, TaskPhase phase = TaskPhase.setup}) → Task - Create a "clean" task that removes all outputs of the given tasks.
-
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, bool allowAbsolutePaths = 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, bool allowAbsolutePaths = false}) → FileCollection - Create a FileCollection consisting of multiple directories, possibly filtering which files within each directory may be included.
-
download(
Uri uri, {void headers(HttpHeaders)?, void cookies(List< Cookie> )?, bool isSuccessfulStatusCode(int) = _isSuccessfulStatusCode, SecurityContext? context, Duration connectionTimeout = const Duration(seconds: 10)}) → Stream<List< int> > - Download binary data from the given Uri.
-
downloadJson(
Uri uri, {void headers(HttpHeaders) = _jsonHeader, void cookies(List< Cookie> )?, bool isSuccessfulStatusCode(int) = _isSuccessfulStatusCode, SecurityContext? context, Duration connectionTimeout = const Duration(seconds: 10), Encoding encoding = utf8}) → Future<Object?> - Download JSON data from the given Uri.
-
downloadText(
Uri uri, {void headers(HttpHeaders) = _plainTextHeader, void cookies(List< Cookie> )?, bool isSuccessfulStatusCode(int) = _isSuccessfulStatusCode, SecurityContext? context, Duration connectionTimeout = const Duration(seconds: 10), Encoding encoding = utf8}) → Future<String> - Download plain text from the given Uri.
-
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 = '', bool isCodeSuccessful(int) = _onlyZero, StreamRedirectMode successMode = StreamRedirectMode.none, StreamRedirectMode errorMode = StreamRedirectMode.stdoutAndStderr}) → Future<int> - Executes the given process, returning its exit code.
-
execRead(
Future< Process> process, {String name = '', bool stdoutFilter(String) = filterNothing, bool stderrFilter(String) = filterNothing, bool isCodeSuccessful(int) = _onlyZero}) → Future<ExecReadResult> - Executes the given process, returning its output streams line-by-line.
-
failBuild(
{required String reason, int exitCode = 1}) → Never -
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.
-
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.
-
homeDir(
) → String? - Get the user HOME directory if possible.
-
ignoreExceptions(
FutureOr action()) → FutureOr< bool> -
Run the given action ignoring any Exceptions thrown by it.
Returns
true
if the action succeeded,false
otherwise. -
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<List< ParallelTasks> > - Run a Dartle build with a "basic" setup.
-
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, bool allowIncremental = true}) → Future< TaskResult> - Run a task unconditionally.
-
runTaskPostRun(
TaskResult taskResult) → Future< void> -
runTasks(
List< ParallelTasks> tasks, {required bool parallelize, bool disableCache = false, bool force = false}) → Future<List< TaskResult> > - Calls runTask with each given task that must run.
-
runTasksPostRun(
List< TaskResult> results) → Future<List< ExceptionAndStackTrace> > -
tar(
FileCollection fileCollection, {required String destination, String destinationPath(String)?, Converter< List< ? encoder}) → Future<int> , List<int> >File> - Tar all files in the given fileCollection into the destination file.
-
taskOutputs(
Task task) → FileCollection? - Get the outputs of a Task.
-
tempDir(
{String suffix = ''}) → Directory -
Get a Directory with a random name inside the
Directory.systemTemp
directory. -
tempFile(
{String extension = ''}) → File -
Get a File with a random name inside the
Directory.systemTemp
directory. -
untar(
String tarFile, {required String destinationDir, Converter< List< ? decoder}) → Future<int> , List<int> >Directory> - Untar a tar file's contents into the given destinationDir.
-
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.
Typedefs
Exceptions / Errors
- DartleException
- Indicates a fatal error during a dartle build.
- HttpCodeException
- MultipleExceptions
- A DartleException caused by multiple Exceptions, usually due to multiple asynchronous actions failing simultaneously.
- ProcessExitCodeException
- Exception thrown by execRead when the process fails by completing with a non-success exit code.