/
introduction-to-the-lifecycle.apt
446 lines (353 loc) · 27.7 KB
/
introduction-to-the-lifecycle.apt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
------
Introduction to the Build Lifecycle
------
Brett Porter
------
2006-06-16
------
~~ Copyright 2006 The Apache Software Foundation.
~~
~~ Licensed under the Apache License, Version 2.0 (the "License");
~~ you may not use this file except in compliance with the License.
~~ You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
Introduction to the Build Lifecycle
* Table Of Contents
* {{{Build_Lifecycle_Basics}Build Lifecycle Basics}}
* {{{Setting_Up_Your_Project_to_Use_the_Build_Lifecycle}Setting Up Your Project to Use the Build Lifecycle}}
* {{{Packaging}Packaging}}
* {{{Plugins}Plugins}}
* {{{Lifecycle_Reference}Lifecycle Reference}}
* {{{Built-in_Lifecycle_Bindings}Built-in Lifecycle Bindings}}
[]
* {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 (project) 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 {{{./introduction-to-the-pom.html}POM}} will ensure they get the results they desired.
There are three built-in build lifecycles: default, clean and site. The default lifecycle handles your project
deployment, the clean lifecycle handles project cleaning, while the site lifecycle handles the creation of your
project's site documentation.
** {A Build Lifecycle is Made Up of Phases}
Each of these build lifecycles is defined by a different list of build phases, wherein a build phase represents a
stage in the lifecycle.
For example, the default lifecycle has the following build phases (for a complete list of the build phases, refer
to the {{{Lifecycle_Reference}Lifecycle Reference}}):
* <<<validate>>> - validate the project is correct and all necessary information is available
* <<<compile>>> - compile the source code of the project
* <<<test>>> - test the compiled source code using a suitable unit testing framework. These tests should not
require the code be packaged or deployed
* <<<package>>> - take the compiled code and package it in its distributable format, such as a JAR.
* <<<integration-test>>> - process and deploy the package if necessary into an environment where integration tests
can be run
* <<<verify>>> - run any checks to verify the package is valid and meets quality criteria
* <<<install>>> - install the package into the local repository, for use as a dependency in other projects locally
* <<<deploy>>> - done in an integration or release environment, copies the final package to the remote repository
for sharing with other developers and projects.
These build phases (plus the other build phases not shown here) are executed sequentially to complete the default
lifecycle. Given the build phases above, this means that when the default lifecycle is used, Maven will first validate
the project, then will try to compile the sources, run those against the tests, package the binaries (e.g. jar), run
integration tests against that package, verify the package, install the verifed package to the local repository,
then deploy the installed package in a specified environment.
To do all those, you only need to call the last build phase to be executed, in this case, <<<deploy>>>:
-------
mvn deploy
-------
That is because if you call a build phase, it will execute not only that build phase, but also every build phase
prior to the called build phase. Thus, doing
-------
mvn integration-test
-------
will do every build phase before it (<<<validate>>>, <<<compile>>>, <<<package>>>, etc.), before executing <<<integration-test>>>.
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 (i.e. a project with one or more
subprojects). For example:
------
mvn clean install
------
This command will traverse into all of the subprojects and run <<<clean>>>, then <<<install>>> (including all of
the prior steps).
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
** {A Build Phase is Made Up of Plugin Goals}
However, even though a build phase is responsible for a specific step in the build lifecycle, the manner in which it
carries out those responsibilities may vary. And this is done by declaring the plugin goals bound to those build phases.
A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a
project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of
the build lifecycle by direct invocation. The order of execution depends on the order in which the goal(s) and the build phase(s) are
invoked. For example, consider the command below. The <<<clean>>> and <<<package>>> arguments are build phases, while the
<<<dependency:copy-dependencies>>> is a goal (of a plugin).
------
mvn clean dependency:copy-dependencies package
------
If this were to be executed, the <<<clean>>> phase will be executed first (meaning it will run all preceeding phases of the clean lifecycle,
plus the <<<clean>>> phase itself), and then the <<<dependency:copy-dependencies>>> goal, before finally executing the
<<<package>>> phase (and all its preceeding build phases of the default lifecycle).
Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.
Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it,
that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals
(<Note: In Maven 2.0.5 and above, multiple goals bound to a phase are executed in the same order as they are declared in the
POM, however multiple instances of the same plugin are not supported. Multiple instances of the same plugin are grouped to execute together and ordered in
Maven 2.0.11 and above>).
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
* {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 packaging for your project via the equally named POM element <<<\<packaging\>>>>. Some of the valid
packaging values are <<<jar>>>, <<<war>>>, <<<ear>>> and <<<pom>>>. If no packaging value has been specified, it will default
to <<<jar>>>.
Each packaging contains a list of goals to bind to a particular phase. For example, the <<<jar>>> packaging will bind the following
goals to build phases of the default lifecycle.
*------------------------------+---------------------------------------------------------------------------------------+
| <<<process-resources>>> | <<<resources:resources>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<compile>>> | <<<compiler:compile>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<process-test-resources>>> | <<<resources:testResources>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<test-compile>>> | <<<compiler:testCompile>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<test>>> | <<<surefire:test>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<package>>> | <<<jar:jar>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<install>>> | <<<install:install>>>
*------------------------------+---------------------------------------------------------------------------------------+
| <<<deploy>>> | <<<deploy:deploy>>>
*------------------------------+---------------------------------------------------------------------------------------+
This is an almost standard set of bindings; however, some packagings handle them differently. For example, a project
that is purely metadata (packaging value is <<<pom>>>) only binds goals to the <<<install>>> and <<<deploy>>> phases (for a
complete list of goal-to-build-phase bindings of some of the packaging types, refer to the
{{{Lifecycle_Reference}Lifecycle Reference}}).
Note that for some packaging types to be available, you may also need to include a particular plugin in the
<<<\<build\>>>> section of your POM and specify <<<\<extensions\>true\</extensions\>>>> for that plugin.
One example of a plugin that requires this is the Plexus plugin, which provides a <<<plexus-application>>> and
<<<plexus-service>>> packaging.
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
** {Plugins}
The second way to add goals to phases is to configure plugins in your project. Plugins are artifacts that provide
goals to Maven. Furthermore, a plugin may have one or more goals wherein each goal represents a capability of that
plugin. For example, the Compiler plugin has two goals: <<<compile>>> and <<<testCompile>>>. The former
compiles the source code of your main code, while the latter compiles the source code of your test code.
As you will see in the later sections, plugins can contain information that indicates which lifecycle phase to bind a
goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want
to run as part of your build.
The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected.
If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed
first, followed by those configured in the POM. Note that you can use the <<<\<executions\>>>> element to gain more
control over the order of particular goals.
For example, the Modello plugin binds by default its goal <<<modello:java>>> to the <<<generate-sources>>> phase (Note: The
<<<modello:java>>> goal generates Java source codes). 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 <<<\<plugins\>>>> section of
<<<\<build\>>>>:
----
...
<plugin>
<groupId>org.codehaus.modello</groupId>
<artifactId>modello-maven-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<configuration>
<models>
<model>src/main/mdo/maven.mdo</model>
</models>
<version>4.0.0</version>
</configuration>
<goals>
<goal>java</goal>
</goals>
</execution>
</executions>
</plugin>
...
----
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 inheritance 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 <<<modello:java>>>, it only makes sense in the <<<generate-sources>>> 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 <<<display:time>>> that echos the current time to the commandline, and you want
it to run in the <<<process-test-resources>>> phase to indicate when the tests were started. This would be configured
like so:
----
...
<plugin>
<groupId>com.mycompany.example</groupId>
<artifactId>display-maven-plugin</artifactId>
<version>1.0</version>
<executions>
<execution>
<phase>process-test-resources</phase>
<goals>
<goal>time</goal>
</goals>
</execution>
</executions>
</plugin>
...
----
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
* {Lifecycle Reference}
The following lists all build phases of the default, clean and site lifecycle, which are executed in the order given
up to the point of the one specified.
<<Clean Lifecycle>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<pre-clean>>> | executes processes needed prior to the actual project cleaning
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<clean>>> | remove all files generated by the previous build
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<post-clean>>> | executes processes needed to finalize the project cleaning
*-------------------------------+--------------------------------------------------------------------------------------+
<<Default Lifecycle>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<validate>>> | validate the project is correct and all necessary information is available.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<initialize>>> | initialize build state, e.g. set properties or create directories.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-sources>>> | generate any source code for inclusion in compilation.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-sources>>> | process the source code, for example to filter any values.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-resources>>> | generate resources for inclusion in the package.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-resources>>> | copy and process the resources into the destination directory, ready for packaging.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<compile>>> | compile the source code of the project.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-classes>>> | post-process the generated files from compilation, for example to do bytecode enhancement on Java classes.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-test-sources>>> | generate any test source code for inclusion in compilation.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-test-sources>>> | process the test source code, for example to filter any values.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-test-resources>>> | create resources for testing.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-test-resources>>> | copy and process the resources into the test destination directory.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test-compile>>> | compile the test source code into the test destination directory
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-test-classes>>> | post-process the generated files from test compilation, for example to do bytecode enhancement on Java classes. For Maven 2.0.5 and above.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test>>> | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<prepare-package>>> | perform any operations necessary to prepare a package before the actual packaging. This often results in an unpacked, processed version of the package. (Maven 2.1 and above)
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<package>>> | take the compiled code and package it in its distributable format, such as a JAR.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<pre-integration-test>>> | perform actions required before integration tests are executed. This may involve things such as setting up the required environment.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<integration-test>>> | process and deploy the package if necessary into an environment where integration tests can be run.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<post-integration-test>>> | perform actions required after integration tests have been executed. This may including cleaning up the environment.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<verify>>> | run any checks to verify the package is valid and meets quality criteria.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<install>>> | install the package into the local repository, for use as a dependency in other projects locally.
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<deploy>>> | done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
*-------------------------------+--------------------------------------------------------------------------------------+
<<Site Lifecycle>>
*-------------------------------+--------------------------------------------------------------------------------------+
| pre-site | executes processes needed prior to the actual project site generation
*-------------------------------+--------------------------------------------------------------------------------------+
| site | generates the project's site documentation
*-------------------------------+--------------------------------------------------------------------------------------+
| post-site | executes processes needed to finalize the site generation, and to prepare for site deployment
*-------------------------------+--------------------------------------------------------------------------------------+
| site-deploy | deploys the generated site documentation to the specified web server
*-------------------------------+--------------------------------------------------------------------------------------+
<{{{./introduction-to-the-lifecycle.html}[top]}}.>
* {Built-in Lifecycle Bindings}
Some phases have goals bound to them by default. And for the default lifecycle, these bindings depend on
the packaging value. Here are some of the goal-to-build-phase bindings.
** Clean Lifecycle Bindings
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<clean>>> | <<<clean:clean>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** Default Lifecycle Bindings - Packaging <<<ejb>>> / <<<ejb3>>> / <<<jar>>> / <<<par>>> / <<<rar>>> / <<<war>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-resources>>> | <<<resources:resources>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<compile>>> | <<<compiler:compile>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-test-resources>>> | <<<resources:testResources>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test-compile>>> | <<<compiler:testCompile>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test>>> | <<<surefire:test>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<package>>> | <<<ejb:ejb>>> <or> <<<ejb3:ejb3>>> <or> <<<jar:jar>>> <or> <<<par:par>>> <or> <<<rar:rar>>> <or> <<<war:war>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<install>>> | <<<install:install>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<deploy>>> | <<<deploy:deploy>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** Default Lifecycle Bindings - Packaging <<<ear>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-resources>>> | <<<ear:generate-application-xml>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-resources>>> | <<<resources:resources>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<package>>> | <<<ear:ear>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<install>>> | <<<install:install>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<deploy>>> | <<<deploy:deploy>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** Default Lifecycle Bindings - Packaging <<<maven-plugin>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<generate-resources>>> | <<<plugin:descriptor>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-resources>>> | <<<resources:resources>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<compile>>> | <<<compiler:compile>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<process-test-resources>>> | <<<resources:testResources>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test-compile>>> | <<<compiler:testCompile>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<test>>> | <<<surefire:test>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<package>>> | <<<jar:jar>>> <and> <<<plugin:addPluginArtifactMetadata>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<install>>> | <<<install:install>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<deploy>>> | <<<deploy:deploy>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** Default Lifecycle Bindings - Packaging <<<pom>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<package>>> | <<<site:attach-descriptor>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<install>>> | <<<install:install>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<deploy>>> | <<<deploy:deploy>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** Site Lifecycle Bindings
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<site>>> | <<<site:site>>>
*-------------------------------+--------------------------------------------------------------------------------------+
| <<<site-deploy>>> | <<<site:deploy>>>
*-------------------------------+--------------------------------------------------------------------------------------+
** References
The full Maven lifecycle is defined by the file <<<components.xml>>> in the module <<<maven-core>>> and viewable from SVN in the branch for
{{{http://svn.apache.org/repos/asf/maven/maven-2/tags/maven-2.2.1/maven-core/src/main/resources/META-INF/plexus/components.xml}Maven 2.2.1}}
and Git for {{{https://git-wip-us.apache.org/repos/asf?p=maven.git;a=blob;f=maven-core/src/main/resources/META-INF/plexus/components.xml}Maven 3.x}}.
In Maven 2.x, default lifecycle bindings were included in <<<components.xml>>>, but in Maven 3.x, they are defined in a separate
<<<{{{https://git-wip-us.apache.org/repos/asf?p=maven.git;a=blob;f=maven-core/src/main/resources/META-INF/plexus/default-bindings.xml}default-bindings.xml}}>>>
descriptor.
See {{{/ref/current/maven-core/lifecycles.html}Lifecycles Reference}} and
{{{/ref/current/maven-core/default-bindings.html}Plugin Bindings for default Lifecycle Reference}} for latest documentation taken directly from
source code.
<{{{./introduction-to-the-lifecycle.html}[top]}}.>