From 9ebc9a7c0da827b26b8646a32b29983d33d26895 Mon Sep 17 00:00:00 2001 From: Brett Leslie Porter Date: Thu, 16 Jun 2005 06:47:21 +0000 Subject: [PATCH] finish lifecycle doco git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@190880 13f79535-47bb-0310-9956-ffa450edef68 --- maven-site/src/site/apt/lifecycle.apt | 101 +++++++++++++++++++++++++- maven-site/src/site/site.xml | 1 + 2 files changed, 98 insertions(+), 4 deletions(-) diff --git a/maven-site/src/site/apt/lifecycle.apt b/maven-site/src/site/apt/lifecycle.apt index 8846fe7467..0a0f3b8209 100644 --- a/maven-site/src/site/apt/lifecycle.apt +++ b/maven-site/src/site/apt/lifecycle.apt @@ -8,6 +8,8 @@ Build Lifecycle + <> this documentation is current only as of alpha-3, and is not yet completely implemented, even in Subversion. + * Build Lifecycle Basics Maven 2.0 is based around the central concept of a build lifecycle. What this means is that the process for building @@ -117,7 +119,7 @@ m2 clean:clean install 4.0.0 - modello:java + java @@ -150,7 +152,7 @@ m2 clean:clean install ${project.output.directory}/timestamp.txt - touch:timestamp + timestamp @@ -270,7 +272,98 @@ m2 clean:clean install ** Forking a Parallel Lifecycle - TODO - + While lots of mojos will participate in the standard lifecycle, there are just as many that are used in other + scenarios. These are mojos that are executed standalone from the command line (such as <<>>), or individual + reports in the site building process. + + However, sometimes these goals require that a particular task has already been performed - for instance, the IDEA + plugin must ensure sources have been generated to properly construct its module files. If the goal were participating + in the lifecycle, it would easily do this by ensuring it occurred after the phase it depended on having run. Since + this isn't the case, it must have a way to first execute that task. + + Additionally, even goals participating in the build lifecycle might need to perform a task with different parameters + to what was already used, and does not want the output to affect the current build (for example, running + <<>> to run tests with modified sources and fail if a certain coverage ratio is not achieved). + + For these reasons, mojos are capable of forking a new lifecycle. The lifecycle will be a normal build lifecycle, + a clone of the one currently being used (including any additional bindings from the POM), executed up until the point + specified by the mojo. + + For example, the <<>> mojo specifies the following in the mojo level declarations to call the source + generation: + +---- +@execute phase="generate-sources" +---- + + But what happens if <<>> has already been run in this build? In the current version of Maven, there + is no way to tell if the previous execution used the same input and outputs as the current mojo requires, so the task + (and any preceding ones if from the lifecycle) must be run again. + + For this reason, it is important that if your plugin does any intensive work, you should first check whether it is + necessary to perform the tasks again, perhaps by using timestamp checking or a similar technique. As an example, + the compiler plugin will only recompile changed source files so can very efficiently be run multiple times in a build + if necessary. + + When the lifecycle is forked, the project object being used is also cloned. In this way, modifications made to the + project as part of the execution, such as the addition of a new source root, will not affect the original build. + When the lifecycle finishes executing and control is passed to the original mojo, it can access that project using + the expression <<<${executedProject}>>>. For example: + +---- +/** + * @parameter expression="${executedProject}" + */ +private MavenProject executedProject; +---- + + This project instance can be used by the mojo to obtain results, and propogate any changes it sees fit into the + original build. + + Finally, when forking the new lifecycle, it is possible to augment it on top of the changes already made by the + packaging and the plugins in the POM. + + For example, consider the Clover plugin. If <<>> were to be run from the command line, the plugin + would need to fork the lifecycle, executing the <<>> phase. But, it would also need to add some configuration + and bind the <<>> goal to the <<>> phase. + + This can be achieved by including the following file as <<>> in the plugin JAR: + +---- + + + clover + + + generate-sources + + + + true + + clover:compiler + + + + + + + + +---- + + Here, the <<>> element is present in a similar way to a plugin declaration in the POM. This can be used + to bind a goal one or more times to a particular phase, as well as specifying configuration. Note that configuration + already provided in the POM to that plugin that is not part of a specific execution will also be applied. + + The lifecycle ID given here, <<>> can then be used in the mojo to specify what to overlay on the forked + lifecycle when executing it, using the following mojo level declaration: + +---- +@execute phase="test" lifecycle="clover" +---- + + For more information about plugin development in general, see the + {{{developers/plugin-overview.html} Developer's Section}}. diff --git a/maven-site/src/site/site.xml b/maven-site/src/site/site.xml index 3da96fdd8d..38403b462e 100644 --- a/maven-site/src/site/site.xml +++ b/maven-site/src/site/site.xml @@ -25,6 +25,7 @@ +