This module defines the base elements of ceylon.build
for declaring goals and tasks.
ceylon.build.engine
is designed to work with goals.
A Goal represents an action that can be launched by the engine. It has a name and a tasks list.
Goal.name
is used in command line to ask for a goal execution.Goal.tasks
is a list of operations that will be executed in order when the goal name is specified.Goal.dependencies
is a list of goals that must be executed before current goal's tasks.Here is an example of how to define a simple Goal
:
Goal hello = Goal { name = "hello"; function(Context context) { context.writer.info("Hello World!"); return done; } };
A Task is an operation that will be executed when the goal name is specified.
It takes a Context in input and returns an Outcome object telling if task execution succeed or failed.
Here is an example of a simple task that will display "Hello World!"
message:
Outcome helloTask(Context context) { context.writer.info("Hello World!"); return done; }
A task can also return a success / failure message
Outcome myTask(Context context) { try { processMyXXXTask(); return Success("operation xxx done"); } catch (Exception exception) { return Failure("failed to do xxx", exception); } }
A goal can have several tasks.
Goal myGoal = Goal { name = "myGoal"; function(Context context) { context.writer.info("starting"); return done; }, function(Context context) { context.writer.info("running"); return done; }, function(Context context) { context.writer.info("stopping"); return done; } };
They will all be executed in order when goal execution is requested. If one of the tasks fails, execution will stop and failure will be reported.
A goal can also define dependencies to other goals. Dependencies will be executed (even if not explicitly requested) before all other goals in the execution list that depend on those.
Goal compile = Goal { name = "compile"; function(Context context) { context.writer.info("compiling!"); return done; } }; Goal run = Goal { name = "run"; dependencies = [compile]; function(Context context) { context.writer.info("running!"); return done; } };
With the above code, requesting execution of run
goal will result in execution of goals compile
followed by run
.
It is possible to define a goal that don't have any tasks like below:
Goal testGoal = Goal { name = "test"; };
Such a goal is useless, because it will not trigger any tasks execution.
However, if dependencies are added it becomes a great way to group goals.
Requesting the execution of a such goal will cause the execution (as for any goals) of all of its dependencies. The execution of those dependencies will be done in the order of declaration as long as dependencies between goals of the current execution list are satisfied. If they are not, goals will be re-ordered to satisfy dependencies.
Here is an example:
Goal compileGoal = Goal { name = "compile"; compile { modules = "my.module"; } }; Goal compileTestsGoal = Goal { name = "compile-tests"; compileTests { modules = "test.my.module"; } }; Goal runTestsGoal = Goal { name = "run-tests"; runModule { moduleName = "test.my.module"; version = "1.0.0"; } }; Goal testGoal = Goal { name = "test"; dependencies = [compileTestsGoal, runTestsGoal]; };
Execution of testGoal
will result in execution of goals compileTestsGoal
followed by runTestsGoal
.
As a goals without tasks is like any other goal from a dependency point of view, it can be used as a dependency which enables interesting constructions like below:
Goal fullBuild = Goal { name = "full-build"; dependencies = [compileGoal, test]; };
Execution of fullBuild
will trigger execution of compileGoal
, compileTestsGoal
and then runTestsGoal
.
A GoalSet is a set of goals that can be imported in a build configuration.
For example, if a ceylonModule
goal set provides goals to compile, compile tests, run tests
and document a ceylon module and you have differents ceylon modules in your build, then,
you are likely to want to rename "compile"
, "tests-compile"
, "test"
and "doc"
to something
like "compile.mymodule1"
, "tests-compile.mymodule1"
, …
Here is an example of goal set definition from ceylon.build.tasks.ceylon
module
"Returns a `GoalSet` providing compile, tests-compile, test and doc goals for a ceylon module." shared GoalSet ceylonModule( "module name" String moduleName, "test module name" String testModuleName = "test.``moduleName``", "test module version" String testModuleVersion = "1.0.0", "rename function that will be applied to each goal name." String(String) rename = keepCurrentName()) { return GoalSet { Goal { name = rename("compile"); compile { modules = moduleName; } }, Goal { name = rename("tests-compile"); compile { modules = testModuleName; sourceDirectories = testSourceDirectory; } }, Goal { name = rename("test"); runModule { moduleName = testModuleName; version = testModuleVersion; } }, Goal { name = rename("doc"); document { modules = moduleName; } } }; }
It can be used as following:
GoalSet ceylonModuleA = ceylonModule { moduleName = "moduleA"; rename = suffix(".a"); }; GoalSet ceylonModuleB = ceylonModule { moduleName = "moduleB"; rename = suffix(".b"); };
This will import goals "compile.a"
, "tests-compile.a"
, "test.a"
, "doc.a"
,
"compile.b"
, "tests-compile.b"
, "test.b"
, "doc.b"
in the build configuration.
Packages | |
ceylon.build.task | ceylon.build tasks/goals API |
ceylon.build tasks/goals API
Aliases | |
Task | Source Code a It takes in input a Context giving access to:
It returns an Outcome object. In case the task execution is successful, task should return a Success object. Otherwise, it should return a Failure object. |
Values | |
done | Source Code shared Success done Returns a success |
Functions | |
keepCurrentName | Source Code shared String(String) keepCurrentName() Returns a function that will not change the Goal name |
prefix | Source Code shared String(String) prefix(String prefix) Returns a function that will prefix the Goal name using the given |
suffix | Source Code shared String(String) suffix(String suffix) Returns a function that will suffix the Goal name using the given |
Interfaces | |
Writer | Source Code shared Writer Abstraction of standard output and error output streams |
Classes | |
Context | Source Code shared Context Represents the current context of a |
Failure | Source Code shared Failure Represents a failed outcome |
Goal | Source Code shared Goal A A
|
GoalSet | Source Code shared GoalSet A |
Outcome | Source Code shared abstract Outcome Represents the outcome of a task |
Success | Source Code shared Success Represents a successful outcome with a message giving details about the outcome. done attribute represents a success without any outcome details. |