| ------ |
| Guide to Using Maven when You Can't Use the Conventions |
| ------ |
| Brett Porter |
| ------ |
| 2005-12-05 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you 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 |
| |
| Using Maven When You Can't Use the Conventions |
| |
| There is a common misconception that Maven can't build a project that doesn't conform to certain directory |
| structures or build practices. This often isn't the case - however it is true that some Maven features or plugins |
| (especially by third parties) may not work or work completely. |
| |
| This guide will help you set up Maven on your project when the directive from on high is to not change the existing |
| layout, and detail some of the feature that you might miss when doing so. |
| |
| <The Maven developers highly recommend you use this as a last resort. There are good reasons why the defaults are |
| the way they are, and we strongly recommend you use them if you can. It encourages consistency and means one less |
| thing you ever need to worry about when starting a new project - there are more interesting things to do then |
| change your layout for the sake of it! Hopefully having used any of these techniques you find that Maven proves itself |
| capable, you will reconsider restructuring to address these issues.> |
| |
| * Using Multiple Source Directories |
| |
| This occurs when you are producing a single JAR (or other artifact), and have several source directories with classes |
| you want to include. |
| |
| ** Why isn't this recommended? |
| |
| ... |
| |
| ~~TODO |
| |
| ** How do I do this? |
| |
| ... |
| |
| ~~TODO |
| |
| ** What are the limitations? |
| |
| There should be no limitations in this approach. Maven natively supports multiple source directories for the purposes |
| of generated sources. |
| |
| * Producing Multiple Unique JARs from a Single Source Directory |
| |
| As many people that complain about not being able to spread out their sources into multiple source directories seem |
| to complain about not wanting to spread anything out, producing several unique artifacts from a single directory |
| using includes and excludes. |
| |
| ** Why isn't this recommended? |
| |
| This practice can be confusing and risky. |
| |
| * You may end up building two JARs that include the same classes - this indicates that the common functionality |
| should have been abstracted into a separate dependency. |
| |
| * You may end up introducing a dependency between the two JARs that you didn't realise, and often a circular |
| dependency. This indicates that the classes are in the wrong JAR, or perhaps that everything should just be a |
| single JAR. |
| |
| ** How do I do this? |
| |
| You still should adhere to producing one artifact per POM, but this requires having multiple POMs, and hence |
| multiple subdirectories. The positive to this is that these introduced directories won't change the layout of existing |
| code, and will establish a future layout should you decide to separate. |
| |
| Here is an example of setting it up when there is a project with two JARs produced: <<<core>>> and <<<module>>>. |
| |
| You might like to review the {{{../getting-started/} Getting Started Guide}} |
| ~~ or {{{guide-multi-module.html} Guide to Using Multiple Modules}} |
| that demonstrates how this is normally done in Maven, as it is quite similar. |
| |
| Your directory will look something like this: |
| |
| -------- |
| / |
| +- pom.xml |
| +- src/ |
| +- main/ |
| +- java/ |
| +- core/ |
| +- Core.java |
| +- module/ |
| +- Module.java |
| -------- |
| |
| First, you set up your <<<pom.xml>>> at the top level not to produce anything, but to include the other modules we plan to create: |
| |
| +-------- |
| <project> |
| <artifactId>my-parent</artifactId> |
| <packaging>pom</packaging> |
| ... |
| <modules> |
| <module>core</module> |
| <module>module</module> |
| </modules> |
| </project> |
| +-------- |
| |
| Next, the modules themselves are created. Here is the <<<core/pom.xml>>> file you should create. The one in the |
| <<<module>>> subdirectory will be similar. |
| |
| +-------- |
| <project> |
| <modelVersion>4.0.0</modelVersion> |
| <parent> |
| <groupId>my-groupId</groupId> |
| <artifactId>my-parent</artifactId> |
| <version>1.0-SNAPSHOT</version> |
| </parent> |
| |
| <artifactId>my-core</artifactId> |
| |
| <build> |
| <sourceDirectory>../src/main/java</sourceDirectory> |
| |
| <plugins> |
| <plugin> |
| <artifactId>maven-compiler-plugin</artifactId> |
| <version>2.0.2</version> |
| <configuration> |
| <includes><include>**/core/**</include></includes> |
| </configuration> |
| </plugin> |
| </plugins> |
| </build> |
| </project> |
| +-------- |
| |
| In this example, the sources are found in the parent directory <<<../src/main/java>>>, and only Java files within a |
| <<<core>>> package are included. |
| |
| The final result when building will look like this: |
| |
| -------- |
| / |
| +- pom.xml |
| +- src/ |
| +- main/ |
| +- java/ |
| +- core/ |
| +- Core.java |
| +- module/ |
| +- Module.java |
| +- core/ |
| +- pom.xml |
| +- target/ |
| +- my-core-1.0-SNAPSHOT.jar |
| +- module/ |
| +- pom.xml |
| +- target/ |
| +- my-module-1.0-SNAPSHOT.jar |
| -------- |
| |
| ** What are the limitations? |
| |
| There is no universal inclusion/exclusion specification, so each plugin needs to be configured individually, and some |
| might not have that capability. In particular, expect that site reports may include all sources, for example. |
| |
| * Producing Multiple JARs from a single POM |
| |
| Source directories aside, sometimes people desire to produce multiple JARs from a single POM. Depending on your use case, Maven |
| can support this. |
| |
| * If you are looking to produce JARs that are different (ie, they have their own dependencies and metadata), Maven |
| doesn't support this. This usually is only needed when sharing a source directory for intrinsically different things, |
| so the use case above applies instead. |
| |
| * If you are producing a JAR that is a derivative of the original (eg, just a subset of classes, or the same JAR with |
| debugging enabled), the Maven supports this completely using profiles. See {{{../introduction/introduction-to-profiles.html} Introduction to Profiles}} |
| for more information. |