diff --git a/maven-site/src/site/apt/lifecycle.apt b/maven-site/src/site/apt/lifecycle.apt new file mode 100644 index 0000000000..0a9d895ad0 --- /dev/null +++ b/maven-site/src/site/apt/lifecycle.apt @@ -0,0 +1,208 @@ + ------ + Build Lifecycle + ------ + Brett Porter + ------ + 16 June 2005 + ------ + +Build Lifecycle + +* 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 + and distributing a particular artifact is clearly defined. + + For the person building a project, this means that it is only necessary to learn a small set of commands to build any + Maven project, and the POM will ensure they get the results they desired. + + The most common lifecycle phases that would be executed on a project are the following: + + * <<>> - validate the project is correct and all necessary information is available + + * <<>> - compile the source code of the project + + * <<>> - test the compiled source code using a suitable unit testing framework. These tests should not + require the code be packaged or deployed + + * <<>> - take the compiled code and package it in its distributable format, such as a JAR. + + * <<>> - process and deploy the package if necessary into an environment where integration tests + can be run + + * <<>> - run any checks to verify the package is valid and meets quality criteria + + * <<>> - install the package into the local repository, for use as a dependency in other projects locally + + * <<>> - done in an integration or release environment, copies the final package to the remote repository + for sharing with other developers and projects. + + Note that for each of these steps, all previous steps are always executed, so you only need to specify the last one + you desire on the command line. For example: + +------- +m2 install +------- + + This command will compile, test, package, verify and install the package into the local repository when run. + + There are more commands that are part of the lifecycle, which will be discussed in the following sections. + + It should also be noted that the same command can be used in a multi-module scenario. For example; + +------ +m2 clean:clean install +------ + + This command will traverse into all of the subprojects and run <<>>, then <<>> (including all of + the prior steps). + +* Setting up your Project to Use the Build Lifecycle + + The build lifecycle is simple enough to use, but when you are constructing a Maven build for a project, how do you go + about assigning tasks to each of those build phases? + +** Packaging + + The first, and most common way, is to set the <<>> for your project. This defaults to <<>>, so whether + you have specifically done it or not, this has already happened. Each packaging contains a list of goals to bind to + a particular phase. For example, a JAR will add the following bindings to the lifecycle: + +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ +| <<>> | <<>> +*------------------------------+---------------------------------------------------------------------------------------+ + + This is an almost standard set of bindings, however, some packages handle them differently. For example, a project + that is purely metadata (packaging <<>>) only binds the <<>> and <<>> phases. + + Note that for some packaging tpyes to be available, you may also need to include a particular plugin in your + <<>> section, similarly to the next section. One example of a plugin that requires this is the Plexus plugin, + which provides a <<>> and <<>> packaging. + +** Plugins + + The second way to add goals to phases is to configure plugins in your project. As you will see in the later sections, + plugins contain information that says where to bind particular goals to. Note that adding the plugin on its own is not + enough information - you must also specify the goals you want run as part of your build. + + For example, the Modello plugin always binds <<>> to the <<>> phase. So to use the + Modello plugin and have it generate sources from a model and incorporate that into the build, you would add the + following to your POM in the <<>> section of <<>>: + +---- +... + + org.codehaus.modello + modello-maven-plugin + + + + maven.mdo + 4.0.0 + + + modello:java + + + + +... +---- + + You might be wondering why that executions element is there? That is so that you can run the same goal multiple times + with different configuration, if needed. Separate executions can also be given an ID so that during inheritence or the + application of profiles you can control whether goal configuration is merged or turned into an additional execution. + + When multiple executions are given that match a particular phase, they are executed in the order specified in the POM, + with inherited executions running first. + + Now, in the case of <<>>, it only makes sense in the <<>> phase. But some goals can be + used in more than one phase, and there may not be a sensible default. For those, you can specify the phase yourself. + For example, let's say you have a goal <<>> that echos the current time to file, and you want it to + run in the <<>> phase to indicate when the tests were started. This would be configured like + so: + +---- +... + + com.mycompany.example + touch-maven-plugin + + + process-test-resources + + ${project.output.directory}/timestamp.txt + + + touch:timestamp + + + + +... +---- + + TODO + +* Build Lifecycle Phase Reference + + The following phases are all the ones available as of the Maven 2.0 alpha-3 release. They are executed in the order + given, up to the point of the one specified. + +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | validate the project is correct and all necessary information is available. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | generate any source code for inclusion in compilation. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | process the source code, for example to filter any values. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | generate resources for inclusion in the package. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | copy and process the resources into the destination directory, ready for packaging. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | compile the source code of the project. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | post-process the generated files from compilation, for example to do bytecode enhancement on Java classes. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | generate any test source code for inclusion in compilation. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | process the test source code, for example to filter any values. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | create resources for testing. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | copy and process the resources into the test destination directory. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | compile the test source code into the test destination directory +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | take the compiled code and package it in its distributable format, such as a JAR. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | process and deploy the package if necessary into an environment where integration tests can be run. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | run any checks to verify the package is valid and meets quality criteria. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | install the package into the local repository, for use as a dependency in other projects locally. +*-------------------------------+--------------------------------------------------------------------------------------+ +| <<>> | done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects. +*-------------------------------+--------------------------------------------------------------------------------------+ + +* How the Build Lifecycle Affects Plugin Developers + + TODO + +