Source Code

This module defines the base elements of ceylon.build for declaring goals and tasks.

Goal

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.

Simple goal definition

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;
    }
};

Task definition

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);
    }
}

Goal with multiple tasks

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.

Dependencies

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.

Goals without tasks

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.

GoalSet

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.

License: [ASL 2.0](http://www.apache.org/licenses/LICENSE-2.0)
Packages
ceylon.build.task

ceylon.build tasks/goals API

ceylon.build tasks/goals API

Aliases
TaskSource Code
shared Task=> Outcome(Context)

a Task represents a Goal action.

It takes in input a Context giving access to:

  • arguments passed to that task's goal
  • a Writer allowing the task to write output messages.

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.

See also: done, Success, Failure
Values
doneSource Code
shared Success done

Returns a success Outcome

Functions
keepCurrentNameSource Code
shared String(String) keepCurrentName()

Returns a function that will not change the Goal name

prefixSource Code
shared String(String) prefix(String prefix)

Returns a function that will prefix the Goal name using the given prefix

suffixSource Code
shared String(String) suffix(String suffix)

Returns a function that will suffix the Goal name using the given suffix

Interfaces
WriterSource Code
shared Writer

Abstraction of standard output and error output streams

Classes
ContextSource Code
shared Context

Represents the current context of a Goal execution. It contains arguments passed to the current Goal and also a Writer for output reporting.

FailureSource Code
shared Failure

Represents a failed outcome

GoalSource Code
shared Goal

A Goal represents an action that can be launched by ceylon.build.engine

A Goal has:

  • a name which must be unique inside a build configuration. name will be used from command line to ask for the Goal execution.
  • a dependencies list that lists goals that must be executed before this goal.
  • a tasks list that lists tasks that have to be executed for that Goal.
GoalSetSource Code
shared GoalSet

A GoalSet represents a set of goals that can be imported together

OutcomeSource Code
shared abstract Outcome

Represents the outcome of a task

SuccessSource Code
shared Success

Represents a successful outcome with a message giving details about the outcome.

done attribute represents a success without any outcome details.