dartle_dart library

Dartle extension for building Dart projects.

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.
DartConfig
Configuration for the DartleDart class.
DartleDart
Dartle built-in functionality for Dart projects.
DirectoryEntry
A directory entry, usually used within a FileCollection.
DoNotAcceptArgs
An ArgsValidator which does not accept any arguments.
ExceptionAndStackTrace
ExecReadResult
Result of calling execRead.
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.
TestTaskArgsValidator
TextAnsiMessagePart

Enums

DartTestOutput
The type of outputs to use for tests.
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.

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<void>
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<int>, List<int>>? encoder}) → Future<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<int>, List<int>>? decoder}) → Future<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

DeletionTasksByTask = Map<String, Set<String>>
IncrementalAction = FutureOr<void> Function(List<String> args, [ChangeSet? changeSet])
Signature of the action of incremental Tasks.

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.