diff --git a/content/apt/archives/maven-2.x/index.apt b/content/apt/archives/maven-2.x/index.apt deleted file mode 100644 index c629528aea..0000000000 --- a/content/apt/archives/maven-2.x/index.apt +++ /dev/null @@ -1,48 +0,0 @@ - --- - Maven 2 Graveyard - --- - Karl-Heinz Marbaise - --- - 2014-03-22 - ------ - -~~ 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. - - -This is the Maven 2 Graveyard - - Based on a decision for the End Of Lifetime of Maven 2 - this location is intended as a graveyard for Maven 2 only related information and links. - -* Plugin List - - The following list of plugins contains plugins which are Maven 2 specific. Apart from - that for those plugins which are listed here there are no updates/bug fixes planned etc. - - -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+ -|| <> || <> || <> || <> || <> || <> -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+ -| <> | | | | <> -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+ -| {{{/plugins/maven-reactor-plugin/} <<>>}} | B | 1.0 | 2008-09-27 | Build a subset of interdependent projects in a reactor | 2014-03-24 -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ - - \* <>uild or <>eporting plugin - - [] diff --git a/content/apt/archives/maven-2.x/maven-2.1-architectural-goals.apt b/content/apt/archives/maven-2.x/maven-2.1-architectural-goals.apt deleted file mode 100644 index 0f0bba1537..0000000000 --- a/content/apt/archives/maven-2.x/maven-2.1-architectural-goals.apt +++ /dev/null @@ -1,321 +0,0 @@ -h1. Maven 2.1 -- Jason van Zyl - -~~ 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. - -Discussion: need some answers to these before even pushing this to the list -TODO: Jesse and Greg spent a lot of time getting the async SSL working so a little description this work would be useful -TODO: architecture document about Mercury transport as the async HTTP/DAV client -TODO: example of user facing API for Mercury -TODO: architecture document and spec for mercury (largely in the wiki) -TODO: example of user facing API for maven-shared-model -TODO: architecture document on maven itself, plugin manager, lifecycle executor, profile construction -TODO: check with kenney to see if his work survived in substituting components or if it's his work that's actually making it work - -Technical Preparation: not necessary before discussions can start but helpful to help guide how we concretely determine backward compat -TODO: get an explanation of the process Arnaud and Benjamin have for plugins. I started by capturing the log -TODO: document standard setup for Hudson we have so people can see the results of testing -TODO: setup hudson with emma for code coverage and ask VELO to help us setup coverage for integration tests - -h2. Architectural Goals - -h3. Backward Compatibility - -We must ensure that plugins and reports written against the Maven 2.0.x APIs remain to work in 2.1. We don't want people to have to rewrite -their plugins. There are several plugins that are using the current artifact resolution code that will not be supported (please see the Mercury section below). The -ones that are in our control we can port over to use Mercury, and external users will have to deal with the major version change. Most people will not be affected and -Mercury will be a far better solution. - -We must also ensure that POMs of version 4.0.0 are supported in 2.1.x along with the behavior currently experienced. We are relying heavily on our integrations tests right -now but as we move forward the work that Shane is doing on the project builder with maven-shared-model will help us to accommodate different versions of a POM, and different -formats we decide to support. The maven-shared-model code has no limitation to formats of XML, or any of format like YAML, script, or anything else anyone can dream up. These -implementations may find use outside of Maven. For example someone might build something with the Maven Embedder, JRuby, and Mercury to create a JRuby-based system. The -same could be done for Groovy, or Intercal. - -h2. Plugin and Extension Loading - -Maven's mechanisms for loading plugins and build extensions has been refactored. You can find more information in the [Maven 2.1 Plugin and Extension Loading Design] document. - -h2. Lifecycle - -h3. Aggregator Mojo Handling - -Aggregator mojos bound to the lifecycle have been deprecated. This practice can produce some very strange results, and isn't really the right solution for many of the problems it attempts to solve. I'm hoping to include some better options for bracketing the normal build - both before, and after, explicitly - to make aggregator mojos obsolete, but for now they've been deprecated to avoid disrupting backward compatibility. - -Also, aggregator mojos that *are* bound to the lifecycle will only be allowed to execute at most once during the build, to limit redundant execution. These mojos are meant to act on all projects in the reactor at once, and binding them to one pom.xml file is dangerous in that it can produce different build results depending on whether that pom.xml is included. This is further complicated if two modules in a reactor configure the same aggregator mojo...in which case, it may run multiple times...or, when the aggregator is configured in the parent pom, where it will run for each descendant module. - -h2. Plugin API - -h3. Shading of plexus-utils causing a ClassCastException on plugin.getConfiguration() ([MNG-3012|http://jira.codehaus.org/browse/MNG-3012]) - - The fact that plexus-utils is hidden from plugins in the newer releases of Maven means that plugin.getConfiguration() from maven-model can cause a ClassCastException, if used from within a mojo. The plan to fix this is basically just to import Xpp3Dom from the shaded plexus-utils version in maven-core within the plugin's classrealm. This should allow us to share the same instance of that class (only, shouldn't really affect other p-u classes) and preserve backward compatibility for existing plugin releases. - -comment from kenney: -The problem with this is that it's a hack. If xpp3dom/plexus utils is updated and the plugin requires the new xpp3dom class, which has a new method for instance, this will break the plugin. - -About this specific issue (MNG-3012): The best solution is to only share java., javax., and core maven api classes, so we can no longer export anything outside the plugin api (which includes maven-model, maven-project, maven-settings e.a.). This would require to phase out plugin.getConfiguration() and other model methods that return xpp3dom classes, and let them return interfaces present in the maven core api. Those interfaces would have an implementation class that implements both that interface and extends xpp3dom, which will be hidden for the plugin. Another solution could be to use xmlplexusconfiguration - -There's one more solution to consider; using ASM to rewrite plugins as they're loaded. We could add code modifiers that workaround incompatibilities by detecting usage patterns, like (Xpp3Dom) plugin.getConfiguration(). An example could be to modify the code to wrap Xpp3DomParser.parse( new StringReader( String.valueOf( /plugin.getConfiguration()/ ) ) ) around the call. This is even more of a hack though. Perhaps a mojo that scans for plugin incompatibilities using ASM is more feasible (no code modification). - -So the basic problem we're up against is that there can be core api changes between major versions that pose incompatibilities for plugins written against an older version. The simplest solution would be to let plugins specify the maven versions they work against (which is partly present: 2.0.6. If this field supports a versionrange, or we'd default the version interpretation above to mean [2.0.6,2.1), we can detect plugins that won't run. The shading mentioned above is solving only one incompatibility problem, and there are bound to be more. Maybe we even need 2 versions of a plugin at some point, targeted toward different maven versions, though I'd really like to avoid that. But we cannot just assume our 2.0 plugin api will never change across 'major' (read: minor) releases. - -h3. Strategies for ensuring backward compatibility - - -* Plugin integration testing - -{code} -jason: so when you and benjamin went through the tests you have "integration-tests" as the standard hook in the plugin build to grab on to? -[07:59am] jason: why is the activator a property negation? why don't you just run in hudson with -Pintegration-tests? -[08:02am] jason: i want to document what you and benjamin have done as a strategy for ensuring backward compatibility -[08:03am] ltheussl left the chat room. (Client closed connection) -[08:04am] aheritier: I started with this idea to have an additional profile that we activate with a property like integration-tests=true -[08:05am] jason: yah, i think -Pintegration-tests=true in a schedule in hudson is fine -[08:05am] jason: don't think the skip property is necessary -[08:05am] bentmann joined the chat room. -[08:05am] aheritier: but others showed me that he major part of existing integration tests were activated with skipTests ! true -[08:05am] aheritier: I asked why -[08:05am] aheritier: they said it was to be sure to launch it by default -[08:06am] aheritier: but to have the possibility to deactivate them if we skip tests -[08:06am] jason: sure, so by default they run -[08:07am] aheritier: yes. -[08:07am] aheritier: I prefer to activate them if I want -[08:07am] jason: yes -[08:07am] aheritier: not to have them always -[08:07am] jason: i agree that should be the pattern -[08:07am] aheritier: it's too long -[08:07am] jason: a smoke test in one mode -[08:07am] jason: and then turn them all on in hudson -[08:07am] aheritier: it's why we invented CI servers -[08:07am] aheritier: yes -[08:07am] eu left the chat room. (Ping timeout) -[08:08am] jason: i will document the setup but you and ben should figure out the pattern you want for a given plugin test -[08:08am] jason: and i'll document this as a strategy for testing 2.1 -[08:08am] eu joined the chat room. -[08:08am] ekuleshov is now known as eu. -[08:08am] jason: as i would like to take your setup, and parameterize the version of maven -[08:08am] jason: so when some changes are made in 2.1 i'll run the plugin smoke test first -[08:09am] jason: make sure nothing we change in the apis or hooks is screwed up -[08:09am] jason: and then run the ITs to make sure those plugins are working -[08:09am] jason: i already know a handful that are not working -[08:09am] bentmann: jason: How exactly do you intend to parametrize the Maven version? As far as I see, you only need to run them with the Maven of your choice. -[08:10am] jason: by taking the existing build, read the job, and change the version -[08:10am] jason: i have tools for reading/writing jobs -[08:10am] jason: but even low tech cloning the job and changing the maven installation -[08:10am] bentmann: So the parametrization is limited to the Hudson job config, right? -[08:11am] jason: actually you could parameterize anything if you control the job reading/writing -[08:11am] eu left the chat room. (Ping timeout) -[08:11am] jason: but this is something kohsuke added himself about a week ago -[08:11am] jason: in hudson itself -[08:11am] jason: i will create a set of parameters to test old/new versions of maven with a given set of plugins -[08:12am] jason: this is a great start, we couldn't do it if the plugins didn't have the same hook -[08:12am] jason: so all the maven plugin builds now have "integration-tests" profiles? -[08:12am] bentmann: Well, not all, only those that ITs before. -[08:12am] ekuleshov joined the chat room. -[08:12am] veleno left the chat room. (veleno) -[08:13am] jason: well that's a start and they are at least consistent now -[08:13am] ekuleshov is now known as eu. -[08:13am] jason: which is a great start -[08:13am] bentmann: I believe you just need to try to setup a Hudson job with Maven 2.1 to build "maven-plugins" and see what's missing in terms of config -[08:14am] jason: not sure what you mean -[08:14am] bentmann: IIRC, both Invoker and Shitty were picking up the maven.home from the currently running Maven, so the ITs should inherit that -[08:14am] jason: also, do you guys have a quick way to tell what plugins don't have ITs? -[08:14am] bentmann: Seach for src/it... -[08:15am] jason: yes, i want to make more a report but i can do that -[08:15am] jason: so anything that does have ITs you guys have made consistent? -[08:15am] jason: yes? -[08:15am] bentmann: Not sure what kind of consistency you actually require -[08:16am] bentmann: The IT profile should be named equal for all of them -[08:16am] bentmann: by inheriting from the parent -[08:16am] i386_ left the chat room. (i386_) -[08:16am] bentmann: whether the are run by Invoker or Shitty shouldn't matter, I guess -[08:17am] jason: no, the actual project just needs a profile name the same. not taken from the parent but stated in the project itself -[08:17am] jason: though the parent could specify that profile which just echos "No ITs" -[08:17am] jason: so in a run we would know which plugins don't have ITs at all -[08:17am] bentmann: Ah, I see -[08:17am] jason: so i can try what i want and that's a great start -[08:18am] jason: if our plugins don't all have ITs i cannot reasonably test 2.1 -[08:18am] jason: and any discussion about compatibility is pointless until that's done -{code} - -h3. POM changes - -There are many changes that users have requested in the POM, in addition to wholesale formatting changes. Acommodating these requests is a little tricky -because we need to support different versions simultaneously so that if projecta A builds with 2.0.x, project B can consume the project A POM using 2.1.x. -We just need some way to easy support multiple versions and support mediation between the different versions. - -* Tags: loose categorization people to use to help categorize as they see fit -* Categories: more standard categories that form over time by using category structures that exist or common tags that are used so often they become categories -* Dendency excludes: being to transitively exclude a dependency -* Properties on dependencies -* Specification Dependencies -* Schematron/RelaxNG descriptor for each plugin -- Bryon Jacob proposed a flexible model but XSD is hard to fight here so I'm not sure how far this will go - -h3. Embedding - -Full embedding of the Maven core is a major feature of the 2.1.x line. The embedder was created primarily for IDE integration and is now being consumed by m2eclipse, Mevenide and IDEA, -but the embedder is also used by the Maven CLI to ensure parity between IDEs and the CLI as much as possible. To understand how the embedder work you can refer to -the [Maven Embedder documentation|http://maven.apache.org/guides/mini/guide-embedding-m2.html]. - -h3. Custom Components - -As discussed in [Substituting of Custom Components|http://docs.codehaus.org/display/MAVEN/Substitution+of+Custom+Maven+Components] we now have two ways -to insert new components into the system. - -* Using a directory and specifying it in the Classworlds configuration. Tycho simply has a special set of components that load first before the standard maven components and they override - the standard Maven components. Here's the example based on what Tycho is currently doing which allows custom components to be used. - -{code} -main is org.apache.maven.cli.MavenCli from plexus.core - -set maven.home default ${user.home}/m2 - -[plexus.core] -load ${maven.home}/tycho/*.jar -load ${maven.home}/lib/*.jar -{code} - -* The embedder has the ContainerCustomizer which allow you to inject new component descriptors. This is used in the IDE integration (m2ecipse, Netbeans) for adding - custom artifact resolvers. - -But what we ultimately need for Tycho is a way to dynamically pull in a set of components based on the packaging of a project. In our case with Tycho the packaging is -maven-osgi-bundle and that should kick in the set of components that do builds for OSGi bundles. We also have another use case in Tycho where we are building OSGi bundles -without a POM and actually using a manifest. In this case we need to somehow detect the manifest and then have the custom set of components kick in. In the case of Tycho -we need a different project builder, and artifact resolver. - -h3. Mercury - -Mercury is a replacement for the current Maven Artifact subsystem, and a complete replacement for the HTTP and DAV portions of the existing transport. - -The primary reasons for replacing the code are that it is unmaintainable and nearly impossible to navigate, it uses completely non-standard structures and libraries for -version calculations, the API is too hard for people to use, and it is not given to users to consume as a single componment to use. Users are forced to know how several -complicated components interact in order to implement a mechanism of retrieving artifacts from a repository. The entire mechanism needs to be replaced with something -that can be maintained and is reliable. - -Mercury started as some fixes to Maven Artifact to first help with embeddability and error reporting for IDE integration. This was a direct result of all IDE integrators -having to reimplement the current artifact resolver to provide decent feedback to users when errors occured. The artifact subsystem would just die and leave the IDE in -an unusable state. Milos was the first to implement his own artifact resolver, and Eugene soon had to do the same in m2eclipse. Oleg and I were also trying to use the -current artifact mechanism in an embedded mode for some Eclipse plugins and this also proved to be quite painful. After the first attempt of removing the fail-fast -behavior, Oleg and I decided to make a break from the old codebase and attempt to create Mercury with the following goals in mind: - -* Find the best people in the world to help create an awesome HTTP and DAV implementation. We did this by talking to Greg, Jan, and Jesse who are the Jetty folks - and there just isn't anyone who knows HTTP better. Greg and Jan are awesome, and Jesse is Maven committer so we have some deep understanding of the issues involved. So - what Oleg and I wanted to see was: -** Easy SSL support where mucky with certificates in the default install is not required. -** Connection pooling -** Connection parallelization -** Built in DAV client support for deployment -** Atomic retrieval: we make sure absolutely everything is been safely transported to disk before we place it in the local Maven repository -** Atomic deployment: in this case we could only support this using a special filter Greg created which blocks requests for any artifacts being deploy in the current - set until the entire set land safely to disk. So it becomes impossible to ask for an artifact that refers to something else in the set before it is actually available. -** Starting thinking about a client that can understand GeoIP. Given the recent spikes in traffic we are going to start needing to distribute the load. - -* Find the best solution possible solution for dealing with version calculations, in particular ranges. For this we called on Daniel Le Berre and ask for some help in - integrating his SAT4J library. We learned about the SAT4J library from the P2 project over at Eclipse.org at the last EclipseCon. SAT4J was deemed the best way forward - by the P2 team in providing the most reliable, and most workable solution for doing version calculation. SAT4J provides ways to plug-in strategies to deal with our - scopes, conflict resolution strategies and it is deadly fast. We felt we are in good company as we can call on Daniel and the P2 team and collaborate when difficult - problems arise. - -* Find the best people to help with with security. This might an SSL-based solution to secure the channel where the source is known to be safe, a PGP-based solution where - the contents must be secured assuming a hostile channel, or a combination of the two. To that end I have contacted the folks at the Legion of the Bouncy Castle and asked - them to provide us the expertise to implement a safe and correct solution. I have not persued any help on the SSL. - -So in the end I believe it would be detrimental to use the Maven Artifact code in the 2.1.x tree and the change needs to be made to use Mercury before the first alpha ships. Oleg -and I started this work, and Oleg has subsequently worked tirelessly on Mercury along with a great deal of help from Greg, Jan and Jesse. I think Oleg understands the requirements -as he's seen Maven in action in one of the largest development environments in the world and watched how Maven can fail spectacularly. - -h3. Plugin API -* Symmetric output expressions -* Java5 Mojo annotations (Yoav Landman has this working already) -* Clean separation of plugins from reports. It's not good that those are the same thing in the Maven internals. -** Not using concrete XML classes in the Plugin API (Xpp3Dom) - -h3. Core Refactorings -* Project Builder ([architecture|http://docs.codehaus.org/display/MAVENUSER/Project+Builder]) -** Maven shared model work: a new way of reading in the models for Maven that is not format dependent in any way i.e. XML, text, YAML, scripts, whatever. -** Pluggable model readers: this could leverage different implementations provided by the shared model work, but we still need a way to detect the type and version - of the model that we want to consume -** A new terse format that uses attributes -** Automatic parent versioning -** New interpolation component (plexus-interpolation) -** Dynamic build sections ([MNG-3530|http://jira.codehaus.org/browse/MNG-3530]) -** Mixin support -- allowing a paramterizable template which can be imported with one line. - -* Remove the use of separate plugin repositories. We only need to pull resources from one repository. We started doing this but I've had a couple - clients that want to separate the tools they use from the code they are developing/building. -* Decouple script-based Plugins from the core -- we are a large part of the way here I need to summarize what was done. -* Remove Settings from the core and make it a user facing configuration (This is primarily done -- jason) -* Have one configuration model for request -* Have one configuration model for session: session takes the request in the constructor and delegates -* Domain logging -* Plugin Manager -** Removal of the Plugin Registry (done) -- we moved in a direction where people lock down their versions and we've helped by putting default versions - in the parent POM. -** Load Plugin dependencies into a separate ClassRealm (done) -** Plugin Execution Environment: Ability to run any version of a plugin where an environment is created which contains all the - requirements for a particular version of the Plugin API -* Lifecycle Executor -** Queryable Lifecycle -*** The most important change in the embedding environment. You can actually query Maven for the complete execution before it happens. We must know the entire - model of execution before we execute. -* OSGi-like Classloading to support isolated execution environments - -h3. Java 5 - -Java5 annotations for plugins: we have two implementations that have now been merged in plexus-cdc. QDOX 1.7 has now been released so we may want to check the -source level gleaning again. Jason Dillon has created a working class processing model. We need to deal with Plexus components and Maven plugins. - -h3. Integration and promotion of scriptable plugins - -h3. Toolchains -* Milos has implemented this and Shane had some feedback so this needs to be linked together - -h3. Reporting -* Report Execution Environment: Ability to run any version of a report where an environment is created which contains all the requirements for a particular version of the Report API. -* Decouple the reporting core. We need to get Doxia out of the core. Anything it needs to run should be isolated. - -h1. Other Use Cases to Integrate - -h2. Determining project type in Eclipse (Igor Fedorenko) - -Support for "java" projects in Eclipse has certain overhead and it is desirable to only enable for projects that actually require it. More specifically, java maven projects have JRE classpath container, maven classpath container, have java-specific UI elements enabled and are offered in various java-related searches. Also, tools like WTP and AJDT treat (eclipse) java projects specially. - -There is currently no direct way to tell if a (maven) project needs to be configured as java project in eclipse. The closest test condition I can think off is - -1 the project ArtifactHandler language=java - -and - -2.1 ArtifactHandler addedToClasspath=true - -or - -2.2 MavenProject.getCompileSourceRoots().size() > 0 - -or - -2.3 MavenProject.getTestCompileSourceRoots().size() > 0 - -(in other words the project is java and either itself is added to classpath or has sources to compile). - -This test will return false negative for some WAR projects (not added to classpath and don't have any sources to compile). Also, compileSourceRoots and testCompileSourceRoots only become fully populated after running maven build lifecycle, which is expensive. - -* Extensions -** Different categories of extensions: providers vs packaging vs PMD/Checkstyle resources stuff in a JAR -** Transparent Extension Loading -*** Any Wagon or SCM providers should get picked up automatically from SCM and distributionManagement URLs -*** Any extensions containing packaging/lifecycle related bits needs to be picked up automatically diff --git a/content/apt/developers/committer-environment.apt b/content/apt/developers/committer-environment.apt deleted file mode 100644 index 9247e4e17b..0000000000 --- a/content/apt/developers/committer-environment.apt +++ /dev/null @@ -1,54 +0,0 @@ - ------ - Developers centre - Committer Environment - ------ - Vincent Siveton - ------ - 2006-10-01 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Committer Environment - -* Introduction - - This document describes how to set up the Maven committer environment. - -* Source File Encoding - - When editing source files, make sure you use the right file encoding. For the Maven project, UTF-8 has been chosen - as the default file encoding. UTF-8 is an encoding scheme for the Unicode character set that can encode - all characters that Java can handle. The source files should not contain the byte order mark (BOM). There are - exceptions to this general rule. For instance, properties files are encoded using ISO-8859-1 as per the JRE API, so - please keep this in mind, too. - -* Maven Code Style - - Refer to {{{./conventions/code.html}Maven Code Style And Code Conventions}} - -* Useful software - - The Maven Team uses assorted software. Here is a partial list: - - * {{{https://www.cygwin.com/}Cygwin}}: collection of free software tools that allow various versions of Microsoft - Windows to act somewhat like a Unix system - - * {{{https://www.gnupg.org/}GnuPG}}: GNU Privacy Guard. diff --git a/content/apt/developers/committer-settings.apt b/content/apt/developers/committer-settings.apt deleted file mode 100644 index dbe1c62937..0000000000 --- a/content/apt/developers/committer-settings.apt +++ /dev/null @@ -1,81 +0,0 @@ - ------ - Developers centre - Committer Settings - ------ - Vincent Siveton - Dennis Lundberg - ------ - 2011-05-23 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Introduction - - This document is intended to set up the Maven committer settings, i.e. the <<<$\{user.home\}/.m2/settings.xml>>>. - -* Enable Apache Servers - - Maven uses several servers configuration to deploy snapshots and releases on the Apache servers. - You need to tell to Maven what your Apache username is. - - <>. - -+-----+ - - ... - - - - apache.snapshots.https - - - - - - apache.releases.https - - - - ... - - -+-----+ - -* Enable sending announcement e-mails - - To be able to send out announcements of Maven releases you need to add a couple - of properties to the <<>> profile. - -+-----+ - - ... - - - apache-release - - - - - - ... - - -+-----+ diff --git a/content/apt/developers/compatibility-plan.apt b/content/apt/developers/compatibility-plan.apt deleted file mode 100644 index fe59035559..0000000000 --- a/content/apt/developers/compatibility-plan.apt +++ /dev/null @@ -1,65 +0,0 @@ - ------ - Maven Plugins Compatibility Plan - ------ - Hervé Boutemy - ------ - 2020-05-20 - ------- - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Plugins Compatibility Plan - -* Scope - - This page describes the system requirements plan, which consists of: - - [[1]] minimum <> runtime prerequisite for Maven plugins, which can be extended to shared components, - - [[2]] minimum <> runtime prerequisite for plugins. - - [] - - Such requirements are displayed as "System Requirements" in every plugin info report (see {{{/plugins/maven-clean-plugin/plugin-info.html}this example}}). - - Consolidated view for all LATEST plugins release is visible in a {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/dist-tool-prerequisites.html}daily generated report}}. - -* Maven Plan - - * Until 2012, Maven 2.2.1 + Java 5 prerequisites, with plugins versions in 2.x - - * Since 2012, Maven 3.0 + Java 7 prerequisites, with plugins in 3.x.y - - * Since June 2020, Maven Plugin API used by plugins >= 3.1.0 + Java 8 prerequisites {{{https://s.apache.org/MVN-PLUGIN-MIGRATION-3.1}Technical details}} - - * In March 2023, Maven before 3.2.5 has been {{{/docs/history.html#maven-3-6-x-and-before}marked as EOL}}, meaning that plugins should use 3.2.5 as minimum - - * In April 2023, Maven before 3.6.3 has been {{{/docs/history.html#maven-3-6-x-and-before}marked as EOL}}, meaning that plugins should use 3.6.3 as minimum - - * In February 2024, Maven 4 after 4.0.0-alpha-12 will require Java 17 (as per {{{https://lists.apache.org/thread/bfkvvjftrxypp06yj8zj919fcz0dt2zt}vote on the Mailing List}}). - - [] - -* Context - - * Maven core history with Java prerequisite is available in the {{{/docs/history.html}release notes}} - - [] diff --git a/content/apt/developers/conventions/code.apt b/content/apt/developers/conventions/code.apt deleted file mode 100644 index aca633f8ee..0000000000 --- a/content/apt/developers/conventions/code.apt +++ /dev/null @@ -1,246 +0,0 @@ - ------ - Maven Code Style And Code Conventions - ------ - Vincent Siveton - ------ - 2008-07-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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Code Style And Code Conventions - - This document describes the rules for how the sources should be formatted - in order to improve consistency, readability and maintainability. - - As the formatting is automatically enforced or even applied with {{{https://github.com/diffplug/spotless/tree/main/plugin-maven}spotless-maven-plugin}} for all projects - using {{{/pom/maven/index.html}Maven Project Parent POM 38 or newer}} developers usually don't need to care and the following sections are just for informational purposes. - - Optionally you can still import the code style formatter for your IDE from - {{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=tree;f=src/main/resources/config;hb=HEAD}shared-resources}} - -%{toc|section=1|fromDepth=2|toDepth=3} - -* Generic Code Style And Convention - - All working files (java, xml, others) should respect the following conventions: - - * <>: Always add the current {{{https://www.apache.org/legal/src-headers.html#headers}ASF license header}} - in all files checked into the source code repository. - - * <>: No trailing whitespaces allowed. - - [] - - and the following style: - - * <>: <> use tabs! - - * <>: Always use a 120-column line width. - - [] - - <>: The specific styles and conventions, listed in the next sections, can override these generic rules. - -* {Java} - -** {Java Code Style} - - Maven adopts the {{{https://github.com/palantir/palantir-java-format}palantir Java format}}. - - -** {Java Code Convention} - - For consistency reasons, our Java code convention is mainly: - - * <>: Constants (i.e. static final members) should always be in upper case. - Use short, descriptive names for classes and methods. - - * <>: Avoid using public inner classes. Prefer interfaces instead of default implementation. - - * <>: Avoid using final modifier on all fields and arguments. - Prefer using private or protected fields instead of public fields. - - * <>: Throw meaningful exceptions to make debugging and testing easier. - - * <>: Document public interfaces well, i.e. all non-trivial public and - protected functions should include Javadoc that indicates what they do. - - * <>: All non-trivial public classes should have corresponding unit or - integration tests. - - [] - -** {Java Code Convention - import layouts} - - For consistency reasons, Java imports should be organized as: - - * import <> - - * import <> - - * blank line - - * import <> - - [] - - all imports in each group should be sorted alphabetically. - - To ensure a package import order consistent with the layout described above, download - <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-importorder.txt;hb=HEAD}maven-eclipse-importorder.txt}}>>>, select Preferences> and - navigate to Code Style \> Organize Imports>. Click on and select the downloaded - file to change the import order. - -** {JavaDoc Convention} - - TO BE DISCUSSED - -* {XML} - -** {XML Code Style} - - The Maven style for XML files is mainly: - - * <>: Always use 2 space indents, unless you're wrapping a new XML tags line in which case you should - indent 4 spaces. - - * <>: Always use a new line with indentation for complex XML types and no line break for simple XML - types. Always use a new line to separate XML sections or blocks, for instance: - -+-----+ - - This is a simple type - - - This is a complex type - - -+-----+ - - In some cases, adding comments could improve the readability of blocks, for instance: - -+-----+ - -+-----+ - - or - -+-----+ - - - -+-----+ - - [] - -** {Generic XML Code Convention} - - No generic code convention exists yet for XML files. - -** {POM Code Convention} - - The team has {{{https://lists.apache.org/thread/h8px5t6f3q59cnkzpj1t02wsoynr3ygk}voted}} - during the end of June 2008 to follow a specific POM convention to ordering POM elements. - The consequence of this vote is that the {{{https://maven.apache.org/ref/current/maven-model/maven.html}Maven project descriptor}} - is <> considered as the reference for the ordering. - - The following is the recommended ordering for all Maven POM files: - -+-----+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+-----+ - - <>: - - [[1]] The \ element is always on one line. - - [[2]] The blocks are voluntary separated by a new line to improve the readingness. - - [[3]] The dependencies in \ and \ tags have no specific ordering. Developers - are free to choose the ordering, but grouping dependencies by topics (like groupId i.e. <<>>) is a good practice. - - [] - - -** {XDOC Code Convention} - - For consistency and readability reasons, XDOC files should respect: - - * <>: Always specify metadata in the \ tag. - - * <>: Always use a new line with indentation for \
tags. - - [] - -** {FML Code Convention} - - For readability reasons, FML files should respect: - - * <>: Always use a new line with indentation for \ tags. - - [] - -~~ * {APT} Do we need any specific APT style/convention? diff --git a/content/apt/developers/conventions/git.apt b/content/apt/developers/conventions/git.apt deleted file mode 100644 index b08a99e352..0000000000 --- a/content/apt/developers/conventions/git.apt +++ /dev/null @@ -1,228 +0,0 @@ - ------ - Maven Git Convention - ------ - Olivier Lamy - ------ - 2012-09-12 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Git Convention - - This document describes how developers should use Git. - -* Git Configuration - -** For contributors who are not committers - - Apache git repositories are at -< <>>. However, the ASF - uses clones on github.com to make it easier for people to contribute - changes via pull requests. - - To contribute to a Maven component that is maintained in git, please - follow these steps: - - [[1]] create a JIRA for bug or improvement that you wish to work - on. The Maven project uses JIRA to organize and track our work, - and in particular to keep track of which changes are included in - which releases. - - [[2]] Make a fork of the official ASF clone from github.com. For - example, <<>>. - - [[3]] Make a branch named after your JIRA ticket. This is not , - but it makes it easier for Maven committers to keep track of your - contribution. - - [[4]] Make your changes. As always, unit or integration tests make - it much easier for us to accept your changes. - - [[5]] Make a pull request to pull your changes to the official clone. - Add a link to your pull request to the JIRA. Committers will take it - from here. - -** For committers - - Committers may, of course, commit directly to the ASF repositories. - For complex changes, you may find it valuable to make a pull request - at github to make it easier to collaborate with others. - -*** {Commit Message Template} - - Commits should be focused on one issue at a time, because that makes it easier - for others to review the commit. - - A commit message should use this template: - -------- -[ISSUE-1] <> -Submitted by: <> - -o Comments -------- - - Where: - - * <> can be omitted if there was no relevant JIRA issue, though you are strongly encouraged to create one for - significant changes. - - * <> only needs to be specified when a patch is being applied for a non-committer. - - * <> some optional words about the solution. - - [] - - eg: - -------- -[MNG-1456] Added the foo to the bar -Submitted by: Baz Bazman - -o Applied without change -------- - -* Apply User Patch - - To keep the history of contributions clear, - The committer should usually apply the patch without any <> - modifications, and then create his or her own commits for further - modifications. However, committers should never commit code to a live - branch which is not suitable to release. If a contribution requires - significant work to make it useful, commit it to a branch, fix it up, - and merge the branch. - - If the user created a pull request, the committer is responsible for - closing that pull request. You do this by adding a note to a commit - message: - ------- - Closes #NNN. ------- - - where NNN is the number of the pull request. - -* Edit Commit Message - - to edit last commit comment: - ---- -$ git commit --amend -m "new comment" ---- - -* Workflow - - Workflow for svn folks is something like : - ---- - $ git pull - $ hack hack hack - $ git push - // fails, because someone else has already pushed to master - $ git pull - // this creates some merges - $ git push ---- - - A more quiet workflow : - ---- -$ git pull -$ hack hack hack -$ git push -// fails, because someone else has already pushed to master -$ git fetch -// this moves 'origin/master' -$ git rebase origin/master -// this reapplies your local changes on top of origin/master -$ git push ---- - -* Other useful Git commands while developing - - If you've done a chunk of work and you would like to ditch your changes and start from scratch use this command to - revert to the original checkout: - ---- -$ git checkout . ---- - - TODO .gitignore - - - -** power-git checkout - - This checkout is typical for highly experienced git users, and may serve as inspiration for others; as usual the - best way to learn is by doing. Sample shown for maven-surefire - - Go to https://github.com/apache/maven-surefire and fork surefire to your own github account. - - Starting with nothing (no existing clone) - ---- -git clone https://github.com//maven-surefire.git -git remote add apache https://git-wip-us.apache.org/repos/asf/maven-surefire.git -git remote add asfgithub https://github.com/apache/maven-surefire.git -git config --add remote.asfgithub.fetch "+refs/pull/*/head:refs/remotes/asfgithub/pr/*" -git fetch --all ---- - (You may consider adding --global to the git config statement above to always fetch - pull requests for any remote named "asfgithub") - - In this setup, running "git push" will normally push to your personal github account. - Furthermore, all pull requests from github are also fetched to your local clone, use - ---- -gitk --all ---- - - to try to make some sense of it all. This is an important command to understand! (gitk may need to be installed additionally) - - gitk also has a quite excellent context menu that is far more context sensitive than most people realize at first impression. Right-clicking on a commit in a github pull-request will allow you to cherry-pick straight in the gui. - - - If you're working on the master branch, you can do stuff like this: - ---- -git push # your github account -git push apache # the authoritative apache repo ---- - - Using your github account as a storage for half-finished work is excellent if you switch between multiple computers, - always push to github before leaving your current computer and start by pulling at the next computer. - - To merge a pull request - ---- -git merge pr/10 # merge pull request number 10 from asf@github into master -git push apache # upload to apache ---- - - Or if you're comfortable with rebasing; - ---- - -git checkout pr/10 -git rebase apache/master -git push apache ---- diff --git a/content/apt/developers/dependency-policies.apt b/content/apt/developers/dependency-policies.apt deleted file mode 100644 index 60ab6a42e2..0000000000 --- a/content/apt/developers/dependency-policies.apt +++ /dev/null @@ -1,78 +0,0 @@ - ------ - Maven Dependency Policies - ------ - Stephen Connolly - ------ - 2011-02-01 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Dependency Policies - -* Scope - - This page describes the policies around the use of dependencies by the Apache - Maven Developers in the process of developing Apache Maven itself. - - This page does not apply to projects hosted outside of the Apache Maven - project. In order to remove all doubt, this page only applies to code - which has a Github URL that starts with - <<>> or a Gitbox URL - starting with <<>> - - If you have stumbled across this page and you are working on code that does - not have a Github URL starting with - <<>> then this page does not apply - to you. - -* Background - - The Apache Maven PMC is tasked with ensuring (among other things) that all - legal issues are addressed and that each and every release is the product - of the community as a whole. - - The Apache Maven project consists of quite a number of components. For - the purposes of this policy, we will make a distinction between the - core Maven distribution and all the other components. - - The core Maven distribution is the binary and source distributions made - available from the https://maven.apache.org/download page. - -* Applicability - - This policy applies to all changes to dependencies as and from Subversion revision 1067464. - -* Core Maven Distribution Dependencies - - All dependencies which are included in the Core Maven Distribution must either: - - * be licensed under a {{{https://www.apache.org/legal/resolved.html#category-a}Category A license}}; or - - * be licensed under a {{{https://www.apache.org/legal/resolved.html#category-b}Category B license}} and - approved by a majority vote of the Apache Maven PMC. - - Votes for Category B licenses will be held on the dev@maven.apache.org mailing list. A majority of the PMC - must vote in favour of a Category B licensed dependency before a release can be made containing that dependency. - -* Non-Core Dependencies - - Non-Core components may only use Category A or Category B licenses. diff --git a/content/apt/developers/index.apt b/content/apt/developers/index.apt deleted file mode 100644 index 6886ea21fb..0000000000 --- a/content/apt/developers/index.apt +++ /dev/null @@ -1,115 +0,0 @@ - ------ - Maven Developer Centre - ------ - Vincent Siveton - Brett Porter - ------ - 2015-02-14 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Developer Centre - - This documentation centre is for people who are Maven developers, or would like to contribute. - - If you cannot find your answers here, feel free to ask the {{{mailto:dev@maven.apache.org}Maven Developer List}}. - -* Contributors Resources - - * {{{../guides/development/guide-helping.html}Guide to helping with Maven}} - - * {{{../guides/development/guide-maven-development.html}Developing Maven}} - - * {{{../guides/development/guide-building-maven.html}Building Maven}} - - * {{{../scm.html}Source Code}} - - * {{{https://ci-maven.apache.org/job/Maven/job/maven-box/}Continuous Integration}} - - * {{{../plugin-developers/common-bugs.html}Common Bugs and Pitfalls}} - - * {{{../project-roles.html}Apache Maven Project Roles}} - - [] - -* Committers Resources - -** General Resources - - * {{{./welcome-to-new-committers.html}Guide for new Maven committers}} - - * {{{./committer-environment.html}Committer Environment}} - - * {{{./committer-settings.html}Committer Settings}} - - * {{{./retirement-plan-plugins.html}Retirement Plan for Plugins}} - - * {{{./dependency-policies.html}Maven Dependency Policies}} - - * {{{./compatibility-plan.html}Maven Plugins and Components Compatibility Plan}} - - * {{{https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=5964567}Maven Proposals/Backlog}} - - [] - -* Developers Conventions - - There are a number of conventions used in the Maven projects, which contributors and developers alike should follow for - consistency's sake. - - * {{{./conventions/code.html}Maven Code Style And Conventions}} - - * {{{./conventions/jira.html}Maven JIRA Convention}} - - * {{{./conventions/git.html}Maven Git Convention}} - - [] - - <>: If you cannot find your answers here, feel free to ask the {{{mailto:dev@maven.apache.org}Maven Developer List}}. - -* Making Releases - - * {{{./release/pmc-gpg-keys.html}Making GPG Keys}} - - * {{{./release/index.html}Release Process}} - - [] - -* Maven Website - - * {{{./website/index.html}Deploy Maven Website}} - - [] - -* Other Resources - - * {{{https://www.apache.org/dev/}ASF Development Infrastructure Information}} - - * {{{https://www.apache.org/foundation/}About the Apache Software Foundation}} - - [] - -~~TODO: tasks as buttons? - -~~TODO: de-dupe with existing documents in community - -~~TODO: clean up, have cookbook with more in depth documents like cutting releases, etc. diff --git a/content/apt/developers/release/index.apt b/content/apt/developers/release/index.apt deleted file mode 100644 index 385ac4edff..0000000000 --- a/content/apt/developers/release/index.apt +++ /dev/null @@ -1,48 +0,0 @@ - ----- - Releasing A Maven Project - ----- - Jason van Zyl - ----- - 2010-07-26 - ----- - -~~ 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. - -Releasing A Maven Project - - What follows is a description of releasing a Maven project to a staging repository and its documentation, whereupon - it is scrutinized by the community, approved, and transferred to a production repository. - - The steps involved are similar for any Apache project, with more specifics for parent POMs and - Maven itself. The steps involved, and the relevant documents for each, are listed below. - -~~ nothing specific: normal component * {{{./maven-plugin-release.html} Releasing a Maven plugin project}} - -~~ nothing specific: normal component * {{{./maven-shared-release.html} Releasing a Maven shared component or subproject}} - - * {{{./maven-core-release.html} Releasing Maven Core}} - - * {{{./parent-pom-release.html} Releasing a parent POM}} - - [] - - The above links all provide specific information for those types of releases, but they all refer back to the common documentation: - - * {{{./maven-project-release-procedure.html} Maven Project Common Release procedure}} - - [] diff --git a/content/apt/developers/release/maven-project-release-procedure.apt b/content/apt/developers/release/maven-project-release-procedure.apt deleted file mode 100644 index 1821abe391..0000000000 --- a/content/apt/developers/release/maven-project-release-procedure.apt +++ /dev/null @@ -1,384 +0,0 @@ - ----- - Releasing A Maven Project - ----- - Jason van Zyl - Karl Heinz Marbaise - ----- - 2018-04-07 - ----- - -~~ 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. - -Performing a Maven Project Release - - This document covers the common release procedures used by the Maven team to perform releases. - -* {Prerequisites} - - Be sure that: - - * you have a recent Git client installed and on your shell's path. - - * you have JDK 8 installed and on your shell's path to build Maven 3.7.0+. Details about minimum JDK version to build an appropriate version - can be found here: {{{/docs/history.html}https://maven.apache.org/docs/history.html}} - - * if you receive an OutOfMemoryError during the build, make sure to have set the environment variable <<>> - - * you must use Maven 3.3.9+. - - * follow Apache environment configuration steps outlined at: {{{https://www.apache.org/dev/publishing-maven-artifacts.html#dev-env}Publishing Maven Artifacts}}. - - * check {{{./pmc-gpg-keys.html} your Public GPG key}} which will be used for release. - - [] - -* Before you begin - - If you started here, you may first want to review one of the following documents that cover the specifics of various types of releases we have in the Maven Project: - - * {{{./maven-core-release.html} Releasing Maven Core}} - - * {{{./parent-pom-release.html} Releasing a parent POM}} - - [] - -* Consider updating the parent versions - - If the item you are planning to release is not using the most recent version of its parent - (see {{{../../pom/}parent POMs}} index), consider taking this opportunity to update to it. - -* Consider updating the project dependencies - - Generally it is a good that project use tha latest available versions of used dependencies. - -* Prepare release notes - - * check all commits since latest release, all mentioned issue should be connected with release notes - - * all issues should be <> to responsible person, which fixed or merged fix - - * all issues should be fixed and <> - - * check existing issues with <> priority, consider to fix it or change priority if reasonable - - [] - -** Check release note at GitHub - - If a component has a history of release notes at <>, we should to continue maintain it in order to avoid user confusing. - - We can maintain release notes at <>, by one of: - - * use release-drafter to help prepare release notes - in such case all PRs should a proper label - - * copy paste release notes from JIRA - - * put link to release notes in JIRA - - [] - - Draft of release notes at <> can be prepared before publishing. - -* Make sure that site compilation works - - Particularly if you update the parent or if you updated your javadoc, - the site compilation process may fail, or reveal a conspicuous error. It is stressful and time-consuming - to discover this *after* you stage a release and then try to follow - the procedure to deploy the site for review. So you may find it more - pleasant to check out the state of the site before you start: - ----- -mvn -Preporting site site:stage ----- - -* Stage the Release - - [[1]] Follow the release preparation, <> and <> the repository steps outlined in - {{{https://infra.apache.org/publishing-maven-artifacts.html}Publishing Maven Releases}}. - - Staging repository <<>> be closed with message like <<>> - - [[2]] Stage the latest documentation as explained in {{{../website/deploy-component-reference-documentation.html}deploying Maven components reference documentation}}. - -* Call the vote - - Propose a vote on the dev list with the closed issues, the issues left, - the staging repository and the staging site. For instance: - ------ -To: "Maven Developers List" -Subject: [VOTE] Release Apache Maven XXX Plugin version Y.Z - -Hi, - -We solved N issues: -https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=XXXXXX&version=YYYYYYY&styleName=Text - -There are still a couple of issues left in JIRA: -https://issues.apache.org/jira/issues/?jql=project%20%3D%20XXXXXXXXXX%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20key%20DESC%2C%20priority%20DESC - -Staging repo: -https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/ -https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/[PATH-TO]-source-release.zip - -Source release checksum(s): -[NAME-OF]-source-release.zip sha512: [SHA512SUM] - -Staging site: -https://maven.apache.org/plugins-archives/maven-XXX-plugin-LATEST/ - -Guide to testing staged releases: -https://maven.apache.org/guides/development/guide-testing-releases.html - -Vote open for at least 72 hours. - -[ ] +1 -[ ] +0 -[ ] -1 - ------ - - To get the JIRA release notes link, browse to the plugin's or component's JIRA page, select the link, pick a version, - and use the link to that is next to the version being released. - - To get the list of issues left in JIRA, browse to the plugin's or component's JIRA page, and from the - on the right, use the link for issues. - - The "vote is open for at least 72 hours" means that you need to wait 72 hours before proceeding. - This gives others time to test your release and check that everything is good. If after that period you have not received - enough +1 votes to reach the quorum, this doesn't mean the vote failed: it just takes a bit longer. - - Checking binary output, ideally to control that the build is reproducible, can be done by running <<>> (NOT <<>>) - followed by <<>> against the staged content: - ------ -mvn -Papache-release -Dgpg.skip clean verify \ - artifact:compare -Dreference.repo=https://repository.apache.org/content/repositories/staging/ ------ - - -* Check the vote results - - Copied from {{{https://www.apache.org/foundation/voting.html#ReleaseVotes}Votes on Package Releases}}. - ------ -Votes on whether a package is ready to be released use majority approval --- i.e. at least three PMC members must vote affirmatively for release, -and there must be more positive than negative votes. Releases may not be vetoed. -Generally the community will cancel the release vote if anyone identifies serious problems, -but in most cases the ultimate decision, lies with the individual serving as release manager. -The specifics of the process may vary from project to project, -but the 'minimum quorum of three +1 votes' rule is universal. ------ - - The list of PMC members is available at {{https://people.apache.org/committers-by-project.html#maven-pmc}}. - -** Successful vote - - Once a vote is <>, post the result to the <<>> list and cc the <<>>. For instance: - ------ -To: "Maven Developers List" -CC: "Maven Project Management Committee List" -Subject: [RESULT] [VOTE] Release Apache Maven XXX Plugin version Y.Z - -Hi, - -The vote has passed with the following result: - -+1 : <> - -PMC quorum: ... - -I will promote the source release zip file to Apache distribution area and the artifacts to the central repo. ------ - - Follow the procedure to the end. - -** Unsuccessful vote - - Once a vote is <>, post the result to the <<>> list, For instance: - ------ -To: "Maven Developers List" -Subject: [CANCEL] [VOTE] Release Apache Maven XXX Plugin version Y.Z - -Hi, - -The vote has been canceled. ------ - - For canceled vote the process will need to be restarted. - - Be sure to: - - * drop your staging repository as described in {{{https://www.apache.org/dev/publishing-maven-artifacts.html}Drop a repository}} - - * create new version for next round <<>> - - * assign issues from version <<>> also to version <<>> - - * mark the <<>> version as <> - - * report found issues and assign them to version <<>> - - * fix found issues - - [] - - Start the process for version <<>> from the beginning. - -* Copy the source release to the Apache Distribution Area - - The official Apache release is the 'source-release' bundle distributed in <<>>, - as described in {{{https://www.apache.org/dev/release-distribution}Apache Release Distribution Policy}}. - All releases for Maven must be copied to {{{https://www.apache.org/dist/maven/}the official Maven release area}}. - - The release area is maintained with svnpubsub. To deliver a release, you add it to - {{{https://dist.apache.org/repos/dist/release/maven}the subversion repository for the dist area}}: - add the release, its signature and sha512 checksum files, copying them from - <<>> directory created during <<>> step. - Currently this requires to be in maven-pmc group (see {{{https://issues.apache.org/jira/browse/INFRA-5945}INFRA-5945}}). - If you are not a PMC member, drop a line to and ask them to do this step (and the next one) for you: the PMC member will - get the source release bundle and its signature from Nexus staging repository and will create sha512 checksum file by hand, for example using shell: - --------- -for f in *.zip ; do echo -n $(sha512sum $f | cut -c -128) > $f.sha512 ; done --------- - - For example: - --------- -wagon/wagon-2.2-source-release.zip -wagon/wagon-2.2-source-release.zip.asc -wagon/wagon-2.2-source-release.zip.sha512 --------- - - You should also run 'svn rm' as needed to clear out older releases. As per {{{https://www.apache.org/legal/release-policy.html#where-do-releases-go}Apache Release Policy}}, - only the latest release on a branch should stay in the main dist areas. So long as the previous release is at least a day old, the automatic archiver - will have copied it to the archive. - - To check that everything is ok in the dist area, dist-tool-plugin has been written and run once a day to produce - {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/}"Check Source Release" and "Check Errors" reports}}. - -* Add the release for next board report - - After committing the 3 source-release files, visit {{{https://reporter.apache.org/addrelease.html?maven}Apache Committee Report Helper}} to add your release data with the Full Version Name and Date of Release. - (You will receive an e-mail for it as well). - - If you are not a PMC member, drop a line to and ask them to do this step for you if they did not do the update while adding to release area. - -* Promote the release - - Once the release is deemed fit for public consumption it can be transferred to a production repository where it will - be available to all users. - - [[1]] See {{{https://www.apache.org/dev/publishing-maven-artifacts.html#promote}Promoting a Repo}} for details on promotion. - - [[2]] Deploy the current website - - As above, deploy the web site if appropriate and update the project site for the - new release: use {{{../website/component-reference-documentation-helper.html}Component Reference Documentation Helper}} to generate commands or see - {{{../website/deploy-component-reference-documentation.html#Publishing_versioned_component_reference_documentation}Publishing versioned component reference documentation}} - for explanations. - Note that not all projects follow these conventions exactly. - - In case there's an overview table with version (e.g. {{{/plugins/index.html}plugins}}, {{{/shared/index.html}shared}}, {{{/skins/index.html}skins}}), update the table: you can directly edit it on the github page. - - For plugins and shared, you can also run <<>> of the site, then review and commit proposed <<>> updates. - - [[3]] Update the version tracking in JIRA - - In the relevant project, go to Administration, then Versions. Mark - the <<>> version as 'released'. Create version <<>>, if that hasn't already - been done. You may also archive any deprecated releases (milestones or alphas) at this time. - - Note: Currently this requires to be in the maven-pmc group. So, if you don't see the Administration option in JIRA, kindly ask to do this step for you. - - - [[4]] Wait for everything to sync - - [[a]] Sync to {{{https://repo.maven.apache.org/maven2/org/apache/maven/}Maven Central}} - - The sync into central staging from repository.apache.org occurs every 4 hours. - There is a separate hourly schedule that runs which pushes from staging to the other central machines, and then updates the indexes. - - [[b]] Sync to Maven Website - - If the project you are releasing doesn't yet use svnpubsub for site deployment, the deployment of the Maven website will {{{https://www.apache.org/dev/release-publishing.html#sync-delay}take an hour or so to sync}}. - - [] - - [[5]] Create an announcement. - - Following instructions are done for plugins: if you are releasing anything else than a plugin, you should adapt email content to match what you are releasing. - - <> You must send this email from your apache email account, e.g. YOUR_APACHE_USERNAME@apache.org otherwise - the email to <<>> will bounce. - ------ -From: YOUR_APACHE_USERNAME@apache.org -To: announce@maven.apache.org, users@maven.apache.org -Cc: dev@maven.apache.org -Subject: [ANN] Apache Maven XXX Plugin Y.Z Released - -The Apache Maven team is pleased to announce the release of the Apache Maven XXX Plugin, version Y.Z - -This plugin (insert short description of the plugin's purpose). - -https://maven.apache.org/plugins/maven-XXX-plugin/ - -You should specify the version in your project's plugin configuration: - - - org.apache.maven.plugins - maven-XXX-plugin - Y.Z - - -You can download the appropriate sources etc. from the download page: - -https://maven.apache.org/plugins/maven-XXX-plugin/download.cgi - -Release Notes - Maven XXX Plugin - Version Y.Z - -(Copy Here Release Notes in Text Format from JIRA) - -Enjoy, - --The Apache Maven team - ------ - - [[6]] If releasing the Apache Parent POM, notify <<>>: - Several projects follow this list, and should be made aware of changes to the common parent. - This might also be a step to take if other shared resources are released, or if plugin releases are - of particular interest to that group. - - If releasing Maven Core, notify <<>> - - [[7]] Publish release notes at <> if it is maintained. - - [[8]] Celebrate :o) - - [] - -* Check Consistency - - You can also check if you (or any previous release manager) did not miss any step by looking at the {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/dist-tool-check-errors.html} Dist Tool Check Errors report}}. - diff --git a/content/apt/developers/release/parent-pom-release.apt b/content/apt/developers/release/parent-pom-release.apt deleted file mode 100644 index 603c6c5431..0000000000 --- a/content/apt/developers/release/parent-pom-release.apt +++ /dev/null @@ -1,79 +0,0 @@ - ----- - Releasing A Parent POM - ----- - Hervé Boutemy - Dennis Lundberg - ----- - 2013-12-07 - ----- - -~~ 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. - -Releasing A Parent POM - - Releasing a Parent POM is much the same as any other Maven project. The following - guide walks through most of the steps: - - * {{{./maven-project-release-procedure.html} Maven Project Common Release procedure}} - - Note that Parent POMs have particular conventions for managing and deploying the documentation. - -* Rationale - - To be able to publish a documentation for the parent POM without affecting released <<>> and <<>>, - parent POM projects have a specific module, with the documentations <<>>. - -* Stage the release - - Then the only difference is with commands to stage the site: - - In Maven Apache Parent POM: - --------- -cd target/checkout -mvn -f docs site -mvn -f docs scm-publish:publish-scm --------- - - In Maven Projects Parent POM: - --------- -cd target/checkout -mvn -f docs site site:stage -mvn -f docs scm-publish:publish-scm --------- - -* Call the vote - - In the vote, additional to providing links to JIRA, the parent POMs should include a link to the Git changes since the - last release: - -------- -... -Hi, - -Changes since the last release: -for Maven Apache Parent POM: -https://github.com/apache/maven-apache-parent/compare/apache-...apache- - -or for Maven Projects Parent POM: -https://github.com/apache/maven-parent/compare/maven-parent-...maven-parent- - -Staging repo: -... -------- diff --git a/content/apt/developers/release/pmc-gpg-keys.apt b/content/apt/developers/release/pmc-gpg-keys.apt deleted file mode 100644 index cab855af1e..0000000000 --- a/content/apt/developers/release/pmc-gpg-keys.apt +++ /dev/null @@ -1,80 +0,0 @@ - ------ - Developers centre - Making GPG Keys - ------ - Vincent Siveton - ------ - 2006-10-01 - ------ - -~~ 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 - -Introduction - - <> a release You need to publish your Public GPG Keys in several place used by different tools for verifying release signatures. - - All Your historical Public Keys should be available for verifying historical releases, so please <> any key used sometime. - - All new <> keys generated should be at least <<4096>> bits. Do not generate new DSA keys. - -* Maven Project Keys - - Public Keys used for signing Maven core, plugins and shared components are available for users at:\ - {{https://downloads.apache.org/maven/KEYS}} - - You need edit a file and follow provided instructions in SVN at:\ - {{https://svn.apache.org/repos/asf/maven/project/KEYS}} - - General ASF instruction - - * {{{https://infra.apache.org/openpgp.html#update-KEYS}Update keys on the next release}} - - * {{{https://infra.apache.org/release-signing.html#keys-policy}The KEYS File}} - - [] - -* Distributing Your Public Keys - - Your Public Keys <> be available at public key server, - you can use one or even all of currently common used key server - - * {{https://keys.openpgp.org}} - - * {{https://keyserver.ubuntu.com}} - - * {{https://pgp.mit.edu}} - - [] - -* Committer public key files - - You should also add Your Public Keys to {{{https://people.apache.org/keys/committer}ASF Committer public key files}} - - Please follow instructions at: {{https://people.apache.org/keys}} - -* Generate a new key - - Please follow ASF infrastructure instruction: - - * {{{https://infra.apache.org/openpgp.html#key-gen-generate-key}Generate a new key}} - - * {{{https://infra.apache.org/openpgp.html#generate-key}How to generate a strong key}} - - [] diff --git a/content/apt/developers/retirement-plan-plugins.apt b/content/apt/developers/retirement-plan-plugins.apt deleted file mode 100644 index fc6b008544..0000000000 --- a/content/apt/developers/retirement-plan-plugins.apt +++ /dev/null @@ -1,174 +0,0 @@ - ------ - Retirement Plan for Plugins - ------ - Dennis Lundberg - ------ - 2013-07-26 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Retirement Plan for Plugins - -* Decide to retire - - Propose a vote on the dev-list to retire a plugin. The vote should be - open for the standard 72 hours to allow people to voice their opinions. Send a - cc to the users-list. Standard Apache voting rules apply. Only PMC votes are - binding. - - The vote must contain one or more options on how to retire the plugin. There - are multiple scenarios available. Here are a couple that have been suggested: - - [[A]] Move to our retired area in svn - - [[A]] Move to another Apache project - - [[A]] Move to www.mojohaus.org, apache-extras.org or another forge - - [] - - Here's a template for scenario A that can be used for the vote email: - ------- -To: "Maven Developers List" -Cc: "Maven Users List" -Subject: [VOTE] Retire Maven Foo Plugin - -Hi, - -A paragraph giving the reasons why the plugin should be retired. Make a note of -how long it has been since the latest release. - -I therefore propose that we retire maven-foo-plugin. - -If this vote is successful I will make one final release of the plugin, making -it clear on the plugin site that it has been retired. After that the source code -will be moved into the "retired" area in Subversion. - -The process for retiring a plugin is described here: -https://maven.apache.org/developers/retirement-plan-plugins.html - -The vote is open for 72 hours. - -[ ] +1 Yes, it's about time -[ ] -1 No, because... ------- - - If the vote is successful, post the result to the dev list and cc the PMC and - users list. For instance: - ------- -To: "Maven Developers List" -Cc: "Maven Users List" -CC: "Maven Project Management Committee List" -Subject: [RESULT] [VOTE] Retire Maven Foo Plugin - -Hi, - -The vote has passed with the following result: - -+1 (binding): <> -+1 (non binding): <> - -I will continue with the steps required to retire this plugin. ------- - - If the vote passes, make one final release of the plugin (with its own standard 72h vote on source release) before it is - retired. This allows us to make a clean break. The person who wants to retire - a plugin is the one who does the final release. Below you will find the extra - steps that you need to follow when retiring a plugin, in addition to - {{{./release/maven-project-release-procedure.html}our standard release process}}. - -* Make the final release - - [[1]] Create an issue in JIRA with the issue type "Task" and the summary - "Retire this plugin", and schedule it for the final release. If the plugin - includes a JIRA report in the generated site, you will need to close this - issue before you make the release. - - [[1]] Add the description - "This is the final version of this plugin. It has been retired." - to the final version in JIRA. - - [[1]] Add a prominent notice on the front page of the plugin's site, - informing that the plugin is retired. Suggested text: - ------- -Note: This plugin is retired. It is no longer maintained. ------- - - If the plugin is moved elsewhere, that should also be added to the plugin's - site. Suggested text: - ------- -Note: This plugin has retired from the Apache Maven project, -but has moved to the project. ------- - - [[1]] Add " (RETIRED)" at the end of <<<\>>>/<<<\>>> in the - plugin's <<>>. This will show up on every page of the generated site. - - [[1]] Go ahead with {{{./release/maven-project-release-procedure.html}the standard release process}}, - making sure that you follow the exceptions mentioned above regarding the site deployment. - - [[1]] When updating the plugins page, move Maven Foo Plugin to under the - "Retired" heading. Remove the SVN and JIRA links and add - the date of retirement. - - [[1]] When updating the version in JIRA, do not add Y.Z+1 and make sure you - remove any future versions. - -* Clean up after the release - - [[1]] Remove the <<<.Jenkinsfile>>> from all branches. This will remove the project from https://builds.apache.org/job/maven-box/ - - [[1]] Remove the <<<.github>>> directory from default branch. This will remove GitHub Actions - - [[1]] Ask INFRA for archive git repos (gitbox + github) - - [[1]] Republish documentation, postfix project name with (RETIRED) - - [[1]] When relevant update summary pages for {{{https://maven.apache.org/plugins/index.html}plugins}} or {{{https://maven.apache.org/shared/index.html}shared components}} - - [[1]] Add " (RETIRED)" at the end of the project name in JIRA. - - [[1]] Put the JIRA project in read-only mode in case of standalone project (own Jira key): apply Maven Retired Project Permissions Scheme. - (Requires JIRA admin karma: e.g. ask Brian Fox) - - [[1]] Comment the {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/dist-tool.conf.html}dist-tool configuration}} entry. - - [[1]] Remove from <<>> - - [[A]] {{https://maven.apache.org/scm.html}} - - [[A]] {{https://github.com/apache/maven-sources}} - - [[1]] Remove distribution from current {{{https://dist.apache.org/repos/dist/release/maven/}dist area}} - (history remains available in {{{https://archive.apache.org/dist/maven/}archive}}). - - [[1]] Update board report - - [[1]] Announce the fact that the plugin has been retired/moved on the - announce@m.a.o and users@m.a.o mailing lists. Explain to people what they - should do if they would like to continue development of the plugin. - -~~ Insert template for retirement email here diff --git a/content/apt/developers/website/deploy-component-reference-documentation.apt b/content/apt/developers/website/deploy-component-reference-documentation.apt deleted file mode 100644 index 58d15fdaf1..0000000000 --- a/content/apt/developers/website/deploy-component-reference-documentation.apt +++ /dev/null @@ -1,165 +0,0 @@ - ------ - Deploy Maven Component Reference Documentation - ------ - Barrie Treloar - Hervé Boutemy - ------ - 2015-03-30 - ------ - -~~ 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 - -Introduction - - This document gives step-by-step instructions for deploying - Maven components reference documentation inside the Maven {{{/}https://maven.apache.org/}} website. - - See {{{./index.html}Maven website introduction}} for instructions on the whole website publication (main site content + components). - - -Overview - - Since December 2012, the overall website uses svnpubsub mechanism: - -[component-reference-documentation.png] Components reference documentation mechanisms overview - - -How components reference documentation publication works - - Components don't use CMS: components reference documentation are versioned and generated from full sources, with both handwritten content (like Maven main site) - and content generated from sources (javadoc, unit-test results, integration test results...). - - -* Staging component reference documentation - - Reference documentation of a component is staged in <<>>, where <<>> is the - component name and <<>> can be: - - * the component type, like <<>>, <<>>, <<>>, ... (see - {{/shared-archives/}}, {{/plugins-archives/}}, {{/pom-archives/}}, {{/skins-archives/}}) - - * the component name for standalone components, like <<>>, <<>>, <<>>, <<>>, ... - (see {{/archetype-archives/}}, {{/archetypes-archives/}}, {{/plugin-tools-archives/}}, {{/scm-archives/}}, {{/surefire-archives/}}, {{/wagon-archives/}}) - - [] - - To publish component reference documentation: - - [[0]] prerequisite: eventually build the component if it has not been done previously, or some reports may miss build or integration information: - - Notice: In cases where you have prepared a release you can simple change into <<>> directory and continue with 2. - ------------- -mvn -Prun-its install ------------- - - [[1]] build the reference documentation: - ------------- -mvn -Preporting site site:stage ------------- - - Notice: <<>> is really necessary only for multi-modules components, but added unconditionally in these instructions - to keep them as straightforward as possible. - - [[2]] stage the reference documentation to website production svn area, using - {{{/plugins/maven-scm-publish-plugin}maven-scm-publish-plugin}}: (TODO: explanations on configuration in pom to yyy-LATEST) - ------------- -mvn scm-publish:publish-scm ------------- - - svnpubsub mechanism transfers svn production content to live production site - - [] - - [] - - <>: content is in fact published to {{/components/}} directory, - and symbolic links declared in <<>> in main site source are used by Ant to - create a reference from <<>> (= what we want to be user-visible) to <<>> (what what is - checked out). - -* Publishing versioned component reference documentation - - When doing a release, <<>> content staged in previous section needs: - - [[1]] to be archived to versioned directory before a newer revision is published into -LATEST, - - [[2]] to replace the actual component reference documentation. - - [] - - This is done with operations on website production svn area: you can use - {{{./component-reference-documentation-helper.html}Component Reference Documentation Helper}} to - easily prepare svnmucc command line. - - - If you prefer to do everything by hand from command templates, you can do either with <<>> command: - - * Unix: - ------------- -SVNPUBSUB=https://svn.apache.org/repos/asf/maven/website/components - -svn cp $SVNPUBSUB/xxx-archives/yyy-LATEST $SVNPUBSUB/xxx-archives/yyy-$version -m "Archive versioned site." - -svn rm $SVNPUBSUB/xxx/yyy -m "Remove old site." -svn cp $SVNPUBSUB/xxx-archives/yyy-$version $SVNPUBSUB/xxx/yyy -m "Publish new site." ------------- - - * Windows: - ------------- -set SVNPUBSUB=https://svn.apache.org/repos/asf/maven/website/components - -svn cp %SVNPUBSUB%/xxx-archives/yyy-LATEST %SVNPUBSUB%/xxx-archives/yyy-$version -m "Archive versioned site." - -svn rm %SVNPUBSUB%/xxx/yyy -m "Remove old site." -svn cp %SVNPUBSUB%/xxx-archives/yyy-$version %SVNPUBSUB%/xxx/yyy -m "Publish new site." ------------- - - [] - - or with {{{http://svnbook.red-bean.com/en/1.8/svn.ref.svnmucc.re.html}<<>> command}}: - ------------- -svnmucc -m "Publish yyy $version documentation" \ - -U https://svn.apache.org/repos/asf/maven/website/components \ - cp HEAD xxx-archives/yyy-LATEST xxx-archives/yyy-$version \ - rm xxx/yyy \ - cp HEAD xxx-archives/yyy-LATEST xxx/yyy ------------- - -* Updating index page in the Maven site - - Some component types have an index page refering to each components of the same type. This is the case for - plugins (see {{{/plugins/}index}}), shared (see {{{/shared/}index}}), poms (see {{{/pom/}index}}) and - skins (see {{{/skins/}index}}). - - Update the version number and release date for the component in the <<>> page. - - See {{{../website/deploy-maven-website.html}Deploy Maven website}} for more in-depth instructions on main - site content editing. - - <>: if you forget about updating the index page, dist-tool has a - {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/}report run daily}} - that will gently send a failure notification on notifications@maven.a.o when "Check Errors" report is not empty. diff --git a/content/apt/developers/website/deploy-maven-website.apt b/content/apt/developers/website/deploy-maven-website.apt deleted file mode 100644 index 179e5365b4..0000000000 --- a/content/apt/developers/website/deploy-maven-website.apt +++ /dev/null @@ -1,117 +0,0 @@ - ------ - Deploy Maven Main Website - ------ - Barrie Treloar - Hervé Boutemy - ------ - 2015-03-30 - ------ - -~~ 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 - -Introduction - - This document gives step-by-step instructions for deploying the main Maven {{{/}https://maven.apache.org}} website. - - <> this documentation is obsolete: with the migration of site source to Git, Apache CMS is not used any more. - It is replaced by Git edit (eventually through GitHub with the "edit" link accessible from breadcrumb) followed - by Jenkins job to build and commit to svnpubsub. - - See {{{./index.html}Maven website introduction}} for instructions on the whole website publication. - - -Overview - - Since December 2012, the overall website uses svnpubsub mechanism and the main website uses Apache CMS: - -[main-website.png] Main website mechanisms overview - - -How main website publication works - - Maven main website ({{https://maven.apache.org}}) is generated with {{{/plugins/maven-site-plugin}maven-site-plugin}} from a source tree - stored in svn: {{https://svn.apache.org/repos/asf/maven/site/trunk}}. - - -* Edit source content - - You can edit source content in 2 ways: - - [[1]] use {{{https://cms.apache.org/maven/}the CMS UI}} through your web browser: - - * Go to {{https://cms.apache.org/maven/}}. - - * Click link "Get Maven Working Copy". - - * Navigate to the content you want to modify. - - * Once you have modified the content, commit with the button "Submit". - - [] - - [[2]] checkout the source content locally, modify it with your favorite text editor, eventually test the result (<<>>), then check-in source modifications. - - [] - - After source tree is modified in svn, {{{http://ci.apache.org/builders/maven-site-staging}a Buildbot job}} is triggered: - - [[1]] it builds the HTML site using {{{/plugins/maven-site-plugin}maven-site-plugin}}: <<>>, - - [[2]] it publishes generated HTML content to {{{https://svn.apache.org/repos/infra/websites/staging/maven/trunk/content/}CMS staging svn area}}, - - [[3]] svnpubsub mecanism transfers svn CMS staging content to live CMS staging site: {{http://maven.staging.apache.org}}, - - [] - - -* Publish site content - - If everything is good, <> using {{{https://cms.apache.org/maven/publish}CMS publish}} action. - - Under the hood: - - [[1]] CMS copies CMS staging svn area content to {{{https://svn.apache.org/repos/infra/websites/production/maven/content/}website production svn area}}, - - [[2]] svnpubsub mecanism transfers svn production content to live production site: {{http://maven.apache.org}}. - - [] - - -How Doxia website publication works - - Doxia uses the exact same mecanisms: - - * you can edit {{{https://svn.apache.org/repos/asf/maven/doxia/site/trunk}svn source tree}} either locally or - through {{{https://cms.apache.org/maven-doxia/}CMS UI}}, - - * {{{http://ci.apache.org/builders/maven-doxia-site-staging}a Buildbot job}} builds the site and updates - {{{https://svn.apache.org/repos/infra/websites/staging/maven-doxia/trunk/content/}website staging svn area}}, - - * svnpubsub published to {{{http://maven-doxia.staging.apache.org}live staging site}}, - - * if everything is good, <> using {{{https://cms.apache.org/maven-doxia/publish}CMS publish}} action, - - * CMS copies CMS staging svn area content to {{{https://svn.apache.org/repos/infra/websites/production/maven-doxia/content/}website production svn area}}, - - * svnpubsub mecanism transfers svn production content to live production site: {{http://maven.apache.org/doxia}}, - with its {{{/doxia/extpaths.txt}<<>>}} - - [] diff --git a/content/apt/developers/website/index.apt b/content/apt/developers/website/index.apt deleted file mode 100644 index bd14c2864c..0000000000 --- a/content/apt/developers/website/index.apt +++ /dev/null @@ -1,79 +0,0 @@ - ------ - Deploy Maven Website - ------ - Barrie Treloar - Hervé Boutemy - ------ - 2013-09-23 - ------ - -~~ 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 - -Introduction - - The Maven {{{https://maven.apache.org}https://maven.apache.org}} website is composed from: - - * a main content, - - * multiple components reference documentation, published for each component release. - - [] - - And {{{https://maven.apache.org/doxia/}Doxia}} website has the same dual structure. - - These contents are stored in svn, and svnpubsub/svnwcsub maintains a working copy on the webservers in <<>> - (see {{{https://github.com/apache/infrastructure-puppet/blob/deployment/modules/svnwcsub/files/svnwcsub.conf#L123}<<>> configured in infra Puppet}}): - - * <<>> comes from {{{https://svn.apache.org/viewvc/maven/website/content/}https://svn.apache.org/repos/asf/maven/website/content/}} - - * {{{https://maven.apache.org/components}<<>>}} comes from {{https://svn.apache.org/repos/asf/maven/website/components/}} - - * <<>> comes from {{{https://svn.apache.org/viewvc/maven/doxia/website/content/}https://svn.apache.org/repos/asf/maven/doxia/website/content/}} - - * {{{https://maven.apache.org/doxia/components}<<>>}} comes from {{https://svn.apache.org/repos/asf/maven/doxia/website/components/}} - - [] - - and the link between main content and components reference documentation (for example from <<>> to internal <<>>) - is done with symbolic links. These links are configured in <<>> files in <<>> and subdirectories, - for example {{{https://github.com/apache/maven-site/blob/master/content/resources/plugins/components.links}plugins/components.links}}. - -How website publication works - - Instructions on how to publish website content are split in separate documents: - - * on every main content source commit ({{{https://github.com/apache/maven-site}maven-site.git}} - and {{{https://github.com/apache/maven-doxia-site}maven-doxia-site.git}}), - main content rebuild and publish is triggered through Jenkins jobs ( - {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-site/}maven-site job}} - and {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-doxia-site/}doxia-site job}}), - which basically run <<>> (it can be run locally if CI is off...), - - * on every Maven component release, release manager follows "{{{./deploy-component-reference-documentation.html}deploying Maven components reference documentation}}", - eventually using {{{./component-reference-documentation-helper.html}Component Reference Documentation Helper}} to - easily prepare <<>> command line. - - [] - -Analytics - - As part of Privacy enhancements, the whole Maven site is moving to {{{https://privacy.apache.org/matomo/}Apache's Analytics infrastructure}}: - see {{{https://analytics.apache.org/index.php?module=CoreHome&action=index&date=yesterday&period=day&idSite=3}Maven statistics}}. diff --git a/content/apt/developers/website/website-overview.apt b/content/apt/developers/website/website-overview.apt deleted file mode 100644 index 63e1196807..0000000000 --- a/content/apt/developers/website/website-overview.apt +++ /dev/null @@ -1,43 +0,0 @@ - ------ - Deploy Maven Website - ------ - Barrie Treloar - Hervé Boutemy - ------ - 2013-09-23 - ------ - -~~ 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 - -Introduction - - The Maven {{{/}https://maven.apache.org}} website is composed from: - - * a main content - - * multiple components reference documentation - - [] - -[website-overview.png] Website mechanisms overview - - - See {{{./index.html}Maven website introduction}} for instructions on website publication. diff --git a/content/apt/developers/welcome-to-new-committers.apt b/content/apt/developers/welcome-to-new-committers.apt deleted file mode 100644 index ad1400d48e..0000000000 --- a/content/apt/developers/welcome-to-new-committers.apt +++ /dev/null @@ -1,70 +0,0 @@ - ------ - Guide for new Maven committers - ------ - The Maven Team - ------ - 2006-04-03 - ------ - -~~ 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 - -Guide for new Maven committers - - First of all congratulations, thank you, and welcome to the fold! If you are reading this - you've recently been voted in as committer on an Apache Maven project and there are a few things - that need to be sorted out before you can participate fully. - - The first thing to get out of the way is sending in your contributor's license agreement (CLA). You - can't participate at Apache until we have received your signed CLA, so go to the {{{http://www.apache.org/licenses/#clas}Apache website}}, - print out the CLA, sign it, and send it in ASAP. - - Once you've dealt with your CLA, there are a some documents that pertain to Apache as a whole you should - read: - - * {{{http://www.apache.org/foundation/how-it-works.html}How the ASF works}} - - * {{{http://www.apache.org/dev/new-committers-guide.html}Guide for new committers}} - - * {{{http://www.apache.org/dev/committers.html}The committers FAQ}} - - * {{{http://www.apache.org/foundation/voting.html}How voting works}} - - [] - - Here are the documents that pertain to Maven specifically: - - * {{{/guides/development/guide-maven-development.html}Guide to Maven development}} - - * {{{/developers/committer-environment.html}Setup your committer environment}} - - [] - - And here are the specifics on setting up your Git access: - - * {{{http://www.apache.org/dev/version-control.html}Apache's Source Code Repository}} - - [] - - If you have any questions just ask! We're here to help, and looking forward to working with you! - - The Maven Team! - - diff --git a/content/apt/examples/index.apt b/content/apt/examples/index.apt deleted file mode 100644 index ef4d66ef54..0000000000 --- a/content/apt/examples/index.apt +++ /dev/null @@ -1,35 +0,0 @@ - --- - Summary of Maven Examples - --- - John Casey - --- - 2009-08-02 - ------ - -~~ 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 - -Examples - - * {{{./injecting-properties-via-settings.html}Injecting POM Properties via settings.xml}} - - * {{{./maven-3-lifecycle-extensions.html}Maven 3 lifecycle extensions}} - - [] diff --git a/content/apt/examples/injecting-properties-via-settings.apt b/content/apt/examples/injecting-properties-via-settings.apt deleted file mode 100644 index 09498baa20..0000000000 --- a/content/apt/examples/injecting-properties-via-settings.apt +++ /dev/null @@ -1,84 +0,0 @@ - --- - Example: Injecting POM Properties via Settings.xml - --- - John Casey - --- - 2006-04-20 - --- - -~~ 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 - -Example: Injecting POM Properties via Settings.xml - -* Impetus - - You have a plugin parameter that should contain a user-specific value. This - parameter has a common format (relative directory structure), but depends on - knowing the directory of the installed application or something. - -* Plugin Configuration - -+---+ - - [...] - - - - org.myproject.plugins - my-cool-maven-plugin - 1.0 - - ${application-home}/deploy - - - - -+---+ - -* <<>> - -+---+ - - [...] - - - inject-application-home - - /path/to/application - - - - - - inject-application-home - - -+---+ - -* Explanation - - When Maven loads the project's POM, it will pickup the activated profiles from - the <<>> section of the <<>> file, and inject the - properties declared within the profile. When the POM is interpolated, the - <<>> property will already have been injected, so will allow - the plugin's parameter value to be resolved. - - diff --git a/content/apt/guides/development/guide-building-maven.apt b/content/apt/guides/development/guide-building-maven.apt deleted file mode 100644 index ce8bc8f3ef..0000000000 --- a/content/apt/guides/development/guide-building-maven.apt +++ /dev/null @@ -1,92 +0,0 @@ - ------ - Guide to Building Maven - ------ - Brett Porter - Jason van Zyl - ------ - 2015-01-04 - ------ - -~~ 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 - -Building Maven - -* Why would I want to build Maven? - - Building Maven (or a plugin, or any component) yourself is for one of two reasons: - - * to try out a bleeding edge feature or bugfix (issues can be found in - {{{/issue-management.html} JIRA}}), - - * to fix a problem you are having and submit a patch to the developers team. - -* Checking out the sources - - All of the source code for Maven and its related libraries is in managed in the ASF source code - repositories: for details, see {{{/scm.html}https://maven.apache.org/scm.html}}. - -* Building Maven - -** Building a Maven Plugin or Component - - Building a Maven plugin or component is like any Maven build: - -------- -mvn install -------- - -*** Running Integration Tests - - Before submitting a patch, it is advised to run the integration tests, which are available in the <<>> profile: - -------- -mvn -Prun-its install -------- - -** Building Maven core - - Until Maven 3.3, Maven core build could be boostrapped with an Ant build. This bootstrap has been removed in Maven 3.5: - you need a pre-built Maven to build Maven from source. - - To do this, run from the source directory: - -------- -mvn install -------- - - The assemblies will be created in <<>>, and can be manually unzipped to the location where you'd like the resulting Maven installed. - - If you want to have the resulting Maven directly copied to a directory, you can use the <<>> property: - -------- -mvn -DdistributionTargetDir="$HOME/app/maven/apache-maven-SNAPSHOT" install -------- - -*** Running the full Maven core integration tests - - Before checking in a change or submitting a patch to Maven core, it is required to run the core integration tests. - Using your local build of Maven, run: - -------- -mvn test -Prun-its -------- - - Consult {{{/core-its/}Core ITs documentation}} for more options. diff --git a/content/apt/guides/development/guide-committer-school.apt b/content/apt/guides/development/guide-committer-school.apt deleted file mode 100644 index c00d3a9ac1..0000000000 --- a/content/apt/guides/development/guide-committer-school.apt +++ /dev/null @@ -1,96 +0,0 @@ - ------ - Do you want to become a Maven Committer? - ------ - Stephen Connolly - Robert Scholte - ------ - 2012-07-11 - 2017-07-21 - ------ - -~~ 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 - -~~ Original post: http://javaadventure.blogspot.nl/2012/07/do-you-want-to-become-maven-committer.html - -Do you want to become a Maven Committer? - - The Apache Software Foundation is a meritocracy. By this we mean that you gain status based on the merit of your work and actions. - In fact the status that you gain is a recognition of the merit of your work and actions. - - Maven is an Apache project, that means that we have to follow the Apache rules and way. - One of those rules is that we cannot hand out commit access to anyone who asks for it. - - To gain commit access you must establish your merit by submitting patches that get picked up by existing committers. - - After you have contributed enough patches to establish merit, the project management committee decides whether you can be trusted with commit access. - - - -What makes a good patch? - - A good patch is a patch that applies cleanly and includes tests that cover both the positive and negative case and has documentation where relevant. - - For example, if you were implementing a patch to fix {{{http://issues.apache.org/jira/browse/MNG-4612}MNG-4612}} you would first need to write a test case that is failing when trying to encrypt - ---- -{DESede}y+qq...== ---- - - and a second test case that is passing when trying to encrypt - ---- -password ---- - - This is in order to be sure that you have written an effective test case that can pass for good data. - Then you implement the fix and all the tests should pass. - You then take a Subversion compatible† diff of the source code and attach that to the issue in question. - - To understand how your patch gets evaluated, here is how I apply patches: - - [[1]] I look at the actual diff, if there is a whole lot of formatting changes irrelevant to the issue being fixed => <> - - [[1]] I look at the list of files in the diff, if there are no tests => <> - - [[1]] I look at the issue and if the issue requires documentation be updated and there is no documentation changes in the patch => <> - - [[1]] I take a clean checkout of the source that the patch applies to and try to apply the patch... if it does not apply clean => <> - - [[1]] I revert the src/main and run the tests. If the tests all pass, then there are no test cases to catch the bug => <> - - [[1]] I revert src and run the tests. If any tests fail, then there is something wrong with the existing code => <> - - [[1]] I apply the patch a second time and run the tests. If the tests all pass => <> - - [] - - So there you have it, my guide to writing good patches... now the next step is getting your patches noticed... - -How to get your patches noticed - - The simplest way to get your patches noticed is to submit them to the JIRA issue that they fix. - - Remember that the Maven project is run by volunteers in their spare time, so very often we may not notice your patch for a few days. - - If you are certain that your patch is a good patch, and a week has passed with no comments on JIRA, then you should send email to the {{{mailto:dev@maven.apache.org}dev@maven.apache.org}} mailing list to see if your patch can get noticed. - - <> you need to be fairly confident that your patch is a good patch, because if you keep on pestering the Maven developers looking to have non-good patches applied, your merit will become negative and people will be less inclined to help you get your patches applied... - also this is why you should send one and email about your patch on any specific JIRA issue. diff --git a/content/apt/guides/development/guide-documentation-style.apt b/content/apt/guides/development/guide-documentation-style.apt deleted file mode 100644 index 098175845c..0000000000 --- a/content/apt/guides/development/guide-documentation-style.apt +++ /dev/null @@ -1,136 +0,0 @@ - ------ - Guide To Maven Documentation Style - ------ - Dennis Lundberg - ------ - 2008-07-12 - ------ - -~~ 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 - -Guide To Maven Documentation Style - -* Where did the style came from? - - The documentation style guide was created to make our documentation more - consistent and also to apply best practices to the documentation as well. - The standard has just been started and will expand over time based on the - suggestions made on the Maven dev mailing list. It is a community consensus - of how we should write our documentation. - - Each rule in this guide should come with a motivation as to why it exists. - References to external sources are encouraged. - -* Date format - - How people format a date varies around the world, sometimes making it hard - for people to understand each other. The solution to this problem comes in - the form of the ISO-8601 standard. - - A date in our documentation must follow this standard: - - <> - - where <> is the year in the Gregorian calendar, <> is the month of - the year between 01 (January) and 12 (December), and <
> is the day of the - month between 01 and 31. - - <>: All documentation meta-data should respect this convention, for instance for this given APT document: - -------- - ------ - Guide To Maven Documentation Style - ------ - Dennis Lundberg - ------ - 2008-07-03 - ------ -------- - -** References - - * {{{http://www.w3.org/QA/Tips/iso-date}W3C Quality Web Tips}} - - * {{{http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780}ISO-8601}} - - * {{{http://en.wikipedia.org/wiki/ISO_8601}Wikipedia}} - - [] - -~~ NOTE: Add more rules here. Follow the heading style of the rule above. - -* POM Snippet - - A POM file must use 2 spaces for each indentation. Because POM snippets are - often used in documentation to show the user how to configure something, it is - important that these snippets aren't too wide. If they are too wide, - the page is difficult to read on a smaller screen. - - When you use a snippet of XML from the POM as an example in - documentation, make sure that the example is properly indented. - A user should be able to copy and paste the example into their own POM without - changing the indentation. - - Also, you should declare all parent POM elements to improve the comprehension. You could use ellipsis (i.e. ...) if - you don't want to specify elements. - -** Example - - The following is an example of how the distribution management of the Maven - site is configured. - -+-----+ - - ... - - - apache.website - scp://people.apache.org/www/maven.apache.org/ - - - ... - -+-----+ - - As you can see above the <<<\>>> element is indented - once (=2 spaces), the <<<\>>> element is indented twice (=4 spaces), and - the <<<\>>> is indented three times (=6 spaces). - -* Naming Documentation Files - - All file names should replace space by a hyphen (-), for instance for this given APT document: - -------- - guide-documentation-style.apt -------- - -* Updating Documentation Files - - A good practice is to update the date (with the correct date format) when you are updating documentation files. - -* Write Thinking - - Here are some pointers about English rules when typing material: - - * {{{https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style}Wikipedia:Manual of Style}}, specifically - {{{https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Punctuation}Punctuation Part}} - - [] diff --git a/content/apt/guides/development/guide-helping.apt b/content/apt/guides/development/guide-helping.apt deleted file mode 100644 index 6eb8f3ca1d..0000000000 --- a/content/apt/guides/development/guide-helping.apt +++ /dev/null @@ -1,107 +0,0 @@ - ------ - Guide to helping with Maven - ------ - Brett Porter - Jason van Zyl - ------ - 2008-07-03 - 2015-06-16 - ------ - -~~ 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 - -Guide to helping with Maven - - As with any open source project, there are several ways you can help: - - * Join the {{{../../mailing-lists.html}mailing lists}} and answer other user's questions. - - * Report bugs, feature requests and other issues in the {{{../../issue-management.html}issue management system}}. - - * {{{./guide-building-maven.html} Build Maven}} for yourself, in order to fix bugs. - - * {{{./guide-maven-development.html#Creating_and_submitting_a_patch}Submit patches}} to reported issues (both those you find, - or that others have filed)\ - To ease your first contribution, we have a {{{https://s.apache.org/for-the-grabs_maven}list of "up for grabs" issues}}, meaning that they should be easy to work on. - If you consider picking up larger chunks of work, please reach out on the {{{../../mailing-lists.html}dev@maven.apache.org list}} to discuss if the idea and solution strategy are still relevant. - - * {{{./guide-testing-releases.html} Test releases}} help test releases that are being voted on (see the {{{../../mailing-lists.html}dev@maven.apache.org list}} for release votes) - - * {{{./guide-testing-development-plugins.html} Test snapshot plugins}} help test the latest development versions of plugins and report issues - - * Help with the documentation by pointing out areas that are lacking or unclear, and if you can, submitting Pull Requests to correct it: - use the "edit" button in the breadcrumb, just after the page title. - You can also create appropriate issues {{{https://issues.apache.org/jira/browse/MNGSITE}by using the issue management system}}. - - [] - - Your participation in the community is much appreciated! - -Why Would I Want to Help? - - There are several reasons these are good things. - - * By answering other people's questions, you can learn more for yourself - - * By submitting your own fixes, they get incorporated faster - - * By reporting issues, you ensure that bugs don't get missed, or forgotten - - * You are giving back to a community that has given you software for free - - [] - -How do I Join the Project? - - Projects at Apache operate under a meritocracy, meaning those that the developers notice participating to a - high extent will be invited to join the project as a committer. - - This is as much based on personality and ability to work with other developers and the community as it is with - proven technical ability. Being unhelpful to other users, or obviously looking to become a committer for bragging - rights and nothing else is frowned upon, as is asking to be made a committer without having contributed - sufficiently to be invited. - -Developers Conventions - - There are a number of conventions used in the project, which contributors and developers alike should follow for - consistency's sake. - - * {{{../../developers/conventions/code.html}Maven Code Style And Convention}} - - * {{{../../developers/conventions/jira.html}Maven Jira Convention}} - - * {{{../../developers/conventions/git.html}Maven Git Convention}} - - * {{{../../developers/release/index.html}Releasing a Maven project}} - - * {{{https://cwiki.apache.org/confluence/display/MAVEN/Index}Apache Maven Wiki}} - - [] - -Resources for committers - - * {{{http://www.apache.org/dev/} Developer Resources}} - - * {{{http://www.apache.org/foundation/} About the Apache Software Foundation}} - - * {{{http://www.apache.org/dev/committers.html} Committer FAQ}} - - [] diff --git a/content/apt/guides/development/guide-maven-development.apt b/content/apt/guides/development/guide-maven-development.apt deleted file mode 100644 index 16bdb04a6c..0000000000 --- a/content/apt/guides/development/guide-maven-development.apt +++ /dev/null @@ -1,197 +0,0 @@ - ------ - Guide to Developing Maven - ------ - Emmanuel Venisse - Trygve Laugstol - Brett Porter - Maarten Mulders - ------ - 2019-06-04 - ------ - -~~ 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 - -Developing Maven - - This document describes how to get started developing Maven itself. There is a separate page describing how - to {{{./guide-building-maven.html}build Maven}}. - -* Finding some work to do - - First of all you need something to work on! Issues can be found in - {{{/issue-management.html}several JIRA projects}}. - - Another good place to look for work is the {{{https://s.apache.org/up-for-grabs_maven} Up for grabs}} list. - This list contains relatively simple issues that can be worked on without a lot of prerequisite knowledge. - - When you find a issue you would like to work on, add a comment in the issue log so the core developers and other - people looking for work know that someone is already working on it. - -* Where's the source? - - See {{{/scm.html}https://maven.apache.org/scm.html}} for information. - The Maven project uses the Apache GitBox Repositories, and all of them are dual-mirrored to - {{{https://github.com/apache/} GitHub}}. - -* Don't forget tests! -~~ TODO move details to guide-building-maven.apt, keep only principles here - - You will find many unit tests. If at all possible, create or modify a unit test to demonstrate - the problem, and then validate your fix. - - If you need to mock a class to write a test, use the Mockito framework. - Parts of the Maven codebase predate Mockito so you will encounter existing tests - that use EasyMock, PowerMock, and JMock. However, all newly written mocks - should use Mockito, even if this means a module or a single class - uses multiple mocking frameworks. If an existing test class has complicated - legacy mock setup, you can add new Mockito based tests in a new test class. - There is no requirement that all tests for a single model class must be in - the same test class. It is OK to have multiple test classes per model class. - - If the problem case can't be set up in the unit tests, add an integration test. Before submitting a patch, in any - case, you should run all of the integration tests. The tests require an empty local repository. - See {{{/core-its/core-it-suite/}Core IT Suite documentation}} for more details. - -* {Creating and submitting a patch} - - The most convenient way is to create a GitHub fork from the Git repository you are working with. - When you have either completed an issue or just want some feedback on the work you have done, create a pull request. - We have a couple of guidelines when submitting contributions: - - * Verify the status of the <<>> branch on {{{https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-dist-tool/job/master/site/dist-tool-master-jobs.html}Maven CI}}. - If it is not SUCCESS, then first try to figure out the problem. Don't start with your own issue yet! You can use <<>> to figure out the problematic commit and help - with that committer to solve the problem. - - * Create your branch from <<>>, not from a tag. Otherwise, your patch is outdated the moment you create it and might not be applicable - to the development head. - - * If this was a new piece of work without a JIRA issue, create a JIRA issue for it now. - - * Name the branch after the issue number; the branch name would start with <<<\->>>. - - * Push your branch with the commit(s) to your fork. - - * Create a {{{https://help.github.com/en/articles/about-pull-requests} pull request}} to submit your contribution. - Shortly after, someone will review the pull request and give you feedback on it. - - [] - - A short note: - - * Make sure that you follow our code style, see {{{Further_Links}Further Links}}. - - [] - -* Pull request acceptance criteria - - There are a number of criteria that a pull request will be judged on: - - * Whether it works and does what is intended. This one is probably obvious! - - * Whether it fits the spirit of the project. Some pull requests may be rejected as they take the project in a different - direction than the current development community has chosen. This is usually discussed on an issue well - before a pull request is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to - continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists. - - * Whether it contains tests. It is expected that any pull request relating to functionality will be accompanied by unit tests - and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis - for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. - As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing. - - * Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough - for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community - we are striving to increase the current coverage of documentation. - - [] - - Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. - And remember, your contributions are always welcome! - -* Related Projects - - Maven has a few dependencies on other projects: - - * <> - - Plexus is a full-fledged container supporting different kinds of component lifecycles. Its native lifecycle - is like any other modern IoC container, using field injection of both requirements and configuration. All - core Maven functionality are Plexus components. - - You can {{{https://codehaus-plexus.github.io/}read more about Plexus}}. - - * <> - - Modello is a simple tool for representing an object model and generating code and resources from the model. - Maven uses Modello to generate all Java objects, XML readers and writers, XML Schema, and HTML documentation. - - You can {{{https://codehaus-plexus.github.io/modello/}read more about Modello}}. - - * <> - - "Mojo" is really two things when it comes to Maven: it is both {{{/ref/current/maven-plugin-api/}Maven's plug-in API}} - and also {{{http://www.mojohaus.org}a separate Mojohaus project}} hosting a lot of plugins. - - {{{http://www.mojohaus.org}The MojoHaus Project}} is a plugin forge for non-core Maven plugins. - There is also a lower bar for becoming a part of the project. - - [] - -* Sub Projects - - ** <> - - Surefire is a testing framework. It can run regular JUnit tests so you won't have to change anything in your code to - use it. It supports scripting tests in BeanShell and Jython and has special "batteries" for writing acceptance and - functional tests for the web and for testing XML-RPC code. - - You can {{{/surefire/}read more about Surefire}}. - - ** <> - - Doxia is Maven's documentation engine. It has a sink and parser API that can be used to plug in support for input - and output documents. - - You can read more about {{{/doxia/}Doxia}} and the currently supported - {{{/doxia/references/index.html}document formats}}. - - - ** <> - - Maven SCM (Source Control Management) is a reusable API which is independent of Maven itself. It is used by the - SCM related Maven Plugins. The core part of Maven doesn't depend on Maven SCM. - - You can {{{/scm/}read more about Scm}}. - - ** <> - - Maven Wagon is a standalone API that dealt with transporting files and directories in Maven 2.x. Maven Core today - uses the Resolver Transport API, that among other implementations, contains a wrapper for Wagon as well. - Also, the site plug-in uses it to publish the site. - - You can {{{/wagon/}read more about Wagon}}. - -* {Further Links} - - * {{{../../developers/conventions/code.html}Maven Code Style And Code Convention}} - - * {{{../../developers/conventions/jira.html}Maven JIRA Convention}} - - [] diff --git a/content/apt/guides/development/guide-testing-development-plugins.apt b/content/apt/guides/development/guide-testing-development-plugins.apt deleted file mode 100644 index 22e87db72c..0000000000 --- a/content/apt/guides/development/guide-testing-development-plugins.apt +++ /dev/null @@ -1,141 +0,0 @@ - ------ - Guide to Testing Development Versions of Plugins - ------ - Brett Porter - ------ - 2009-08-02 - ------ - -~~ 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 - -Guide to Testing Development Versions of Plugins - -* Why would I want to do this? - - If a bug you are encountering has been reported as fixed but not yet released, you can confirm that it has been fixed - for you. Or perhaps you just like to live on the bleeding edge. - - You are highly encouraged to join the development list for the project and provide your feedback, or help promote release - of the plugin in question. - - This is <> recommended as an everyday or in production practice! Snapshots are for testing purposes only and - are not official releases. For more information, see {{{http://www.apache.org/dev/release.html#what} the Releases FAQ}}. - -* How do I do this? - - Development versions of Maven plugins are periodically published to the repository: {{https://repository.apache.org/snapshots/}}. - - Currently, this is not done automatically by our continuous integration setup. This is coming soon. - - Other sites may publish there own - for example, the MojoHaus project hosts theirs at {{https://oss.sonatype.org/content/repositories/snapshots/}} - - The first step is to include this in your project: - -+------- - - ... - - - apache.snapshots - https://repository.apache.org/snapshots/ - - - ... - -+------- - - After this is included, there are three ways to use the updated versions: - - * Set the appropriate version in the plugin, eg <<<2.0.1-SNAPSHOT>>> - - * If you have not specified a version, use the <<<-U>>> switch to update plugins for the given Maven run - - * You can have Maven automatically check for updates on a given interval, for example: - -+------- - - ... - - - apache.snapshots - https://repository.apache.org/snapshots/ - - - ... - -+------- - - These last two techniques mean that plugin will be updated to the latest snapshot version. - - The development version will stop being used if the <<<\>>> element is removed from your POM - and the version is set back to the release version. If you are using the command line or an unspecified version, - you will also need to remove the version from the local repository. - -* Using Settings without Modifying the Project - - If you are using the goals from the command line on a number of projects, you should include this in your - <<>> file instead. - - You need to modify your <<<$\{user.home\}/.m2/settings.xml>>> file to include two new profiles - and then when you need access to the plugin snapshots use <<<-Papache>>>. - The profile only needs to be enabled once so that the plugins can be downloaded into you local repository. Once - in your local repository Maven can successfully resolve the dependencies and - the profile no longer needs to be activated. - -+--- - - ... - - - apache - - - apache.snapshots - Maven Plugin Snapshots - https://repository.apache.org/snapshots/ - - false - - - true - - - - - - ... - -+--- - - When invoking Maven for Apache profile, do it like this: - ----- -mvn -Papache ----- - -* Using a Repository Manager - - In addition to the above you may want to use a repository manager so that you can retain the builds you have been using. - For information on this technique, see the {{{./guide-testing-releases.html} Guide to Testing Staged Releases}}. - -* How do I make changes to the source and test development versions of the plugins? - - For information on this, see the {{{./guide-maven-development.html}Guide to Maven Development}}. diff --git a/content/apt/guides/development/guide-testing-releases.apt b/content/apt/guides/development/guide-testing-releases.apt deleted file mode 100644 index c1a980c096..0000000000 --- a/content/apt/guides/development/guide-testing-releases.apt +++ /dev/null @@ -1,162 +0,0 @@ - ------ - Guide to Testing Staged Releases - ------ - Maven Team - ------ - 2007-12-21 - ------ - -~~ 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 - -Guide to Testing Staged Releases - - As part of the release process, the artifacts are staged in a temporary repository - for testing and evaluation before voting. Such repositories are not available by - default, so to use them your project must be configured appropriately. - - The steps are as follows: - - * add the repository or plugin repository to your POM or settings (see below) - - * ensure you are using the version being released of the artifacts in your project, - e.g. by setting the <<<\>>> in the <<<\>>> tag. - - * test the release - - * remove the repository from your POM if it was specified there - - * remove the artifacts from your local repository when you have completed testing - - The repository configuration for testing a plugin will typically look something like this (it will be provided in the vote email): - -+---- - ... - - - staged-releases - https://repository.apache.org/content/groups/staging/ - - - ... -+---- - - The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the - release is made again. This is why clearing the local repository is necessary, but if you are using a repository manager this is also - important to clear. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already. - -Checking Reproducible Builds - - Checking binary output, ideally to control that the build is reproducible, can be done by running <<>> (NOT <<>>) followed by <<>> against the staged content: - ------ -mvn -Papache-release -Dgpg.skip clean verify \ - artifact:compare -Dreference.repo=https://repository.apache.org/content/groups/staging/ ------ - -* Setting up Archiva to Test Staged Releases - - These steps will be similar for any repository manager - please refer to their individual documentation for instructions on how to - configure remote proxies. - - For Archiva, the first step is to create a new managed repository for the staged releases. This will ensure they remain isolated from your - environment. On the repositories tab, add a new managed repository with the settings: - - * Identifier = <<>> - - * Name = Staged Releases - - * Directory = <<>> - - * Uncheck 'Scannable' - - Next add a remote repository with settings similar to the following: - - * Identifier = <<>> - - * Name = dfabulich Staged Releases - - * URL = <<>> - - Finally, add a proxy connector to connect the two repositories: - - * Managed repository = <<>> - - * Remote repository = <<>> - - * Release policy = <<>> - - * Snapshot policy = <<>> - - * White list = <<>> - - You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of - <<>>. - - The advantage of this approach is that you can usually remove your entire local repository afterwards and after removing the staged repository - from your POM the artifacts will no longer be used. There is no need to remove the repository or artifacts from Archiva itself - unless a - staged release is updated for further testing. - - It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote - repository for a different staging repository. - - If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional - mirror to correspond to the additional repository in the POM, such as: - -+---- - ... - - staged-releases-mirror - http://localhost:8080/archiva/repository/staged-releases/ - staged-releases - - ... -+---- - -* Using a Settings Profile - - If you regularly test staged releases and want to have a more convenient way to add the repository to a build without - modifying your POM, you may add a profile to your <<<~/.m2/settings.xml>>>: - -+---- - ... - - - staged-releases - - - staged-releases - https://repository.apache.org/content/groups/staging/ - - - - ... -+---- - - With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then - run the build with the following command: - ------ -mvn verify -Pstaged-releases ------ - - Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build - environment. - diff --git a/content/apt/guides/getting-started/index.apt b/content/apt/guides/getting-started/index.apt deleted file mode 100644 index 9c5d1dd999..0000000000 --- a/content/apt/guides/getting-started/index.apt +++ /dev/null @@ -1,1257 +0,0 @@ - ---- - Maven Getting Started Guide - ----- - Jason van Zyl - Vincent Siveton - ----- - 2006-11-01 - ----- - -Maven Getting Started Guide - - This guide is intended as a reference for those working with Maven for the first time, but is also intended to serve as - a cookbook with self-contained references and solutions for common use cases. For first time users, it is recommended - that you step through the material in a sequential fashion. For users more familiar with Maven, this guide endeavours - to provide a quick solution for the need at hand. It is assumed at this point that you have downloaded Maven and - installed Maven on your local machine. If you have not done so please refer to the - {{{../../download.html}Download and Installation}} instructions. - - Ok, so you now have Maven installed and we're ready to go. Before we jump into our examples we'll very briefly go over - what Maven is and how it can help you with your daily work and collaborative efforts with team members. Maven will, of - course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members - to focus on what the stakeholders of a project require. You can leave the build infrastructure to Maven! - -Sections - - * {{{./index.html#what-is-maven}What is Maven?}} - - * {{{./index.html#how-can-maven-benefit-my-development-process}How can Maven benefit my development process?}} - - * {{{./index.html#how-do-i-setup-maven}How do I setup Maven?}} - - * {{{./index.html#how-do-i-make-my-first-maven-project}How do I make my first Maven project?}} - - * {{{./index.html#how-do-i-compile-my-application-sources}How do I compile my application sources?}} - - * {{{./index.html#how-do-i-compile-my-test-sources-and-run-my-unit-tests}How do I compile my test sources and run my unit tests?}} - - * {{{./index.html#how-do-i-create-a-jar-and-install-it-in-my-local-repository}How do I create a JAR and install it in my local repository?}} - - * {{{./index.html#what-is-a-snapshot-version}What is a SNAPSHOT version?}} - - * {{{./index.html#how-do-i-use-plugins}How do I use plugins?}} - - * {{{./index.html#how-do-i-add-resources-to-my-jar}How do I add resources to my JAR?}} - - * {{{./index.html#how-do-i-filter-resource-files}How do I filter resource files?}} - - * {{{./index.html#how-do-i-use-external-dependencies}How do I use external dependencies?}} - - * {{{./index.html#how-do-i-deploy-my-jar-in-my-remote-repository}How do I deploy my jar in my remote repository?}} - - * {{{./index.html#how-do-i-create-documentation}How do I create documentation?}} - - * {{{./index.html#how-do-i-build-other-types-of-projects}How do I build other types of projects?}} - - * {{{./index.html#how-do-i-build-more-than-one-project-at-once}How do I build more than one project at once?}} - - [] - -* {What is Maven?} - - At first glance Maven can appear to be many things, but in a nutshell Maven is an attempt . Maven is essentially a project management and comprehension tool and as such provides a way to - help with managing: - - - * Builds - - * Documentation - - * Reporting - - * Dependencies - - * SCMs - - * Releases - - * Distribution - - [] - - If you want more background information on Maven you can check out {{{../../background/philosophy-of-maven.html}The Philosophy of Maven}} and - {{{../../background/history-of-maven.html}The History of Maven}}. Now let's move on to how you, the user, can benefit from - using Maven. - -* {How can Maven benefit my development process?} - - Maven can provide benefits for your build process by employing standard conventions and practices to accelerate your development - cycle while at the same time helping you achieve a higher rate of success. - - Now that we have covered a little bit of the history and purpose of Maven let's get into some real examples to - get you up and running with Maven! - -* {How do I setup Maven?} - - The defaults for Maven are often sufficient, but if you need to change the cache location or are behind a HTTP proxy, - you will need to create configuration. See the {{{../mini/guide-configuring-maven.html} Guide to Configuring Maven}} for - more information. - -* {How do I make my first Maven project?} - - We are going to jump headlong into creating your first Maven project! - To create our first Maven project we are going to use Maven's archetype mechanism. An archetype is defined as - . In Maven, an archetype is a template - of a project which is combined with some user input to produce a working Maven project that has been tailored to the - user's requirements. We are going to show you how the archetype mechanism works now, but if you would like to know more - about archetypes please refer to our {{{../introduction/introduction-to-archetypes.html}Introduction to Archetypes}}. - - On to creating your first project! In order to create the simplest of Maven projects, execute the following from - the command line: - ------ -mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false ------ - - Once you have executed this command, you will notice a few things have happened. First, you will notice that - a directory named <<>> has been created for the new project, and this directory contains a file named - <<>> that should look like this: - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - - my-app - - http://www.example.com - - - UTF-8 - 17 - - - - - - org.junit - junit-bom - 5.11.0 - pom - import - - - - - - - org.junit.jupiter - junit-jupiter-api - test - - - - org.junit.jupiter - junit-jupiter-params - test - - - - - - ... lots of helpful plugins - - - -+-----+ - - <<>> contains the Project Object Model (POM) for this project. The POM is the basic unit - of work in Maven. This is important to remember because Maven is inherently project-centric in that everything revolves - around the notion of a project. In short, the POM contains every important piece of information about your project and - is essentially one-stop-shopping for finding anything related to your project. Understanding the POM is important and - new users are encouraged to refer to the {{{../introduction/introduction-to-the-pom.html}Introduction to the POM}}. - - This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them - to familiarize you with the POM essentials: - - * <> This is the top-level element in all Maven <<>> files. - - * <> This element indicates what version of the object model this POM is using. The version of the - model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when - the Maven developers deem it necessary to change the model. - - * <> This element indicates the unique identifier of the organization or group that created the project. - The groupId is one of the key identifiers of a project and is typically based on the fully qualified - domain name of your organization. For example <<>> is the designated groupId for - all Maven plugins. - - * <> This element indicates the unique base name of the primary artifact being generated by this project. - The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use - the artifactId as part of their final name. A typical artifact produced by Maven would have the form - \-\.\ (for example, <<>>). - - * <> This element indicates the version of the artifact generated by the project. Maven goes a long way - to help you with version management and you will often see the <<>> designator in a version, which - indicates that a project is in a state of development. We will discuss the use of - {{{./index.html#what-is-a-snapshot-version}snapshots}} and how they work further on in this guide. - - * <> This element indicates the display name used for the project. This is often used in Maven's - generated documentation. - - * <> This element indicates where the project's site can be found. This is often used in Maven's - generated documentation. - - * <> This element contains value placeholders accessible anywhere within a POM. - - * <> This element's children list {{{/pom.html#dependencies}dependencies}}. The cornerstone of the POM. - - * <> This element handles things like declaring your project's directory structure and managing plugins. - - [] - - For a complete reference of what elements are available for use in the POM please refer to our {{{/ref/current/maven-model/maven.html}POM Reference}}. - Now let's get back to the project at hand. - - After the archetype generation of your first project you will also notice that the following directory structure - has been created: - ------ -my-app -|-- pom.xml -`-- src - |-- main - | `-- java - | `-- com - | `-- mycompany - | `-- app - | `-- App.java - `-- test - `-- java - `-- com - `-- mycompany - `-- app - `-- AppTest.java ------ - - As you can see, the project created from the archetype has a POM, a source tree for your application's sources and - a source tree for your test sources. This is the standard layout for Maven projects (the application sources - reside in <<<$\{project.basedir\}/src/main/java>>> and test sources reside in <<<$\{project.basedir\}/src/test/java>>>, where <<<$\{project.basedir\}>>> - represents the directory containing <<>>). - - If you were to create a Maven project by hand this is the directory structure that we recommend using. This is a - Maven convention and to learn more about it you can read our - {{{../introduction/introduction-to-the-standard-directory-layout.html}Introduction to the Standard Directory Layout}}. - - Now that we have a POM, some application sources, and some test sources you are probably asking... - -* {How do I compile my application sources?} - - Change to the directory where <<>> is created by archetype:generate and execute the following command to compile - your application sources: - -------- -mvn compile -------- - - Upon executing this command you should see output like the following: - ------ -[INFO] Scanning for projects... -[INFO] -[INFO] ----------------------< com.mycompany.app:my-app >---------------------- -[INFO] Building my-app 1.0-SNAPSHOT -[INFO] --------------------------------[ jar ]--------------------------------- -[INFO] -[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- -[INFO] Using 'UTF-8' encoding to copy filtered resources. -[INFO] skip non existing resourceDirectory /my-app/src/main/resources -[INFO] -[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- -[INFO] Changes detected - recompiling the module! -[INFO] Compiling 1 source file to /my-app/target/classes -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 0.899 s -[INFO] Finished at: 2020-07-12T11:31:54+01:00 -[INFO] ------------------------------------------------------------------------ ------ - - The first time you execute this (or any other) command, Maven will need to download all the plugins and related - dependencies it needs to fulfill the command. From a clean installation of Maven, this can take quite a while (in - the output above, it took almost 4 minutes). If you execute the command again, Maven will now have what it needs, - so it won't need to download anything new and will be able to execute the command much more quickly. - - As you can see from the output, the compiled classes were placed in <<<$\{project.basedir\}/target/classes>>>, which is - another standard convention employed by Maven. So, if you're a keen observer, you'll notice that by using the - standard conventions, the POM above is very small and you haven't had to tell Maven explicitly where any of - your sources are or where the output should go. By following the standard Maven conventions, you can get - a lot done with very little effort! Just as a casual comparison, let's take a look at what you might have had to do - in {{{http://ant.apache.org}Ant}} to accomplish the same {{{../../ant/build-a1.xml}thing}}. - - Now, this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same - size as the POM shown above. But we'll see how much more we can do with just that simple POM! - -* {How do I compile my test sources and run my unit tests?} - - Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile - and execute (because every programmer always writes and executes their unit tests *nudge nudge wink wink*). - - Execute the following command: - ------- -mvn test ------- - - Upon executing this command you should see output like the following: - ----- -[INFO] Scanning for projects... -[INFO] -[INFO] ----------------------< com.mycompany.app:my-app >---------------------- -[INFO] Building my-app 1.0-SNAPSHOT -[INFO] --------------------------------[ jar ]--------------------------------- -[INFO] -[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- -[INFO] Using 'UTF-8' encoding to copy filtered resources. -[INFO] skip non existing resourceDirectory /my-app/src/main/resources -[INFO] -[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- -[INFO] Nothing to compile - all classes are up to date -[INFO] -[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app --- -[INFO] Using 'UTF-8' encoding to copy filtered resources. -[INFO] skip non existing resourceDirectory /my-app/src/test/resources -[INFO] -[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app --- -[INFO] Changes detected - recompiling the module! -[INFO] Compiling 1 source file to /my-app/target/test-classes -[INFO] -[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app --- -[INFO] -[INFO] ------------------------------------------------------- -[INFO] T E S T S -[INFO] ------------------------------------------------------- -[INFO] Running com.mycompany.app.AppTest -[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest -[INFO] -[INFO] Results: -[INFO] -[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -[INFO] -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 1.881 s -[INFO] Finished at: 2020-07-12T12:00:33+01:00 -[INFO] ------------------------------------------------------------------------ ----- - - Some things to notice about the output: - - * Maven downloads more dependencies this time. These are the dependencies and plugins necessary for executing the tests - (it already has the dependencies it needs for compiling and won't download them again). - - * Before compiling and executing the tests Maven compiles the main code (all these classes are up to date because - we haven't changed anything since we compiled last). - - If you simply want to compile your test sources (but not execute the tests), you can execute the following: - ------- - mvn test-compile ------- - - Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move - on to the next logical step so you'll be asking ... - -* {How do I create a JAR and install it in my local repository?} - - Making a JAR file is straight forward enough and can be accomplished by executing the following command: - -~~ How to skip tests ... jvz - ------- -mvn package ------- - - You can now take a look in the <<<$\{project.basedir\}/target>>> directory and you will see the generated JAR file. - - Now you'll want to install the artifact you've generated (the JAR file) in your local repository - (<<<$\{user.home\}/.m2/repository>>> is the default location). For more information on repositories you can refer to our - {{{../introduction/introduction-to-repositories.html}Introduction to Repositories}} but let's move on to installing our artifact! - To do so execute the following command: - ------- -mvn install ------- - - Upon executing this command you should see the following output: - ----- -[INFO] Scanning for projects... -[INFO] -[INFO] ----------------------< com.mycompany.app:my-app >---------------------- -[INFO] Building my-app 1.0-SNAPSHOT -[INFO] --------------------------------[ jar ]--------------------------------- -[INFO] -[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- -... -[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- -[INFO] Nothing to compile - all classes are up to date -[INFO] -[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app --- -... -[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app --- -[INFO] Nothing to compile - all classes are up to date -[INFO] -[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app --- -[INFO] -[INFO] ------------------------------------------------------- -[INFO] T E S T S -[INFO] ------------------------------------------------------- -[INFO] Running com.mycompany.app.AppTest -[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest -[INFO] -[INFO] Results: -[INFO] -[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -[INFO] -[INFO] -[INFO] --- maven-jar-plugin:3.0.2:jar (default-jar) @ my-app --- -[INFO] Building jar: /my-app/target/my-app-1.0-SNAPSHOT.jar -[INFO] -[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ my-app --- -[INFO] Installing /my-app/target/my-app-1.0-SNAPSHOT.jar to /com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar -[INFO] Installing /my-app/pom.xml to /com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.pom -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 1.678 s -[INFO] Finished at: 2020-07-12T12:04:45+01:00 -[INFO] ------------------------------------------------------------------------ ----- - - Note that the surefire plugin (which executes the test) looks for tests contained in files with a particular naming convention. By default - the tests included are: - - * <<<\*\*/\*Test.java>>> - - * <<<\*\*/Test\*.java>>> - - * <<<\*\*/\*TestCase.java>>> - - [] - - And the default excludes are: - - * <<<\*\*/Abstract\*Test.java>>> - - * <<<\*\*/Abstract\*TestCase.java>>> - - [] - - You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project. - This is likely the vast majority of what projects will be doing with Maven and if you've noticed, everything you've been - able to do up to this point has been driven by an 18-line file, namely the project's model or POM. If you look at - a typical Ant {{{../../ant/build-a1.xml}build file}} that provides the same functionality that we've achieved thus - far you'll notice it's already twice the size of the POM and we're just getting started! There is far more - functionality available to you from Maven without requiring any additions to our POM as it currently stands. To - get any more functionality out of our example Ant build file you must keep making error-prone additions. - - So what else can you get for free? There are a great number of Maven plugins that work out of the box with - even a simple POM like we have above. We'll mention one here specifically as it is one of the highly - prized features of Maven: without any work on your part this POM has enough information to generate - a web site for your project! You will most likely want to customize your Maven site but if you're pressed for - time all you need to do to provide basic information about your project is execute the following command: - ------- -mvn site ------- - - There are plenty of other standalone goals that can be executed as well, for example: - ------- -mvn clean ------- - - This will remove the <<>> directory with all the build data before starting so that it is fresh. - -* {What is a SNAPSHOT version?} - - Notice the value of the <> tag in the <<>> file shown below has the suffix: <<<-SNAPSHOT>>>. - -+-----+ -... - my-app - ... - 1.0-SNAPSHOT - Maven Quick Start Archetype - ... -+-----+ - - The <<>> value refers to the 'latest' code along a development branch, and provides no guarantee the - code is stable or unchanging. Conversely, the code in a 'release' version (any version value without the suffix <<>>) - is unchanging. - - In other words, a SNAPSHOT version is the 'development' version before the final 'release' version. - The SNAPSHOT is "older" than its release. - - During the {{{../../plugins/maven-release-plugin/}release}} process, a version of <> changes to - <>. The release process also increments the development version to <>. - For example, version <<1.0-SNAPSHOT>> is released as version <<1.0>>, and the new development version is - version <<1.1-SNAPSHOT>>. - -* {How do I use plugins?} - - Whenever you want to customise the build for a Maven project, this is done by adding or reconfiguring plugins. - - For this example, we will configure the Java compiler to allow JDK 5.0 sources. This is as simple as - adding this to your POM: - -+----+ -... - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.3 - - 1.5 - 1.5 - - - - -... -+----+ - - You'll notice that all plugins in Maven look much like a dependency - and in some ways they are. - This plugin will be automatically downloaded and used - including a specific version if you request it - (the default is to use the latest available). - - The <<>> element applies the given parameters to every goal from the compiler plugin. - In the above case, the compiler plugin is already used as part of the build process and this just changes the - configuration. It is also possible to add new goals to the process, and configure specific goals. For information on - this, see the {{{../introduction/introduction-to-the-lifecycle.html} Introduction to the Build Lifecycle}}. - - To find out what configuration is available for a plugin, you can see the {{{../../plugins/} Plugins List}} and navigate - to the plugin and goal you are using. For general information about how to configure the available parameters of a - plugin, have a look at the {{{../mini/guide-configuring-plugins.html}Guide to Configuring Plugins}}. - -* {How do I add resources to my JAR?} - - Another common use case that can be satisfied which requires no changes to the POM that we have - above is packaging resources in the JAR file. For this common task, Maven again relies on the - {{{../introduction/introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}, which means by using - standard Maven conventions you can package resources within JARs simply by placing those resources in a standard - directory structure. - - You see below in our example we have added the directory <<<$\{project.basedir\}/src/main/resources>>> into which we place - any resources we wish to package in our JAR. The simple rule employed by Maven is this: any directories or files - placed within the <<<$\{project.basedir\}/src/main/resources>>> directory are packaged in your JAR with the exact same - structure starting at the base of the JAR. - ----- -my-app -|-- pom.xml -`-- src - |-- main - | |-- java - | | `-- com - | | `-- mycompany - | | `-- app - | | `-- App.java - | `-- resources - | `-- META-INF - | `-- application.properties - `-- test - `-- java - `-- com - `-- mycompany - `-- app - `-- AppTest.java ----- - - So you can see in our example that we have a <<>> directory with an <<>> file - within that directory. If you unpacked the JAR that Maven created for you and took a look at it you would - see the following: - ----- -|-- META-INF -| |-- MANIFEST.MF -| `-- application.properties -| `-- maven -| `-- com.mycompany.app -| `-- my-app -| |-- pom.properties -| `-- pom.xml -`-- com - `-- mycompany - `-- app - `-- App.class ----- - - As you can see, the contents of <<<$\{project.basedir\}/src/main/resources>>> can be found starting at the base of the - JAR and our <<>> file is there in the <<>> directory. You will also notice some other files there - like <<>> as well as a <<>> and <<>> file. These come standard with - generation of a JAR in Maven. You can create your own manifest if you choose, but Maven will generate one by - default if you don't. (You can also modify the entries in the default manifest. We will touch on this - later.) The <<>> and <<>> files are packaged up in the JAR so that each artifact - produced by Maven is self-describing and also allows you to utilize the metadata in your own application - if the need arises. One simple use might be to retrieve the version of your application. Operating on the POM - file would require you to use some Maven utilities but the properties can be utilized using the standard - Java API and look like the following: - ----- -#Generated by Maven -#Tue Oct 04 15:43:21 GMT-05:00 2005 -version=1.0-SNAPSHOT -groupId=com.mycompany.app -artifactId=my-app ----- - - To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR - except the directory you place resources in is <<<$\{project.basedir\}/src/test/resources>>>. At this point you would have a - project directory structure that would look like the following: - ------ -my-app -|-- pom.xml -`-- src - |-- main - | |-- java - | | `-- com - | | `-- mycompany - | | `-- app - | | `-- App.java - | `-- resources - | `-- META-INF - | |-- application.properties - `-- test - |-- java - | `-- com - | `-- mycompany - | `-- app - | `-- AppTest.java - `-- resources - `-- test.properties ------ - - In a unit test you could use a simple snippet of code like the following to access the resource required for - testing: - -+----+ -... - -// Retrieve resource -InputStream is = getClass().getResourceAsStream( "/test.properties" ); - -// Do something with the resource - -... -+----+ - -* {How do I filter resource files?} - - Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in - Maven, put a reference to the property that will contain the value into your resource file using the syntax <<<$\{\}>>>. - The property can be one of the values defined in your <<>>, a value defined in the user's <<>>, a property - defined in an external properties file, or a system property. - - To have Maven filter resources when copying, simply set <<>> to true for the resource directory in your <<>>: - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - - - - - src/main/resources - true - - - - -+----+ - - You'll notice that we had to add the <<>>, <<>>, and <<>> elements which weren't there before. - In addition, we had to explicitly state that the resources are located in the <<>> directory. All of this - information was provided as default values previously, but because the default value for <<>> is false, we had - to add this to our <<>> in order to override that default value and set <<>> to true. - - To reference a property defined in your <<>>, the property name uses the names of the XML elements that define the value, - with "pom" being allowed as an alias for the project (root) element. So <<<$\{project.name\}>>> refers to the name of the project, - <<<$\{project.version\}>>> refers to the version of the project, <<<$\{project.build.finalName\}>>> refers to the final name of the file created - when the built project is packaged, etc. Note that some elements of the POM have default values, so don't need to be explicitly - defined in your <<>> for the values to be available here. Similarly, values in the user's <<>> can be referenced - using property names beginning with "settings" (for example, <<<$\{settings.localRepository\}>>> refers to the path of the user's - local repository). - - To continue our example, let's add a couple of properties to the <<>> file (which we put in the - <<>> directory) whose values will be supplied when the resource is filtered: - ------- -# application.properties -application.name=${project.name} -application.version=${project.version} ------- - - With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are - copied and filtered): - ------- -mvn process-resources ------- - - and the <<>> file under <<>> (and will eventually go into the jar) looks like this: - ------- -# application.properties -application.name=Maven Quick Start Archetype -application.version=1.0-SNAPSHOT ------- - - To reference a property defined in an external file, all you need to do is add a reference to this external file in your <<>>. - First, let's create our external properties file and call it <<>>: - ------- -# filter.properties -my.filter.value=hello! ------- - - Next, we'll add a reference to this new file in the <<>>: - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - - - - src/main/filters/filter.properties - - - - src/main/resources - true - - - - -+----+ - - Then, if we add a reference to this property in the <<>> file: - ------- -# application.properties -application.name=${project.name} -application.version=${project.version} -message=${my.filter.value} ------- - - the next execution of the <<>> command will put our new property value into <<>>. - As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the <<>> - section of your <<>> and you'd get the same effect (notice I don't need the references to <<>> either): - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - - - - - src/main/resources - true - - - - - - hello - - -+----+ - - Filtering resources can also get values from system properties; either the system properties built into Java (like <<>> or - <<>>) or properties defined on the command line using the standard Java -D parameter. To continue the example, let's change - our <<>> file to look like this: - ------- -# application.properties -java.version=${java.version} -command.line.prop=${command.line.prop} ------- - - Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the - <<>> file will contain the values from the system properties. - ------- -mvn process-resources "-Dcommand.line.prop=hello again" ------- - - -* {How do I use external dependencies?} - - You've probably already noticed a <<>> element in the POM we've been using as an example. - You have, in fact, been using an external dependency all this time, but here we'll talk about how this - works in a bit more detail. For a more thorough introduction, please refer to our - {{{../introduction/introduction-to-dependency-mechanism.html}Introduction to Dependency Mechanism}}. - - The <<>> section of the <<>> lists all of the external dependencies that our project needs - in order to build (whether it needs that dependency at compile time, test time, run time, or whatever). Right - now, our project is depending on JUnit only (I took out all of the resource filtering stuff for clarity): - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - -+----+ - - For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope. The groupId, - artifactId, and version are the same as those given in the <<>> for the project that built that dependency. The scope - element indicates how your project uses that dependency, and can be values like <<>>, <<>>, and <<>>. - For more information on everything you can specify for a dependency, see the {{{/ref/current/maven-model/maven.html}Project Descriptor Reference}}. - ~~DJ: Does this link work? I can't find the document. - For more information about the dependency mechanism as a whole, see - {{{../introduction/introduction-to-dependency-mechanism.html}Introduction to Dependency Mechanism}}. - - With this information about a dependency, Maven will be able to reference the dependency when it builds the project. Where does - Maven reference the dependency from? Maven looks in your local repository (<<<$\{user.home\}/.m2/repository>>> is the default location) to find - all dependencies. In a {{{How_do_I_create_a_JAR_and_install_it_in_my_local_repository}previous section}}, we installed the artifact - from our project (my-app-1.0-SNAPSHOT.jar) into the local repository. Once it's installed there, another project can reference that jar - as a dependency simply by adding the dependency information to its <<>>: - -+----+ - - com.mycompany.app - my-other-app - ... - - ... - - com.mycompany.app - my-app - 1.0-SNAPSHOT - compile - - - -+----+ - - What about dependencies built somewhere else? How do they get into my local repository? Whenever a project references a dependency - that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository. You - probably noticed Maven downloading a lot of things when you built your very first project (these downloads were dependencies for the - various plugins used to build the project). By default, the remote repository Maven uses can be found (and browsed) at - {{https://repo.maven.apache.org/maven2/}}. You can also set up your own remote repository (maybe a central repository for your company) to - use instead of or in addition to the default remote repository. For more information on repositories you can refer to the - {{{../introduction/introduction-to-repositories.html}Introduction to Repositories}}. - - Let's add another dependency to our project. Let's say we've added some logging to the code and need to add log4j as a dependency. - First, we need to know what the groupId, artifactId, and version are for log4j. The appropriate directory on Maven Central is called - {{{https://repo.maven.apache.org/maven2/log4j/log4j/}/maven2/log4j/log4j}}. In that directory is a file called maven-metadata.xml. Here's what the maven-metadata.xml for - log4j looks like: - -+----+ - - log4j - log4j - 1.1.3 - - - 1.1.3 - 1.2.4 - 1.2.5 - 1.2.6 - 1.2.7 - 1.2.8 - 1.2.11 - 1.2.9 - 1.2.12 - - - -+----+ - - From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j". We see lots of different version values - to choose from; for now, we'll just use the latest version, 1.2.12 (some maven-metadata.xml files may also specify which version is - the current release version: see {{{/ref/current/maven-repository-metadata/repository-metadata.html}repository metadata reference}}). - Alongside the maven-metadata.xml file, we can see a directory corresponding to each version of the - log4j library. Inside each of these, we'll find the actual jar file (e.g. log4j-1.2.12.jar) as well as a pom file (this is the <<>> - for the dependency, indicating any further dependencies it might have and other information) and another maven-metadata.xml file. - There's also an md5 file corresponding to each of these, which contains an MD5 hash for these files. You can use this to authenticate - the library or to figure out which version of a particular library you may be using already. - - Now that we know the information we need, we can add the dependency to our pom.xml: - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - log4j - log4j - 1.2.12 - compile - - - -+----+ - - Now, when we compile the project (<<>>), we'll see Maven download the log4j dependency for us. - -~~DJ: Current - -* {How do I deploy my jar in my remote repository?} - - For deploying jars to an external repository, you have to configure the repository url in the <<>> - and the authentication information for connecting to the repository in the <<>>. - - Here is an example using scp and username/password authentication: - -+----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - jar - - Maven Quick Start Archetype - http://maven.apache.org - - - - junit - junit - 4.11 - test - - - org.apache.codehaus.plexus - plexus-utils - 1.0.4 - - - - - - src/main/filters/filters.properties - - - - src/main/resources - true - - - - - - - mycompany-repository - MyCompany Repository - scp://repository.mycompany.com/repository/maven2 - - - -+----+ - -+----+ - - ... - - - mycompany-repository - jvanzyl - - /path/to/identity (default is ~/.ssh/id_dsa) - my_key_passphrase - - - ... - -+----+ - - Note that if you are connecting to an openssh ssh server which has the parameter "PasswordAuthentication" set to "no" - in the sshd_config, you will have to type your password each time for username/password authentication - (although you can log in using another ssh client by typing in the username and password). - You might want to switch to public key authentication in this case. - - Care should be taken if using passwords in <<>>. For more information, see {{{../mini/guide-encryption.html} Password Encryption}}. - -* {How do I create documentation?} - - To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site - for your existing project using the following command: - ------- -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.maven.archetypes \ - -DarchetypeArtifactId=maven-archetype-site \ - -DgroupId=com.mycompany.app \ - -DartifactId=my-app-site ------- - - Now head on over to the {{{../mini/guide-site.html}Guide to creating a site}} - to learn how to create the documentation for your project. - -* {How do I build other types of projects?} - - Note that the lifecycle applies to any project type. For example, back in the base directory we can create a - simple web application: - ------- -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.maven.archetypes \ - -DarchetypeArtifactId=maven-archetype-webapp \ - -DgroupId=com.mycompany.app \ - -DartifactId=my-webapp ------- - - Note that these must all be on a single line. This will create a directory called - <<>> containing the following project descriptor: - -+----+ - - 4.0.0 - - com.mycompany.app - my-webapp - 1.0-SNAPSHOT - war - - - - junit - junit - 4.11 - test - - - - - my-webapp - - -+----+ - - Note the <<<\>>> element - this tells Maven to build as a WAR. Change into the webapp project's directory - and try: - ------- -mvn package ------- - - You'll see <<>> is built, and that all the normal steps were executed. - -* {How do I build more than one project at once?} - - The concept of dealing with multiple modules is built in to Maven. - In this section, we will show how to build the WAR above, and include the previous JAR as well in one step. - - Firstly, we need to add a parent <<>> file in the directory above the other two, so it should look like this: - ----- -+- pom.xml -+- my-app -| +- pom.xml -| +- src -| +- main -| +- java -+- my-webapp -| +- pom.xml -| +- src -| +- main -| +- webapp ----- - - The POM file you'll create should contain the following: - -+----+ - - 4.0.0 - - com.mycompany.app - app - 1.0-SNAPSHOT - pom - - - my-app - my-webapp - - -+----+ - - We'll need a dependency on the JAR from the webapp, so add this to <<>>: - -+----+ - ... - - - com.mycompany.app - my-app - 1.0-SNAPSHOT - - ... - -+----+ - - Finally, add the following <<<\>>> element to both of the other <<>> files in the subdirectories: - -+----+ - - - com.mycompany.app - app - 1.0-SNAPSHOT - - ... -+----+ - - Now, try it... from the top level directory, run: - ------- -mvn verify ------- - - The WAR has now been created in <<>>, and the JAR is included: - ----- -$ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war - 0 Fri Jun 24 10:59:56 EST 2005 META-INF/ - 222 Fri Jun 24 10:59:54 EST 2005 META-INF/MANIFEST.MF - 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/ - 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/ - 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/ -3239 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.xml - 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/ - 215 Fri Jun 24 10:59:56 EST 2005 WEB-INF/web.xml - 123 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.properties - 52 Fri Jun 24 10:59:56 EST 2005 index.jsp - 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/ -2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar ----- - - How does this work? Firstly, the parent POM created (called <<>>), has a packaging of <<>> - and a list of modules defined. This tells Maven to run all operations over the set of projects instead of - just the current one (to override this behaviour, you can use the <<<--non-recursive>>> command line option). - - Next, we tell the WAR that it requires the <<>> JAR. This does a few things: it makes it available - on the classpath to any code in the WAR (none in this case), it makes sure the JAR is always built before the - WAR, and it indicates to the WAR plugin to include the JAR in its library directory. - - You may have noticed that <<>> was a dependency, but didn't end up in the WAR. The - reason for this is the <<<\test\>>> element - it is only required for testing, - and so is not included in the web application as the compile time dependency <<>> is. - - The final step was to include a parent definition. - This ensures that the POM can always be located even if the project - is distributed separately from its parent by looking it up in the repository. diff --git a/content/apt/guides/getting-started/maven-in-five-minutes.apt b/content/apt/guides/getting-started/maven-in-five-minutes.apt deleted file mode 100644 index 55439c6a2d..0000000000 --- a/content/apt/guides/getting-started/maven-in-five-minutes.apt +++ /dev/null @@ -1,321 +0,0 @@ - ---- - Maven in 5 Minutes - ----- - Eric Redmond - ----- - 2008-01-01 - ----- - -~~ 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 - -Maven in 5 Minutes - -* Prerequisites - - You must understand how to install software on your computer. - If you do not know how to do this, please ask someone at your office, school, etc. - or pay someone to explain this to you. The Maven mailing lists are not the best place to ask for this advice. - -* Installation - - - - First, {{{../../download.html}download Maven}} and follow the {{{../../install.html}installation instructions}}. - After that, type the following in a terminal or in a command prompt: - ------ -mvn --version ------ - - It should print out your installed version of Maven, for example: - ------ -Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f) -Maven home: D:\apache-maven-3.6.3\apache-maven\bin\.. -Java version: 1.8.0_232, vendor: AdoptOpenJDK, runtime: C:\Program Files\AdoptOpenJDK\jdk-8.0.232.09-hotspot\jre -Default locale: en_US, platform encoding: Cp1250 -OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows" ------ - - Depending upon your network setup, you may require extra configuration. Check out the - {{{../mini/guide-configuring-maven.html}Guide to Configuring Maven}} if necessary. - - <> {{{./windows-prerequisites.html}Windows Prerequisites}} - <> - -* Creating a Project - - You need somewhere for your project to reside. Create a directory somewhere and start a shell in that directory. - On your command line, execute the following Maven goal: - ------ -mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false ------ - - - - You will notice that the goal created a directory with the same name given as the - artifactId. Change into that directory. - ------ -cd my-app ------ - - Under this directory you will notice the following - {{{../introduction/introduction-to-the-standard-directory-layout.html}standard project structure}}. - ------ -my-app -|-- pom.xml -`-- src - |-- main - | `-- java - | `-- com - | `-- mycompany - | `-- app - | `-- App.java - `-- test - `-- java - `-- com - `-- mycompany - `-- app - `-- AppTest.java ------ - - The <<>> directory contains the project source code, the <<>> directory contains - the test source, and the <<>> file is the project's Project Object Model, or POM. - -** The POM - - The <<>> file is the core of a project's configuration in Maven. It is a single configuration - file that contains the majority of information required to build a project in just the way you want. - The POM is huge and can be daunting in its complexity, but it is not necessary to understand all - of the intricacies just yet to use it effectively. This project's POM should look like this: - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1.0-SNAPSHOT - - my-app - - http://www.example.com - - - UTF-8 - 17 - - - - - - org.junit - junit-bom - 5.11.0 - pom - import - - - - - - - org.junit.jupiter - junit-jupiter-api - test - - - - org.junit.jupiter - junit-jupiter-params - test - - - - - - ... lots of helpful plugins - - - -+-----+ - -** What did I just do? - - You executed the Maven goal , and passed in various parameters to that goal. - The prefix is the {{{../../plugins/index.html}plugin}} that provides the goal. If you are familiar with - {{{http://ant.apache.org}Ant}}, you - may conceive of this as similar to a task. This goal created a simple project based upon - a {{{/archetypes/maven-archetype-quickstart/}maven-archetype-quickstart}} archetype. - Suffice it to say for now that a is a collection - of with a general common purpose. For example the jboss-maven-plugin, whose purpose is "deal with - various jboss items". - -** Build the Project - ------ -mvn package ------ - - The command line will print out various actions, and end with the following: - ------ - ... -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 2.953 s -[INFO] Finished at: 2019-11-24T13:05:10+01:00 -[INFO] ------------------------------------------------------------------------ ------ - - Unlike the first command executed (), the second is simply - a single word - . Rather than a , this is a . A phase is a step in the - {{{../introduction/introduction-to-the-lifecycle.html}build lifecycle}}, which is an ordered - sequence of phases. When a phase is given, Maven executes every phase in the sequence - up to and including the one defined. For example, if you execute the phase, the - phases that actually get executed are: - - [[1]] validate - - [[2]] generate-sources - - [[3]] process-sources - - [[4]] generate-resources - - [[5]] process-resources - - [[6]] compile - - [] - - You may test the newly compiled and packaged JAR with the following command: - ------ -java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App ------ - - Which will print the quintessential: - ------ -Hello World! ------ - -* Java 9 or later - - By default your version of Maven might use an old version of the <<>> - that is not compatible with Java 9 or later versions. To target Java 9 or later, - you should at least use version 3.6.0 of the <<>> and set the - <<>> property to the Java release you are targetting (e.g. 9, 10, 11, 12, etc.). - - In the following example, we have configured our Maven project to use version 3.8.1 of <<>> - and target Java 11: - -+-----+ - - 11 - - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.8.1 - - - - -+-----+ - - To learn more about <<>>'s <<<--release>>> option, see {{{https://openjdk.java.net/jeps/247}JEP 247}}. - -* Running Maven Tools - -** Maven Phases - - Although hardly a comprehensive list, these are the most common lifecycle phases executed. - - * <>: 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. - - [] - - There are two other Maven lifecycles of note beyond the list above. They are - - * <>: cleans up artifacts created by prior builds - - [] - - * <>: generates site documentation for this project - - [] - - Phases are actually mapped to underlying goals. The specific goals executed per phase is dependant upon the - packaging type of the project. For example, executes if the project type is a JAR, and - if the project type is - you guessed it - a WAR. - - An interesting thing to note is that phases and goals may be executed in sequence. - ------ -mvn clean dependency:copy-dependencies package ------ - - This command will clean the project, copy dependencies, and package the project (executing all phases up to - , of course). - -** Generating the Site - ------ -mvn site ------ - - This phase generates a site based upon information on the project's pom. You can look at the - documentation generated under <<>>. - -* Conclusion - - We hope this quick overview has piqued your interest in the versatility of Maven. Note that this is a very - truncated quick-start guide. Now you are ready for more comprehensive details concerning - the actions you have just performed. Check out the {{{./index.html}Maven Getting Started Guide}}. diff --git a/content/apt/guides/getting-started/windows-prerequisites.apt b/content/apt/guides/getting-started/windows-prerequisites.apt deleted file mode 100644 index 8fd7640bb9..0000000000 --- a/content/apt/guides/getting-started/windows-prerequisites.apt +++ /dev/null @@ -1,66 +0,0 @@ - ---- - Maven on Windows - ----- - Benson Margulies - ----- - 2012-07-01 - ----- - -~~ 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 - -Maven on Windows - - Maven is a command-line tool for building Java (and other) programs. The Maven project provides a simple ZIP - file containing a precompiled version of Maven for your convenience. There is no installer. It's up to you - to set up your prerequisites and environment to run Maven on Windows. - - -* Prerequisites - - Maven is written in Java (and primarily used to build Java programs). Thus, the major prerequisite is the Java SDK. - You need to install the Java SDK (e.g. from {{{https://www.oracle.com/technetwork/java/javase/downloads/index.html}Oracle's download site}}). - - Once Java is installed, you must ensure that the commands from the Java SDK are in your PATH environment variable. - Running, for example, - -------- -java -version -------- - - must show the right version number. - -* Maven Unpacked - - You need to unpack the Maven distribution. Don't unpack it in the middle of your source code; pick some location - and unpack it there. Let's assume that the path is <<<$\{maven.home\}>>>. - -* Maven in PATH - - You run Maven by invoking a command-line tool: <<>> from the <<>> directory of the Maven. To do this conveniently, - <<<$\{maven.home\}\bin>>> must be in your PATH, just like the Java SDK commands. You can add directories to your <<>> - in the control panel; the details vary by Windows version. - -* Firewalls and Anti-virus - - Firewall and Anti-virus sometimes prevent Java from running properly, or Windows Firewall (and various other Firewalls) actively - prevent Java.exe from reaching out to the Internet to "download stuff" which is a key part of Maven. - You may need to configure the Firewall or Anti-virus to add exceptions to allow such actions. - diff --git a/content/apt/guides/introduction/introduction-to-archetypes.apt b/content/apt/guides/introduction/introduction-to-archetypes.apt deleted file mode 100644 index ee3635ed69..0000000000 --- a/content/apt/guides/introduction/introduction-to-archetypes.apt +++ /dev/null @@ -1,102 +0,0 @@ - ------ - Introduction to Archetypes - ------ - Jason van Zyl - ------ - 2009-08-26 - ------ - -~~ 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 - -Introduction to Archetypes - -What is Archetype? - - In short, Archetype is a Maven project templating toolkit. An archetype is defined as . The name fits as we are trying to provide a system that - provides a consistent means of generating Maven projects. Archetype will help authors create - Maven project templates for users, and provides users with the means to generate parameterized versions - of those project templates. - - Using archetypes provides a great way to enable developers work quickly in a way consistent with best practices employed - by your project or organization. Within the Maven project, we use archetypes to try and get our users up and running - as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing - new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project - to use as a jumping board for investigating more of the features in Maven. We have also tried to make the Archetype - mechanism additive, and by that we mean allowing portions of a project to be captured in an archetype so that pieces - or aspects of a project can be added to existing projects. A good example of this is the Maven site archetype. - If, for example, you have used the quick start archetype to generate a working project, you can then quickly - create a site for that project by using the site archetype within that existing project. You can do anything like - this with archetypes. - - You may want to standardize J2EE development within your organization, so you may want to provide archetypes - for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's - repository, they are available for use by all developers within your organization. - -* Using an Archetype - - To create a new project based on an Archetype, you need to call <<>> goal, like the following: - ------ -mvn archetype:generate ------ - - Please refer to {{{/archetype/maven-archetype-plugin/}Archetype Plugin page}}. - -* Provided Archetypes - - Maven provides several Archetype artifacts: - -*-----------------------------+----------------+ -|| Archetype ArtifactIds || Description || -*-----------------------------+----------------+ -| maven-archetype-archetype | An archetype to generate a sample archetype project. | -*-----------------------------+----------------+ -| maven-archetype-j2ee-simple | An archetype to generate a simplifed sample J2EE application. | -*-----------------------------+----------------+ -| maven-archetype-mojo | An archetype to generate a sample a sample Maven plugin. | -*-----------------------------+----------------+ -| maven-archetype-plugin | An archetype to generate a sample Maven plugin. | -*-----------------------------+----------------+ -| maven-archetype-plugin-site | An archetype to generate a sample Maven plugin site. | -*-----------------------------+----------------+ -| maven-archetype-portlet | An archetype to generate a sample JSR-268 Portlet. | -*-----------------------------+----------------+ -| maven-archetype-quickstart | An archetype to generate a sample Maven project. | -*-----------------------------+----------------+ -| maven-archetype-simple | An archetype to generate a simple Maven project. | -*-----------------------------+----------------+ -| maven-archetype-site | An archetype to generate a sample Maven site which demonstrates some of the supported document types like APT, XDoc, and FML and demonstrates how to i18n your site. | -*-----------------------------+----------------+ -| maven-archetype-site-simple | An archetype to generate a sample Maven site. | -*-----------------------------+----------------+ -| maven-archetype-webapp | An archetype to generate a sample Maven Webapp project. | -*-----------------------------+----------------+ - - For more information on these archetypes, please refer to the {{{/archetypes/index.html}Maven Archetype Bundles page}}. - -* What makes up an Archetype? - - Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of - archetype, and a set of {{{http://velocity.apache.org/}Velocity}} templates which make up the prototype - project. If you would like to know how to make your own archetypes, please refer to our - {{{../mini/guide-creating-archetypes.html}Guide to creating archetypes}}. - diff --git a/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt b/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt deleted file mode 100644 index b63dc15bd2..0000000000 --- a/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt +++ /dev/null @@ -1,923 +0,0 @@ - ------ - Introduction to the Dependency Mechanism - ------ - Brett Porter - Trygve Laugstol - Karl Heinz Marbaise - ------ - 2005-10-12 - 2016-06-17 - ------ - -~~ 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 - -Introduction to the Dependency Mechanism - - Dependency management is a core feature of Maven. Managing dependencies for a single project is easy. - Managing dependencies for multi-module projects and applications that consist of hundreds of modules - is possible. Maven helps a great deal in defining, creating, and maintaining reproducible builds - with well-defined classpaths and library versions. - - Learn more about: - - * {{{Transitive_Dependencies}Transitive Dependencies}} - - * Excluded/Optional Dependencies - - * {{{Dependency_Scope}Dependency Scope}} - - * {{{Dependency_Management}Dependency Management}} - - * {{{Importing_Dependencies}Importing Dependencies}} - - * {{{bill-of-materials-bom-poms}Bill of Materials (BOM) POMs}} - - * {{{System_Dependencies}System Dependencies}} - - [] - -* {Transitive Dependencies} - - Maven avoids the need to discover and - specify the libraries that your own dependencies require by including transitive dependencies automatically. - - This feature is facilitated by reading the project files of your dependencies from the remote repositories - specified. In general, all dependencies of those projects are used in your project, as are any that the - project inherits from its parents, or from its dependencies, and so on. - - There is no limit to the number of levels that dependencies can be gathered from. A problem arises - only if a cyclic dependency is discovered. - - With transitive dependencies, the graph of included libraries can quickly grow quite large. For this reason, - there are additional features that limit which dependencies are included: - - * - - this determines what version of an artifact will be chosen when multiple - versions are encountered as dependencies. Maven picks the "nearest definition". That is, - it uses the version of the closest dependency to your project in the tree of dependencies. - You can always guarantee a version by declaring it explicitly in your project's POM. - Note that if two dependency versions are at the same depth in the dependency tree, - the first declaration wins. - - * "nearest definition" means that the version used will be the closest one to your project in the tree of dependencies. Consider this tree of dependencies: - ----- - A - ├── B - │ └── C - │ └── D 2.0 - └── E - └── D 1.0 ----- - - In text, dependencies for A, B, and C are defined as A -> B -> C -> D 2.0 and A -> E -> D 1.0, - then D 1.0 will be used when building A because the path from A to D through E is shorter. - You could explicitly add a dependency to D 2.0 in A to force the use of D 2.0, as shown here: - ----- - A - ├── B - │ └── C - │ └── D 2.0 - ├── E - │ └── D 1.0 - │ - └── D 2.0 ----- - - * - - this allows project authors to directly specify the versions of artifacts to be used when they are encountered - in transitive dependencies or in dependencies where no version has been specified. In the example in - the preceding section a dependency was directly added to A even though it is not directly used by A. Instead, - A can include D as a dependency in its dependencyManagement section and directly control which version of - D is used when, or if, it is ever referenced. - - * - - this allows you to only include dependencies appropriate for the current stage - of the build. This is described in more detail below. - - * - - If project X depends on project Y, and project Y depends on project Z, the owner of project X can explicitly exclude project Z - as a dependency, using the "exclusion" element. - - * - - If project Y depends on project Z, the owner of project Y can mark project Z - as an optional dependency, using the "optional" element. When project X depends on project Y, X will - depend only on Y and not on Y's optional dependency Z. The owner of project X may then - explicitly add a dependency on Z, at her option. (It may be helpful to think of optional - dependencies as "excluded by default.") - - [] - - Although transitive dependencies can implicitly include desired dependencies, it is a good practice to explicitly - specify the dependencies your source code uses directly. This best practice proves its value especially - when the dependencies of your project change their dependencies. - - For example, assume that your project A specifies a - dependency on another project B, and project B specifies a dependency on project C. If you are directly using components - in project C, and you don't specify project C in your project A, it may cause build failure when project B suddenly - updates/removes its dependency on project C. - - Another reason to directly specify dependencies is that it provides better - documentation for your project: one can learn more information by just reading the POM file in your project, or by executing <>. - - Maven also - provides {{{/plugins/maven-dependency-plugin/analyze-mojo.html}dependency:analyze}} plugin goal - for analyzing the dependencies: it helps making this best practice more achievable. - -* {Dependency Scope} - - Dependency scope is used to limit the transitivity of a dependency and to determine when a dependency is - included in a classpath. - - There are 6 scopes: - - * <>\ - This is the default scope, used if none is specified. Compile dependencies are available - in all classpaths of a project. Furthermore, those dependencies are propagated to dependent projects. - - * <>\ - This is much like <<>>, but indicates you expect the JDK or a container to provide the dependency at runtime. - For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the - Servlet API and related Java EE APIs to scope <<>> because the web container provides those classes. - A dependency with this scope is added to the classpath used for compilation and test, but not the - runtime classpath. It is not transitive. - - * <>\ - This scope indicates that the dependency is not required for compilation, but is for - execution. Maven includes a dependency with this scope in the runtime and test classpaths, - but not the compile classpath. - - * <>\ - This scope indicates that the dependency is not required for normal use of the application, and - is only available for the test compilation and execution phases. This scope is not transitive. - Typically this scope is used for test libraries such as JUnit and Mockito. - It is also used for non-test libraries such as Apache Commons IO if those libraries are used in - unit tests (src/test/java) but not in the model code (src/main/java). - - * <>\ - This scope is similar to <<>> except that you have to provide the JAR - which contains it explicitly. The artifact is always available and is not - looked up in a repository. - - * <>\ - This scope is only supported on a dependency of type <<>> in the <<<\>>> section. It - indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's - <<<\>>> section. Since they are replaced, dependencies with a scope of <<>> do not - actually participate in limiting the transitivity of a dependency. - - [] - - Each of the scopes (except for <<>>) affects transitive dependencies in different ways, as is demonstrated in the table below. - If a dependency is set to the scope in the left column, a transitive dependency of that dependency with the - scope across the top row results in a dependency in the main project with the scope listed at the - intersection. If no scope is listed, it means the dependency is omitted. - -*----------+------------+----------+----------+------+ -| | compile | provided | runtime | test -*----------+------------+----------+----------+------+ -| compile | compile(*) | - | runtime | - -*----------+------------+----------+----------+------+ -| provided | provided | - | provided | - -*----------+------------+----------+----------+------+ -| runtime | runtime | - | runtime | - -*----------+------------+----------+----------+------+ -| test | test | - | test | - -*----------+------------+----------+----------+------+ - - <<(*) Note:>> - it is intended that this should be runtime scope instead, so that all compile dependencies must - be explicitly listed. However, if a library you depend on extends a class from another - library, both must be available at compile time. For this reason, compile time dependencies remain - as compile scope even when they are transitive. - -* {Dependency Management} - - The dependency management section is a mechanism for centralizing dependency information. When you have - a set of projects that inherit from a common parent, it's possible to put all information about the dependency - in the common POM and have simpler references to the artifacts in the child POMs. The mechanism is best - illustrated through some examples. Given these two POMs which extend the same parent: - - Project A: - -+----+ - - - ... - - - group-a - artifact-a - 1.0 - - - group-c - excluded-artifact - - - - - group-a - artifact-b - 1.0 - bar - runtime - - - - -+----+ - - Project B: - -+----+ - - - ... - - - group-c - artifact-b - 1.0 - war - runtime - - - group-a - artifact-b - 1.0 - bar - runtime - - - - -+----+ - - These two example POMs share a common dependency and each has one non-trivial dependency. This information - can be put in the parent POM like this: - -+----+ - - - ... - - - - group-a - artifact-a - 1.0 - - - - group-c - excluded-artifact - - - - - - - group-c - artifact-b - 1.0 - war - runtime - - - - group-a - artifact-b - 1.0 - bar - runtime - - - - - -+----+ - - Then the two child POMs become much simpler: - -+----+ - - - ... - - - group-a - artifact-a - - - - group-a - artifact-b - - bar - - - - -+----+ - -+----+ - - - ... - - - group-c - artifact-b - - war - - - - group-a - artifact-b - - bar - - - - -+----+ - - <> In two of these dependency references, we had to specify the \ - element. This is because the minimal set of information for matching a dependency - reference against a dependencyManagement section is actually - <<\{groupId, artifactId, type, classifier\}>>. In many cases, these dependencies - will refer to jar artifacts with no classifier. This allows us to shorthand the - identity set to <<\{groupId, artifactId\}>>, since the default for the type field - is <<>>, and the default classifier is null. - - A second, and very important use of the dependency management section is to control the versions - of artifacts used in transitive dependencies. As an example consider these projects: - - Project A: - -+----+ - - - 4.0.0 - maven - A - pom - A - 1.0 - - - - test - a - 1.2 - - - test - b - 1.0 - compile - - - test - c - 1.0 - compile - - - test - d - 1.2 - - - - - -+----+ - - Project B: - -+----+ - - - - A - maven - 1.0 - - 4.0.0 - maven - B - pom - B - 1.0 - - - - - test - d - 1.0 - - - - - - - test - a - 1.0 - runtime - - - test - c - runtime - - - - -+----+ - - When maven is run on project B, version 1.0 of artifacts a, b, c, and d will be used regardless of - the version specified in their POM. - - * a and c both are declared as dependencies of the project so version 1.0 is used due to - dependency mediation. Both also have runtime scope since it is directly specified. - - * b is defined in B's parent's dependency management section and since dependency management - takes precedence over dependency mediation for transitive dependencies, version 1.0 will be - selected should it be referenced in a or c's POM. b will also have compile scope. - - * Finally, since d is specified in B's dependency management section, should d be a dependency - (or transitive dependency) of a or c, version 1.0 will be chosen - again because dependency - management takes precedence over dependency mediation and also because the current POM's - declaration takes precedence over its parent's declaration. - - [] - - <> The dependency management won't affect the (transitive) dependencies of any - used in the same effective POM but only the (transitive) project dependencies. - - The reference information about the dependency management tags is available from the - {{{../../ref/current/maven-model/maven.html#class_DependencyManagement}project descriptor reference}}. - -** {Importing Dependencies} - - The examples in the previous section describe how to specify managed dependencies through inheritance. However, - in larger projects it may be impossible to accomplish this since a project can only inherit from a single parent. - To accommodate this, projects can import managed dependencies from other projects. This is accomplished by declaring a - POM artifact as a dependency with a scope of "import". - - Project B: - -+----+ - - - 4.0.0 - maven - B - pom - B - 1.0 - - - - - maven - A - 1.0 - pom - import - - - test - d - 1.0 - - - - - - - test - a - 1.0 - runtime - - - test - c - runtime - - - - -+----+ - - Assuming A is the POM defined in the preceding example, the end result would be the same. All of A's managed dependencies - would be incorporated into B except for d since it is defined in this POM. - - Project X: - -+----+ - - - 4.0.0 - maven - X - pom - X - 1.0 - - - - - test - a - 1.1 - - - test - b - 1.0 - compile - - - - - -+----+ - - Project Y: - -+----+ - - - 4.0.0 - maven - Y - pom - Y - 1.0 - - - - - test - a - 1.2 - - - test - c - 1.0 - compile - - - - - -+----+ - - Project Z: - -+----+ - - - 4.0.0 - maven - Z - pom - Z - 1.0 - - - - - maven - X - 1.0 - pom - import - - - maven - Y - 1.0 - pom - import - - - - - -+----+ - - In the example above Z imports the managed dependencies from both X and Y. However, both X and Y contain dependency a. Here, - version 1.1 of a would be used since X is declared first and a is not declared in Z's dependencyManagement. - - This process is recursive. For example, if X imports another POM, Q, when Z is processed it will simply appear that all - of Q's managed dependencies are defined in X. - -** {Bill of Materials (BOM) POMs} - - Imports are most effective when used for defining a "library" of related artifacts that are generally part of a - multiproject build. It is fairly common for one project to use one or more artifacts from these libraries. - However, it has sometimes been difficult to keep the versions in the project using the artifacts in synch - with the versions distributed in the library. The pattern below illustrates how a "bill of materials" (BOM) can be - created for use by other projects. - - The root of the project is the BOM POM. It defines the versions of all the artifacts that will be created - in the library. Other projects that wish to use the library should import this POM into the dependencyManagement - section of their POM. - -+----+ - - - 4.0.0 - com.test - bom - 1.0.0 - pom - - 1.0.0 - 1.0.0 - - - - - - com.test - project1 - ${project1Version} - - - com.test - project2 - ${project2Version} - - - - - - parent - - - -+----+ - - The parent subproject has the BOM POM as its parent. It is a normal multiproject pom. - -+----+ - - - 4.0.0 - - com.test - 1.0.0 - bom - - - com.test - parent - 1.0.0 - pom - - - - - log4j - log4j - 1.2.12 - - - commons-logging - commons-logging - 1.1.1 - - - - - project1 - project2 - - - -+----+ - - Next are the actual project POMs. - -+----+ - - - 4.0.0 - - com.test - 1.0.0 - parent - - com.test - project1 - ${project1Version} - jar - - - - log4j - log4j - - - - - - 4.0.0 - - com.test - 1.0.0 - parent - - com.test - project2 - ${project2Version} - jar - - - - commons-logging - commons-logging - - - - -+----+ - - The project that follows shows how the library can now be used in another project without having to - specify the dependent project's versions. - -+----+ - - 4.0.0 - com.test - use - 1.0.0 - jar - - - - - com.test - bom - 1.0.0 - pom - import - - - - - - com.test - project1 - - - com.test - project2 - - - - -+----+ - - Finally, when creating projects that import dependencies, beware of the following: - - * Do not attempt to import a POM that is defined in a submodule of the current POM. - Attempting to do that will result in the build failing since it won't be able to locate the POM. - - * Never declare the POM importing a POM as the parent (or grandparent, etc) of the target POM. - There is no way to resolve the circularity and an exception will be thrown. - - * When referring to artifacts whose POMs have transitive dependencies, the project needs to specify versions - of those artifacts as managed dependencies. Not doing so results in a build failure since the - artifact may not have a version specified. (This should be considered a best practice in any case as it - keeps the versions of artifacts from changing from one build to the next). - - [] - - Starting from Maven 4.0, a new specific BOM packaging has been introduced. - It allows defining a BOMs which are not used as parent in a project leveraging - the newer 4.1.0 model, while still providing full compatibility with Maven 3.X - clients and projects. This BOM packaging is translated into a more usual POM - packaging at installation / deployment time, leveraging the build/consumer POM - feature from Maven 4. This thus provides full compatibility with Maven 3.x. - -+----+ - - - - com.test - 1.0.0 - parent - - com.test - bom - 1.0.0 - bom - - 1.0.0 - 1.0.0 - - - - - com.test - project1 - ${project1Version} - - - com.test - project2 - ${project2Version} - - - - - -+----+ - -* {System Dependencies} - - <<>> - - Dependencies with the scope are always available and are not looked - up in repository. They are usually used to tell Maven about dependencies which - are provided by the JDK or the VM. Thus, system dependencies are especially - useful for resolving dependencies on artifacts which are now provided by the - JDK, but were available as separate downloads earlier. Typical examples are - the JDBC standard extensions or the Java Authentication and Authorization - Service (JAAS). - - A simple example would be: - -+----+ - - - ... - - - javax.sql - jdbc-stdext - 2.0 - system - ${java.home}/lib/rt.jar - - - ... - - -+----+ - - If your artifact is provided by the JDK's <<>>, the system path - would be defined as follows: - -+----+ - - ... - - - sun.jdk - tools - 1.5.0 - system - ${java.home}/../lib/tools.jar - - - ... - -+----+ - - diff --git a/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt b/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt deleted file mode 100644 index 4ecceba620..0000000000 --- a/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt +++ /dev/null @@ -1,320 +0,0 @@ - ------ - Optional Dependencies and Dependency Exclusions - ------ - Allan Ramirez - ------ - 2006-01-23 - ------ - -~~ 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 - -Introduction - - This section discusses optional dependencies and - dependency exclusions. This will help users to understand what they are and - when and how to use them. It also explains why exclusions are made on a - per dependency basis instead of at the POM level. - -* Optional Dependencies - - Optional dependencies are used when it's not possible - (for whatever reason) to split a project into sub-modules. - The idea is that some of the dependencies are only used for certain features - in the project and will not be needed if that feature isn't used. Ideally, - such a feature would be split into a sub-module that depends on the core - functionality project. This new subproject would have only non-optional - dependencies, since you'd need them all if you decided to use the - subproject's functionality. - - However, since the project cannot be split up (again, for whatever reason), - these dependencies are declared optional. If a user wants to use - functionality related to an optional dependency, they have to redeclare - that optional dependency in their own project. This is not the clearest - way to handle this situation, but both optional dependencies and - dependency exclusions are stop-gap solutions. - -** Why use optional dependencies? - - Optional dependencies save space and memory. They prevent problematic jars - that violate a license agreement or cause classpath issues from being - bundled into a WAR, EAR, fat jar, or the like. - -** How do I use the optional tag? - - A dependency is declared optional by setting the <<<\>>> element - to true in its dependency declaration: - -+---+ - - - ... - - - - sample.ProjectA - Project-A - 1.0 - compile - true - - - - -+---+ - -** How do optional dependencies work? - ------ - -Project-A -> Project-B - ------ - - The diagram above says that Project-A depends on Project-B. When A - declares B as an optional dependency in its POM, this relationship remains - unchanged. It's just like a normal build where Project-B will be added in - Project-A's classpath. - ------ - -Project-X -> Project-A - ------ - - When another project (Project-X) declares Project-A as a dependency in - its POM, the optional nature of the dependency takes effect. - Project-B is not included in the classpath of Project-X. You - need to declare it directly in the POM of Project X for B to be included - in X's classpath. - -** Example - - Suppose there is a project named that has similar functionality - to . It supports many databases such as - MySQL, PostgreSQL, and several versions of Oracle. - Each supported database requires an additional dependency on a driver jar. - All of these dependencies are needed at compile time to build X2. - However your project only uses one specific database - and doesn't need drivers for the others. X2 can - declare these dependencies as optional, so that when your project - declares X2 as a direct dependency in its POM, all the drivers supported - by the X2 are not automatically included in your project's classpath. - Your project will have to include an explicit dependency on the specific - driver for the one database it does use. - -* Dependency Exclusions - - Since Maven resolves dependencies transitively, it is possible - for unwanted dependencies to be included in your project's classpath. - For example, a certain older jar may have security issues or be incompatible with the Java - version you're using. To address this, Maven allows you to exclude specific dependencies. - Exclusions are set on a specific dependency in your POM, and are targeted - at a specific groupId and artifactId. When you build your project, that - artifact will not be added to your project's classpath . - -** How to use dependency exclusions - - Add an <<<\>>> element in the <<<\>>> element by which - the problematic jar is included. - -+---+ - - - ... - - - sample.ProjectA - Project-A - 1.0 - compile - - - sample.ProjectB - Project-B - - - - - - -+---+ - -** How dependency exclusion works and when to use it <<( as a last resort! )>> - ------ - -Project-A - -> Project-B - -> Project-D - -> Project-E - -> Project-F - -> Project C - ------ - - The diagram shows that Project-A depends on both Project-B and C. Project-B - depends on Project-D. Project-D depends on both Project-E and F. By default, - Project A's classpath will include: - ------ -B, C, D, E, F ------ - - Suppose you don't want project D and its dependencies to be added to - Project A's classpath because some of Project-D's dependencies - are missing from the repository, and you - don't need the functionality in Project-B that depends on Project-D - anyway. Project-B's developers could have marked the dependency on - Project-D <<<\true\>>>: - -+---+ - - sample.ProjectD - ProjectD - 1.0-SNAPSHOT - true - -+---+ - - Unfortunately, they didn't. As a last resort, you can exclude it - on your own POM for Project-A like this: - -+---+ - - - 4.0.0 - sample.ProjectA - Project-A - 1.0-SNAPSHOT - jar - ... - - - sample.ProjectB - Project-B - 1.0-SNAPSHOT - - - sample.ProjectD - Project-D - - - - - - -+---+ - - If you deploy Project-A to a repository, and Project-X declares a - normal dependency on Project-A, will Project-D still be excluded from the - classpath? - ------ - -Project-X -> Project-A - ------ - - The answer is <>. Project-A has declared that it doesn't need - Project-D to run, so it won't be brought in as a transitive dependency - of Project-A. - - Now, consider that Project-X depends on Project-Y, as in the diagram below: - ------ - -Project-X -> Project-Y - -> Project-B - -> Project-D - ... - ------ - - Project-Y also has a dependency on Project-B, and it does need the features - supported by Project-D. Therefore, it will NOT place an exclusion on - Project-D in its dependency list. It may also supply an additional - repository, from which it can resolve Project-E. In this case, it's important - that Project-D <> excluded globally, since it is a legitimate - dependency of Project-Y. - - As another scenario, suppose the dependency you don't want is Project-E - instead of Project-D. How do you exclude it? See the diagram below: - ------ - -Project-A - -> Project-B - -> Project-D - -> Project-E - -> Project-F - -> Project C - ------ - - Exclusions work on the entire dependency graph below the point where they - are declared. If you want to exclude Project-E instead of Project-D, - simply change the exclusion to point at Project-E, but you don't - move the exclusion down to Project-D. You cannot change Project-D's POM. - If you could, you would use optional dependencies instead of exclusions, - or split Project-D up into multiple subprojects, each with nothing but - normal dependencies. - -+---+ - - - 4.0.0 - sample.ProjectA - Project-A - 1.0-SNAPSHOT - jar - ... - - - sample.ProjectB - Project-B - 1.0-SNAPSHOT - - - sample.ProjectE - Project-E - - - - - - -+---+ - -** Why exclusions are made on a per-dependency basis, rather than at the POM level - - This is mainly to be sure the dependency graph is predictable, and to - keep inheritance effects from excluding a dependency that should not be - excluded. If you get to the method of last resort and have to put in an - exclusion, you should be absolutely certain which of your dependencies is - bringing in that unwanted transitive dependency. - - If you truly want to ensure that a particular dependency appears nowhere in - your classpath, regardless of path, the - {{{/enforcer/enforcer-rules/bannedDependencies.html}banned dependencies rule}} - can be configured to fail the build if a problematic dependency is found. - When the build fails, you'll need to add specific exclusions on each path - the enforcer finds. diff --git a/content/apt/guides/introduction/introduction-to-plugins.apt b/content/apt/guides/introduction/introduction-to-plugins.apt deleted file mode 100644 index cde95074be..0000000000 --- a/content/apt/guides/introduction/introduction-to-plugins.apt +++ /dev/null @@ -1,87 +0,0 @@ - ------ - Introduction to Maven Plugin Development - ------ - John Casey - ------ - 2005-06-24 - ------ - -~~ 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 - -Introduction to Maven Plugin Development - - Maven consists of a core engine which provides basic project-processing - capabilities and build-process management, and a host of plugins which are - used to execute the actual build tasks. - -* What is a Plugin? - - "Maven" is really just a core framework for a collection of - Maven Plugins. In other words, plugins are where much of the real action is - performed, plugins are used to: create jar files, create war files, compile - code, unit test code, create project documentation, and on and on. Almost - any action that you can think of performing on a project is implemented as - a Maven plugin. - - Plugins are the central feature of Maven that allow for the reuse of - common build logic across multiple projects. They do this by executing an - "action" (i.e. creating a WAR file or compiling unit tests) in the context - of a project's description - the Project Object Model (POM). Plugin behavior - can be customized through a set of unique parameters which are exposed by a - description of each plugin goal (or Mojo). - - One of the simplest plugins in Maven is the Clean Plugin. The - {{{../../plugins/maven-clean-plugin/}Maven - Clean plugin}} (maven-clean-plugin) is responsible for removing the target - directory of a Maven project. When you run "mvn clean", Maven executes - the "clean" goal as defined in the Clean plug-in, and the target directory - is removed. The Clean plugin - {{{../../plugins/maven-clean-plugin/clean-mojo.html}defines - a parameter}} which can be used to customize plugin behavior, this parameter is - called outputDirectory and it defaults to $\{project.build.directory\}. - -* What is a Mojo ()? - - A Mojo is really just a <> in Maven, and plug-ins consist of - any number of goals (Mojos). Mojos can be defined as annotated Java classes or - Beanshell script. A Mojo specifies - metadata about a goal: a goal name, which phase of the lifecycle it fits into, - and the parameters it is expecting. - - MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for - "Plain". Mojo is also an interesting word (see {{{http://www.answers.com/mojo&r=67}definition}}). - From {{{http://www.wikipedia.org}Wikipedia}}, a "mojo" is defined as: - "...a small bag worn by a person under the clothes (also known as a mojo hand). - Such bags were thought to have supernatural powers, such as protecting from evil, - bringing good luck, etc." - -* What is the Build Lifecycle? (Overview) - - The build lifecycle is a series of common <>s through which all project - builds naturally progress. Plugin goals are bound to specific stages in the - lifecycle. - -Resources - - [[1]] {{{/plugin-developers/index.html}Plugin Development Center}} - - [[2]] {{{../mini/guide-configuring-plugins.html}Configuring plugins}} - diff --git a/content/apt/guides/introduction/introduction-to-profiles.apt b/content/apt/guides/introduction/introduction-to-profiles.apt deleted file mode 100644 index 3b5e3c6594..0000000000 --- a/content/apt/guides/introduction/introduction-to-profiles.apt +++ /dev/null @@ -1,835 +0,0 @@ - --- - Introduction to build profiles - --- - John Casey/Allan Ramirez - --- - 2008-01-01 - --- - -~~ 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 - -Introduction to Build Profiles - -%{toc|section=0|fromDepth=2|toDepth=5} - - Apache Maven goes to great lengths to ensure that builds are portable. Among - other things, this means allowing build configuration inside the POM, - avoiding <> filesystem references (in inheritance, dependencies, and - other places), and leaning much more heavily on the local repository to - store the metadata needed to make this possible. - - However, sometimes portability is not entirely possible. Under certain - conditions, plugins may need to be configured with local filesystem paths. - Under other circumstances, a slightly different dependency set will be - required, and the project's artifact name may need to be adjusted slightly. - And at still other times, you may even need to include a whole plugin in the - build lifecycle depending on the detected build environment. - - To address these circumstances, Maven supports build profiles. - Profiles are specified using a subset of the elements available in - the POM itself (plus one extra section), and are triggered in any of a - variety of ways. They modify the POM at build time, and are meant to be used - in complementary sets to give equivalent-but-different parameters for a set - of target environments (providing, for example, the path of the appserver root - in the development, testing, and production environments). As such, profiles - can easily lead to differing build results from different members of your team. - However, used properly, profiles can be used while still preserving - project portability. This will also minimize the use of <<<-f>>> option of - maven which allows user to create another POM with different parameters or - configuration to build which makes it more maintainable since it is running - with one POM only. - -* What are the different types of profile? Where is each defined? - - * Per Project - - - Defined in the POM itself <<<(pom.xml)>>>. - - * Per User - - - Defined in the {{{/ref/current/maven-settings/settings.html} Maven-settings}} - <<<(%USER_HOME%/.m2/settings.xml)>>>. - - * Global - - - Defined in the {{{/ref/current/maven-settings/settings.html} global Maven-settings}} - <<<($\{maven.home\}/conf/settings.xml)>>>. - -* Profile Inheritance - - The profiles are not inherited as other POM elements by child POMs. Instead they are resolved very early by the {{{/ref/current/maven-model-builder/}Maven Model Builder}} - and only the effects of active profiles are inherited (e.g. the plugins defined in the profile). - That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile (even if it has the same id). - -* How can a profile be triggered? How does this vary according to the type of profile being used? - - A profile can be activated in several ways: - - * Explicitly - - * Implicitly - - * Based on OS - - * Based on system properties - - * Based on presence of files - - [] - - Refer to the sections below for details. - -** Details on profile activation - -*** Explicit profile activation - - Profiles can be explicitly specified using the <<<-P>>> command line flag. - - This flag is followed by a comma-delimited list of - profile IDs to use. The profile(s) specified in the option - are activated in addition to any profiles which are activated by their activation - configuration or the <<<\>>> section in <<>>. - From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved. - To prevent this, prefix the profile identifier with an <<>>, marking it as optional: - ------ -mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3 ------ - - Profiles can be activated in the Maven settings, via the <<<\>>> - section. This section takes a list of <<<\>>> elements, each - containing a profile-id inside. - -+---+ - - ... - - profile-1 - - ... - -+---+ - - Profiles listed in the <<<\>>> tag would be activated by default - every time a project use it. - - Profiles can also be active by default using a configuration like the following in a POM: - -+---+ - - - profile-1 - - true - - ... - - -+---+ - - This profile will automatically be active for all builds unless another profile in the same POM - is activated using one of the previously described methods. All profiles that are active by - default are automatically deactivated when a profile in the POM is activated on the command line - or through its activation config. - -*** Implicit profile activation - - Profiles can be automatically triggered based on the detected state of - the build environment. These triggers are specified via an <<<\>>> - section in the profile itself. Currently, this detection is limited to - JDK version matching, operating system matching or - the presence/the value of a system property. The implicit profile activation always only refers to the container profile (and not to profiles in other modules with the same id). - Here are some examples. - -**** JDK - - The following configuration will trigger the profile when the JDK's - version "1.4" (eg. "1.4.0_08", "1.4.2_07", "1.4"), in particular it - for <> versions like "1.8" or "11": - -+---+ - - - - 1.4 - - ... - - -+---+ - - {{{/enforcer/enforcer-rules/versionRanges.html} Ranges}} can also be used. - Range values must start with either <<<[>>> or <<<(>>>. Otherwise, the value is interpreted as a prefix. - The following honours versions 1.3, 1.4 and 1.5. - -+---+ - - - - [1.3,1.6) - - ... - - -+---+ - - an upper bound such as <<<,1.5]>>> is likely not to include most releases of 1.5, since they will have an additional "patch" release such as <<<_05>>> that is not taken into consideration in the above range. - - -**** OS - - This next one will activate based on the detected operating system. See the {{{/enforcer/enforcer-rules/requireOS.html}Maven Enforcer Plugin}} for more details about OS values. - -+---+ - - - - - Windows XP - Windows - x86 - 5.1.2600 - - - ... - - -+---+ - - The values are interpreted as Strings and are matched against the {{{https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html}Java System properties}} - <<>>, <<>>, <<>> and the family being derived from those. - - Each value can be prefixed with <<>> to negate the matching. - The values match if they are (not) equal to the actual String value (<>). - All given OS conditions must match for the profile to be considered for activation. - - Since {{{https://issues.apache.org/jira/browse/MNG-5726}Maven 3.9.7}} the value for <<>> may be prefixed with <<>>. - In that case {{{https://docs.oracle.com/javase/tutorial/essential/regex/}regular pattern matching}} is applied for the version matching and applied against the <> <<>> value. - - The actual OS values which need to match the given values are emitted when executing <<>>. - -**** Property - - The profile below will be activated when the system property "debug" is specified - with any value: - -+---+ - - - - - debug - - - ... - - -+---+ - - The following profile will be activated when the system property "debug" is not defined - at all: - -+---+ - - - - - !debug - - - ... - - -+---+ - - The following profile will be activated when the system property "debug" is not defined, - or is defined with a value which is not "true". - -+---+ - - - - - debug - !true - - - ... - - -+---+ - - To activate this you would type one of those on the command line: - ------ -mvn groupId:artifactId:goal -mvn groupId:artifactId:goal -Ddebug=false ------ - - The next example will trigger the profile when the system property - "environment" is specified with the value "test": - -+---+ - - - - - environment - test - - - ... - - -+---+ - - To activate this you would type this on the command line: - ------ -mvn groupId:artifactId:goal -Denvironment=test ------ - - Profiles in the POM can also be activated based on properties from active profiles from the - <<>>. - - <>: Environment variables like <<>> are available as properties of the form <<>>. Further note - that environment variable names are normalized to all upper-case on Windows. - - Since Maven 3.9.0 one can also evaluate the POM's packaging value by referencing property <<>>. - This is only useful where the profile activation is defined in a common parent POM which is reused among multiple Maven projects. - The next example will trigger the profile when a project with packaging <<>> is built: - -+---+ - - - - - packaging - war - - - ... - - -+---+ - -**** Files - - This example will trigger the profile when the generated file - <<>> is missing. - -+---+ - - - - - target/generated-sources/axistools/wsdl2java/org/apache/maven - - - ... - - -+---+ - - The tags <<<\>>> and <<<\>>> can be interpolated. Supported variables are - system properties like <<<$\{user.home\}>>> and environment variables like <<<$\{env.HOME\}>>>. Please note that - properties and values defined in the POM itself are not available for interpolation here, e.g. the above example - activator cannot use <<<$\{project.build.directory\}>>> but needs to hard-code the path <<>>. - -*** Multiple conditions - - Different implicit activation types can be combined in one profile. - The profile is then only active if all conditions are met (since Maven 3.2.2, {{{https://issues.apache.org/jira/browse/MNG-4565}MNG-4565}}). - Using the same type more than once in the same profile is not supported ({{{https://issues.apache.org/jira/browse/MNG-5909}MNG-5909}}, {{{https://issues.apache.org/jira/browse/MNG-3328}MNG-3328}}). - -** Deactivating a profile - - One or more profiles can be deactivated using the command line by prefixing their - identifier with either the character '!' or '-' as shown below. - - <> that <<>> needs to be escaped with <<<\\>>> or quoted in Bash, ZSH and other shells as it has {{{https://www.gnu.org/software/bash/manual/html_node/Event-Designators.html}a special meaning}}. - Also there is a known bug with command line option values starting with <<<->>> ({{{https://issues.apache.org/jira/browse/CLI-309}CLI-309}}), therefore it is recommended to use it with the syntax <<<-P=-profilename>>>. - ------ -mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3 ------ - - or - ------ -mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3 ------ - - This can be used to deactivate profiles marked as activeByDefault or profiles that would - otherwise be activated through their activation config. - -* Which areas of a POM can be customized by each type of profile? Why? - - Now that we've talked about where to specify profiles, and how to activate them, - it will be useful to talk about you can specify in a profile. As with - the other aspects of profile configuration, this answer is not straightforward. - - Depending on where you choose to configure your profile, you will have access - to varying POM configuration options. - -** Profiles in external files - - Profiles specified in external files - (i.e in <<>> or <<>>) are not portable in the - strictest sense. Anything that seems to stand a high chance of changing the result - of the build is restricted to the inline profiles in the POM. Things like - repository lists could simply be a proprietary repository of approved - artifacts, and won't change the outcome of the build. Therefore, you will - only be able to modify the <<<\>>> and <<<\>>> - sections, plus an extra <<<\>>> section. - - The <<<\>>> section allows you to specify free-form key-value pairs - which will be included in the interpolation process for the POM. This allows - you to specify a plugin configuration in the form of <<<$\{profile.provided.path\}>>>. - -** Profiles in POMs - - On the other hand, if your profiles can be reasonably specified the - POM, you have many more options. The trade-off, of course, is that you can - only modify project and its sub-modules. Since these profiles are - specified inline, and therefore have a better chance of preserving portability, - it's reasonable to say you can add more information to them without the risk - of that information being unavailable to other users. - - Profiles specified in the POM can modify - {{{/ref/current/maven-model/maven.html}the following POM elements}}: - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> (not actually available in the main POM, but used behind the - scenes) - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * a subset of the <<<\>>> element, which consists of: - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - * <<<\>>> - - [] - -** POM elements outside \ - - We don't allow modification of some POM elements outside of POM-profiles - because these runtime modifications will not be distributed when the POM - is deployed to the repository system, making that person's build of that - project completely unique from others. While you can do this to some extent - with the options given for external profiles, the danger is limited. - Another reason is that this POM info is sometimes being reused from the - parent POM. - - External files such as <<>> and <<>> also do not support elements - outside the POM-profiles. Let us take this scenario for elaboration. When the - effective POM is deployed to a remote repository, any person can pickup - its info out of the repository and use it to build a Maven project directly. - Now, imagine that if we can set profiles in dependencies, which is very - important to a build, or in any other elements outside POM-profiles in - <<>> then most probably we cannot expect someone else to use that - POM from the repository and be able to build it. And we have to also think about - how to share the <<>> with others. Note that too many files to - configure are very confusing and very hard to maintain. - Bottom line is that since this is build data, it should be in the POM. - -* Profile Order - - All profile elements in a POM from active profiles overwrite the global elements with the same name of the POM or extend those in case of collections. - In case multiple profiles are active in the same POM or external file, the ones which are defined <> take precedence over the ones defined <> (independent of their profile id and activation order). - - Example: - -+---+ - - ... - - - global-repo - ... - - - ... - - - profile-1 - - true - - - - profile-1-repo - ... - - - - - profile-2 - - true - - - - profile-2-repo - ... - - - - ... - - ... - -+---+ - - This leads to the repository list: <<>>. - -* Profile Pitfalls - - We've already mentioned the fact that adding profiles to your build has the - potential to break portability for your project. We've even gone so far as to - highlight circumstances where profiles are likely to break project portability. - However, it's worth reiterating those points as part of a more coherent - discussion about some pitfalls to avoid when using profiles. - - There are two main problem areas to keep in mind when using profiles. - First are external properties, usually used in plugin configurations. These pose - the risk of breaking portability in your project. The other, more subtle area - is the incomplete specification of a natural set of profiles. - -** External Properties - - External property definition concerns any property value defined outside - the <<>> but not defined in a corresponding profile inside it. - The most obvious usage of properties in the POM is in plugin configuration. - While it is certainly possible to break project portability without properties, - these critters can have subtle effects that cause builds to fail. For example, - specifying appserver paths in a profile that is specified in the - <<>> may cause your integration test plugin to fail when another - user on the team attempts to build without a similar <<>>. - Consider the following <<>> snippet for a web application project: - -+---+ - - ... - - - - org.myco.plugins - spiffy-integrationTest-plugin - 1.0 - - ${appserver.home} - - - ... - - - ... - -+---+ - - Now, in your local <<<$\{user.home\}/.m2/settings.xml>>>, you have: - -+---+ - - ... - - - appserverConfig - - /path/to/appserver - - - - - - appserverConfig - - ... - -+---+ - - When you build the <> lifecycle phase, your integration - tests pass, since the path you've provided allows the test plugin to install - and test this web application. - - , when your colleague attempts to build to <>, - his build fails spectacularly, complaining that it cannot resolve the plugin - configuration parameter <<<\>>>, or worse, that the value of that - parameter - literally <<<$\{appserver.home\}>>> - is invalid (if it warns you at all). - - Congratulations, your project is now non-portable. Inlining this profile in - your <<>> can help alleviate this, with the obvious drawback that - each project hierarchy (allowing for the effects of inheritance) now have to - specify this information. Since Maven provides good support for project - inheritance, it's possible to stick this sort of configuration in the - <<<\>>> section of a team-level POM or similar, and simply - inherit the paths. - - Another, less attractive answer might be standardization of development - environments. However, this will tend to compromise the productivity - gain that Maven is capable of providing. - -** Incomplete Specification of a Natural Profile Set - - In addition to the above portability-breaker, it's easy to fail to cover all - cases with your profiles. When you do this, you're usually leaving one of - your target environments high and dry. Let's take the example <<>> - snippet from above one more time: - -+---+ - - ... - - - - org.myco.plugins - spiffy-integrationTest-plugin - 1.0 - - ${appserver.home} - - - ... - - - ... - -+---+ - - Now, consider the following profile, which would be specified inline in the - <<>>: - -+---+ - - ... - - - appserverConfig-dev - - - env - dev - - - - /path/to/dev/appserver - - - - - appserverConfig-dev-2 - - - env - dev-2 - - - - /path/to/another/dev/appserver2 - - - - .. - -+---+ - - This profile looks quite similar to the one from the last example, with a few - important exceptions: it's plainly geared toward a development environment, - a new profile named <<>> is added and it has an - activation section that will trigger its inclusion when the system - properties contain "env=dev" for a profile named <<>> and - "env=dev-2" for a profile named <<>>. So, executing: - ------ -mvn -Denv=dev-2 integration-test ------ - - will result in a successful build, applying the properties given - by profile named <<>>. And when we execute - ------ -mvn -Denv=dev integration-test ------ - - it will result in a successful build applying the properties given - by the profile named <<>>. However, executing: - ------ -mvn -Denv=production integration-test ------ - - will not do a successful build. Why? Because, the resulting non-interpolated - literal value of <<<$\{appserver.home\}>>> will not be a valid path for deploying - and testing your web application. We haven't considered the case for the - production environment when writing our profiles. The "production" - environment (env=production), along with "test" and possibly even "local" - constitute a natural set of target environments for which we may want to - build the integration-test lifecycle phase. The incomplete specification of - this natural set means we have effectively limited our valid target environments - to the development environment. Your teammates - and probably your manager - - will not see the humor in this. When you construct profiles to handle cases - such as these, be sure to address the entire set of target permutations. - - As a quick aside, it's possible for user-specific profiles to act in a similar - way. This means that profiles for handling different environments which are - keyed to the user can act up when the team adds a new developer. While I - suppose this act as useful training for the newbie, it just wouldn't - be nice to throw them to the wolves in this way. Again, be sure to think of the - set of profiles. - -* How can I tell which profiles are in effect during a build? - - Determining active profiles will help the user to know what particular - profiles has been executed during a build. We can use the {{{/plugins/maven-help-plugin/}Maven Help Plugin}} - to tell what profiles are in effect during a build. - ------ - mvn help:active-profiles ------ - - Let us have some small samples that will help us to understand more on the - goal of that plugin. - - From the last example of profiles in the <<>>, you'll notice that there are - two profiles named <<>> and <<>> - which has been given different values for properties. If we go ahead - and execute: - ------ - mvn help:active-profiles -Denv=dev ------ - - The result will be a bulleted list of the id of the profile with an - activation property of "env=dev" together with the source where it was - declared. See sample below. - ---- -The following profiles are active: - - - appserverConfig-dev (source: pom) ---- - - Now if we have a profile declared in <<>> (refer to the sample of profile - in <<>>) and that have been set to be an active profile and execute: - ------ - mvn help:active-profiles ------ - - The result should be something like this - ---- -The following profiles are active: - - - appserverConfig (source: settings.xml) ---- - - Even though we don't have an activation property, a profile has been listed as active. - Why? Like we mentioned before, a profile that has been set as an active profile - in the <<>> is automatically activated. - - Now if we have something like a profile in the <<>> that has been set - as an active profile and also triggered a profile in the POM. Which profile do - you think will have an effect on the build? - ------ - mvn help:active-profiles -P appserverConfig-dev ------ - - This will list the activated profiles: - ---- -The following profiles are active: - - - appserverConfig-dev (source: pom) - - appserverConfig (source: settings.xml) ---- - - Even though it listed the two active profiles, we are not sure which one - of them has been applied. To see the effect on the build execute: - ------ - mvn help:effective-pom -P appserverConfig-dev ------ - - This will print the effective POM for this build configuration out to the - console. Take note that profiles in the <<>> takes higher priority - than profiles in the POM. So the profile that has been applied here is - <<>> not <<>>. - - If you want to redirect the output from the plugin to a file called <<>>, - use the command-line option <<<-Doutput=effective-pom.xml>>>. - -* Naming Conventions - - By now you've noticed that profiles are a natural way of addressing the problem of - different build configuration requirements for different target environments. Above, - we discussed the concept of a "natural set" of profiles to address this situation, - and the importance of considering the whole set of profiles that will be required. - - However, the question of how to organize and manage the evolution of that set is - non-trivial as well. Just as a good developer strives to write self-documenting - code, it's important that your profile id's give a hint to their intended use. - One good way to do this is to use the common system property trigger as part of - the name for the profile. This might result in names like <>, <>, - and <> for profiles that are triggered by the system property <>. - Such a system leaves a highly intuitive hint on how to activate a build targeted - at a particular environment. Thus, to activate a build for the test environment, - you need to activate <> by issuing: - ------ -mvn -Denv=test ------ - - The right command-line option can be had by simply substituting "=" for "-" in - the profile id. - - diff --git a/content/apt/guides/introduction/introduction-to-repositories.apt b/content/apt/guides/introduction/introduction-to-repositories.apt deleted file mode 100644 index 099abbdc79..0000000000 --- a/content/apt/guides/introduction/introduction-to-repositories.apt +++ /dev/null @@ -1,167 +0,0 @@ - ------ - Introduction to Repositories - ------ - Jason van Zyl - Brian Fox - ------ - 2008-05-13 - ------ - -~~ 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 - -Introduction to Repositories - -* Artifact Repositories - - A repository in Maven holds build artifacts and dependencies of varying types. - - There are exactly two types of repositories: <> and <>: - - [[1]] the <> repository is a directory - on the computer where Maven runs. It caches remote downloads and contains temporary - build artifacts that you have not yet released. - - [[2]] <> repositories refer to any other type of repository, accessed by a variety of protocols such as - <<>> and <<>>. These repositories might be a truly remote repository - set up by a third party to provide their artifacts for downloading (for example, - {{{https://repo.maven.apache.org/maven2/}repo.maven.apache.org}}). - Other "remote" repositories may be internal repositories - set up on a file or HTTP server within your company, used to share private artifacts between development teams - and for releases. - - [] - - Local and remote repositories are structured the same way so that scripts can run on either - side, or they can be synced for offline use. The layout of the repositories is completely - transparent to the Maven user, however. - -* Using Repositories - - In general, you should not need to do anything with the local repository on a regular basis, except clean - it out if you are short on disk space (or erase it completely if you are willing to download everything again). - - For the remote repositories, they are used for both downloading and uploading (if you have the permission to - do so). - -** Downloading from a Remote Repository - - Downloading in Maven is triggered by a project declaring a dependency that is not present in the local - repository (or for a <<>>, when the remote repository contains one that is newer). - By default, Maven will download from the {{{https://repo.maven.apache.org/maven2/}central}} repository. - - To override this, you need to specify a <<>> as shown in {{{../mini/guide-mirror-settings.html}Using Mirrors for Repositories}}. - - You can set this in your <<>> file to globally use a certain mirror. However, - it is common for a project to {{{../mini/guide-multiple-repositories.html}customise the repository in its <<>>}} - and that your setting will take precedence. If dependencies are not being found, check that you - have not overridden the remote repository. - - For more information on dependencies, see {{{./introduction-to-dependency-mechanism.html}Dependency Mechanism}}. - -** Using Mirrors for the Central Repository - - There are {{{/repository/}several official Central repositories}} geographically distributed. You can make - changes to your <<>> file to use one or more mirrors. Instructions for this can be - found in the guide {{{../mini/guide-mirror-settings.html}Using Mirrors for Repositories}}. - -* Building Offline - - If you are temporarily disconnected from the internet and you need to build your projects offline, - you can use the offline switch on the CLI: - ------ - mvn -o package ------ - - Many plugins honor the offline setting and do not perform any operations that connect to - the internet. Some examples are resolving Javadoc links and link checking the site. - -* Uploading to a Remote Repository - - While this is possible for any type of remote repository, you must have the permission to do so. - To have someone upload to the Central Maven repository, see {{{../../repository/index.html}Repository Center}}. - -* Internal Repositories - - When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies - is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an - internal repository to house a copy of artifacts, and to publish private artifacts to. - - Such an internal repository can be downloaded using HTTP or the file system (with a <<>> - URL), and uploaded to using SCP, FTP, or a file copy. - - As far as Maven is concerned, there is nothing special about this repository: it is another - <> that contains artifacts to download to a user's local cache, and is a publish - destination for artifact releases. - - Additionally, you may want to share the repository server with your generated project sites. For more - information on creating and deploying sites, see {{{../mini/guide-site.html}Creating a Site}}. - -* Setting up the Internal Repository - - To set up an internal repository just requires that you have a place to put it, and then copy - required artifacts there using the same layout as in a remote repository such as {{{https://repo.maven.apache.org/maven2/}repo.maven.apache.org}}. - - It is recommended that you scrape or <<>> a full copy of central as there is a large amount - of data there and doing so will get you banned. You can use a program such as those described on the {{{../../repository-management.html}Repository Management}} page to - run your internal repository's server, download from the internet as required, and then hold - the artifacts in your internal repository for faster downloading later. - - The other options available are to manually download and vet releases, then copy them to the internal - repository, or to have Maven download them for a user, and manually upload the vetted artifacts to the - internal repository which is used for releases. This step is the only one available for artifacts where - the license forbids their distribution automatically, such as several J2EE JARs provided by Sun. - Refer to the {{{../mini/guide-coping-with-sun-jars.html}Guide to coping with SUN JARs}} document for more information. - - It should be noted that Maven intends to include enhanced support for such features in the future, - including click through licenses on downloading, and verification of signatures. - -* Using the Internal Repository - - Using the internal repository is quite simple. Simply make a change to add a <<>> element: - -+----+ - - - ... - - - my-internal-site - https://myserver/repo - - - ... - - -+----+ - - If your internal repository requires authentication, the <<>> element can be used in your {{{../../settings.html#Servers}settings}} file - to specify login information. - -* Deploying to the Internal Repository - - One of the most important reasons to have one or more internal repositories is to be able to publish - your own private releases. - - To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, WebDAV, or the filesystem. Connectivity is accomplished with the various - {{{/wagon/wagon-providers/index.html}wagons}}. Some wagons may need to be added as {{{/ref/current/maven-model/maven.html#class_extension}extension}} to your build. -~~ For example, to set up an SCP transfer. -~~ show the scp example. diff --git a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt b/content/apt/guides/introduction/introduction-to-the-lifecycle.apt deleted file mode 100644 index 5f7b78c633..0000000000 --- a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt +++ /dev/null @@ -1,481 +0,0 @@ - ------ - Introduction to the Build Lifecycle - ------ - Brett Porter - ------ - 2006-06-16 - 2015-04-04 - ------ - - ~~ Copyright 2015 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 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 <<>> lifecycle handles your project - deployment, the <<>> lifecycle handles project cleaning, while the <<>> lifecycle handles the creation of your - project's web site. - -** {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 comprises of the following phases (for a complete list of the lifecycle phases, refer - to the {{{Lifecycle_Reference}Lifecycle Reference}}): - - * <<>> - 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. - - * <<>> - run any checks on results of integration tests to ensure quality criteria are met - - * <<>> - install the package into the local repository, for use as a dependency in other projects locally - - * <<>> - done in the build environment, copies the final package to the remote repository - for sharing with other developers and projects. - - These lifecycle phases (plus the other lifecycle phases not shown here) are executed sequentially - to complete the <<>> lifecycle. - Given the lifecycle 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 integration tests, install the verified package to the local - repository, then deploy the installed package to a remote repository. - - <{{{./introduction-to-the-lifecycle.html}[top]}}.> - -** {Usual Command Line Calls} - - You should select the phase that matches your outcome. If you want your jar, run <<>>. If you want to run the - unit tests, run <<>>. - - If you are uncertain what you want, the preferred phase to call is - ------- -mvn verify ------- - - This command executes each default lifecycle phase in order (<<>>, <<>>, <<>>, etc.), - before executing <<>>. You only need to call the last build phase to be executed, in this case, <<>>. - In most cases the effect is the same as <<>>. However, in case there are integration tests, these will be - executed as well. And during the <<>> phase additional checks can be done, e.g. if your code is written - according to predefined checkstyle rules. - - In a build environment, use the following call to cleanly build and deploy artifacts into the shared repository. - ------- -mvn clean deploy ------- - - The same command can be used in a multi-module scenario (i.e. a project with one or more subprojects). Maven - traverses into every subproject and executes <<>>, then executes <<>> (including all of - the prior build phase 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 <<>> and <<>> arguments are build phases, while the - <<>> is a goal (of a plugin). - ------- -mvn clean dependency:copy-dependencies package ------- - - If this were to be executed, the <<>> phase will be executed first (meaning it will run all preceding phases of the clean lifecycle, - plus the <<>> phase itself), and then the <<>> goal, before finally executing the - <<>> phase (and all its preceding 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. -~~~ - Multiple goals bound to a phase are executed in the same order as they are declared in the - POM. Multiple instances of the same plugin are grouped to execute together. -~~~ - - <{{{./introduction-to-the-lifecycle.html}[top]}}.> - -** {Some Phases Are Not Usually Called From the Command Line} - - The phases named with hyphenated-words (<<>>, <<>>, or <<>>) are not usually directly - called from the command line. These phases sequence the build, producing intermediate results that are not useful outside - the build. In the case of invoking <<>>, the environment may be left in a hanging state. - - Code coverage tools such as Jacoco and execution container plugins such as Tomcat, Cargo, and Docker bind goals to the - <<>> phase to prepare the integration test container environment. These plugins also bind goals - to the <<>> phase to collect coverage statistics or decommission the integration test container. - - Failsafe and code coverage plugins bind goals to <<>> and <<>> phases. The net result is - test and coverage reports are available after the <<>> phase. If <<>> were to be called from the - command line, no reports are generated. Worse is that the integration test container environment is left in a hanging - state; the Tomcat webserver or Docker instance is left running, and Maven may not even terminate by itself. - - <{{{./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 <<<\>>>. Some of the valid - packaging values are <<>>, <<>>, <<>> and <<>>. If no packaging value has been specified, it will default - to <<>>. - - Each packaging contains a list of goals to bind to a particular phase. For example, the <<>> packaging will bind the following - goals to build phases of the default lifecycle. - -*------------------------------+---------------------------------------------------------------------------------------+ -|| Phase || plugin:goal for the <<>> packaging -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ -| <<>> | <<>> -*------------------------------+---------------------------------------------------------------------------------------+ - - This is an almost {{{/ref/current/maven-core/default-bindings.html}standard set of bindings}}; - however, some packagings handle them differently. For example, a project - that is purely metadata (packaging value is <<>>) only binds goals to the <<>> and <<>> 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 - <<<\>>> section of your POM and specify <<<\true\>>> for that plugin. - One example of a plugin that requires this is the Plexus plugin, which provides a <<>> and - <<>> 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: <<>> and <<>>. 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 <<<\>>> element to gain more - control over the order of particular goals. - - For example, the Modello plugin binds by default its goal <<>> to the <<>> phase (Note: The - <<>> 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 <<<\>>> section of - <<<\>>>: - -+----+ - - org.codehaus.modello - modello-maven-plugin - 1.8.1 - - - - - src/main/mdo/maven.mdo - - 4.0.0 - - - java - - - - -+----+ - - You might be wondering why that <<<\>>> 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 <<>>, 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 the commandline, 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 - display-maven-plugin - 1.0 - - - process-test-resources - - time - - - - -+----+ - - <{{{./introduction-to-the-lifecycle.html}[top]}}.> - -* {Lifecycle Reference} - - The following lists all build phases of the <<>>, <<>> and <<>> lifecycles, which are executed in the order given - up to the point of the one specified. - -** Clean Lifecycle - -*-------------------------------+---------------------------------------------------------------------------------------+ -|| Phase || Description -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | execute processes needed prior to the actual project cleaning -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | remove all files generated by the previous build -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | execute processes needed to finalize the project cleaning -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Default Lifecycle - -*-------------------------------+---------------------------------------------------------------------------------------+ -|| Phase || Description -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | validate the project is correct and all necessary information is available. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | initialize build state, e.g. set properties or create directories. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | 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 -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | post-process the generated files from test compilation, for example to do bytecode enhancement on Java classes. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | perform any operations necessary to prepare a package before the actual packaging. This often results in an unpacked, processed version of the package. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | take the compiled code and package it in its distributable format, such as a JAR. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | perform actions required before integration tests are executed. This may involve things such as setting up the required environment. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | process and deploy the package if necessary into an environment where integration tests can be run. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | perform actions required after integration tests have been executed. This may including cleaning up the environment. -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | 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. -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Site Lifecycle - -*-------------------------------+---------------------------------------------------------------------------------------+ -|| Phase || Description -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | execute processes needed prior to the actual project site generation -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | generate the project's site documentation -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | execute processes needed to finalize the site generation, and to prepare for site deployment -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | deploy 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 - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Default Lifecycle Bindings - Packaging <<>> / <<>> / <<>> / <<>> / <<>> / <<>> - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> <<>> <<>> <<>> <<>> <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Default Lifecycle Bindings - Packaging <<>> - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Default Lifecycle Bindings - Packaging <<>> - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Default Lifecycle Bindings - Packaging <<>> - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** Site Lifecycle Bindings - -*-------------------------------+--------------------------------------------------------------------------------------+ -|| Phase || plugin:goal -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ -| <<>> | <<>> -*-------------------------------+--------------------------------------------------------------------------------------+ - -** References - - The full Maven lifecycle is defined by the <<>> file in the <<>> module, with - {{{/ref/current/maven-core/lifecycles.html}associated documentation}} for reference. - - Default lifecycle bindings are defined in a separate - <<<{{{https://github.com/apache/maven/blob/master/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]}}.> diff --git a/content/apt/guides/introduction/introduction-to-the-pom.apt b/content/apt/guides/introduction/introduction-to-the-pom.apt deleted file mode 100644 index 45056b06ee..0000000000 --- a/content/apt/guides/introduction/introduction-to-the-pom.apt +++ /dev/null @@ -1,577 +0,0 @@ - ------ - Introduction to the POM - ------ - Jason van Zyl - Franz Allan Valencia See - Brett Porter - ------ - 2009-02-04 - ------ - -~~ 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 - -Introduction to the POM - - * {{{./introduction-to-the-pom.html#What_is_a_POM}What is a POM}}? - - * {{{./introduction-to-the-pom.html#Super_POM}Super POM}} - - * {{{./introduction-to-the-pom.html#Minimal_POM}Minimal POM}} - - * {{{./introduction-to-the-pom.html#Project_Inheritance}Project Inheritance}} - - * {{{./introduction-to-the-pom.html#Example_1}Example 1}} - - * {{{./introduction-to-the-pom.html#Example_2}Example 2}} - - [] - - * {{{./introduction-to-the-pom.html#Project_Aggregation}Project Aggregation}} - - * {{{./introduction-to-the-pom.html#Example_3}Example 3}} - - * {{{./introduction-to-the-pom.html#Example_4}Example 4}} - - [] - - * {{{./introduction-to-the-pom.html#Project_Inheritance_vs_Project_Aggregation}Project Inheritance vs Project Aggregation}} - - * {{{./introduction-to-the-pom.html#Example_5}Example 5}} - - [] - - * {{{./introduction-to-the-pom.html#Project_Interpolation}Project Interpolation and Variables}} - - * {{{./introduction-to-the-pom.html#Available_Variables}Available Variables}} - - [] - - [] - -* {What is a POM}? - - A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information - about the project and configuration details used by Maven to build the project. It contains default values for most projects. - Examples for this is the build directory, which is <<>>; the source directory, which is <<>>; the test - source directory, which is <<>>; and so on. When executing a task or goal, Maven - looks for the POM in the current directory. It reads the POM, gets the needed configuration information, then executes the - goal. - - Some of the configuration that can be specified in the POM are the project dependencies, the plugins or goals that - can be executed, the build profiles, and so on. Other information such as the project version, description, developers, - mailing lists and such can also be specified. - - {{{./introduction-to-the-pom.html}[top]}} - -* {Super POM} - - The Super POM is Maven's default POM. All POMs extend the Super POM unless explicitly set, meaning the configuration specified - in the Super POM is inherited by the POMs you created for your projects. - - You can see the {{{/maven-model-builder/super-pom.html}Super POM for the latest Maven 3 release}} in Maven Core reference documentation. - - {{{./introduction-to-the-pom.html}[top]}} - -* {Minimal POM} - - The minimum requirement for a POM are the following: - - * <<>> root - - * <<>> - should be set to 4.0.0 - - * <<>> - the id of the project's group. - - * <<>> - the id of the artifact (project) - - * <<>> - the version of the artifact under the specified group - - [] - - Here's an example: - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - -+-----+ - - A POM requires that its groupId, artifactId, and version be configured. These three values form the project's fully - qualified artifact name. This is in the form of \:\:\. As for the example above, its - fully qualified artifact name is "com.mycompany.app:my-app:1". - - Also, as mentioned in the {{{What_is_a_POM}first section}}, if the configuration details - are not specified, Maven will use their defaults. One of these default values is the packaging type. Every Maven project - has a packaging type. If it is not specified in the POM, then the default value "jar" would be used. - - Furthermore, you can see that in the minimal POM the were not specified. If you build your project using the minimal POM, - it would inherit the configuration in the Super POM. Therefore when Maven sees the dependencies in - the minimal POM, it would know that these dependencies will be downloaded from <<>> which was specified - in the Super POM. - - {{{./introduction-to-the-pom.html}[top]}} - -* {Project Inheritance} - - Elements in the POM that are merged are the following: - - * dependencies - - * developers and contributors - - * plugin lists (including reports) - - * plugin executions with matching ids - - * plugin configuration - - * resources - - [] - - The Super POM is one example of project inheritance, however you can also introduce your own parent POMs by specifying - the parent element in the POM, as demonstrated in the following examples. - - [] - -** {Example 1} - -*** The Scenario - - As an example, let us reuse our previous artifact, com.mycompany.app:my-app:1. And let us introduce another artifact, - com.mycompany.app:my-module:1. - -+-----+ - - 4.0.0 - - com.mycompany.app - my-module - 1 - -+-----+ - - And let us specify their directory structure as the following: - ------ -. - |-- my-module - | `-- pom.xml - `-- pom.xml ------ - - <> <<>> is the POM of com.mycompany.app:my-module:1 while <<>> is the POM of - com.mycompany.app:my-app:1 - -*** The Solution - - Now, if we were to turn com.mycompany.app:my-app:1 into a parent artifact of com.mycompany.app:my-module:1,we will have to - modify com.mycompany.app:my-module:1's POM to the following configuration: - - <> - -+-----+ - - 4.0.0 - - - com.mycompany.app - my-app - 1 - - - com.mycompany.app - my-module - 1 - -+-----+ - - Notice that we now have an added section, the parent section. This section allows us to specify which artifact is the - parent of our POM. And we do so by specifying the fully qualified artifact name of the parent POM. With this setup, our - module can now inherit some of the properties of our parent POM. - - Alternatively, if you want the groupId or the version of your modules to be the same as their parents, you can - remove the groupId or the version identity of your module in its POM. - -+-----+ - - 4.0.0 - - - com.mycompany.app - my-app - 1 - - - my-module - -+-----+ - - This allows the module to inherit the groupId or the version of its parent POM. - - {{{./introduction-to-the-pom.html}[top]}} - -** {Example 2} - -*** The Scenario - - However, that would work if the parent project was already installed in our local repository or was in that specific - directory structure (parent <<>> is one directory higher than that of the module's <<>>). - - But what if the parent is not yet installed and if the directory structure is as in the following example? - ------ -. - |-- my-module - | `-- pom.xml - `-- parent - `-- pom.xml ------ - -*** The Solution - - To address this directory structure (or any other directory structure), we would have to add the <<<\>>> element to - our parent section. - -+-----+ - - 4.0.0 - - - com.mycompany.app - my-app - 1 - ../parent/pom.xml - - - my-module - -+-----+ - - As the name suggests, it's the relative path from the module's <<>> to the parent's <<>>. - -* {Project Aggregation} - - Project Aggregation is similar to {{{Project_Inheritance}Project Inheritance}}. But - instead of specifying the parent POM from the module, it specifies the modules from the parent POM. By doing so, the - parent project now knows its modules, and if a Maven command is invoked against the parent project, that Maven command - will then be executed to the parent's modules as well. To do Project Aggregation, you must do the following: - - * Change the parent POMs packaging to the value "pom". - - * Specify in the parent POM the directories of its modules (children POMs). - - [] - - {{{./introduction-to-the-pom.html}[top]}} - -** {Example 3} - -*** The Scenario - - Given the previous original artifact POMs and directory structure: - - <> - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - -+-----+ - - <> - -+-----+ - - 4.0.0 - - com.mycompany.app - my-module - 1 - -+-----+ - - <> - ------ -. - |-- my-module - | `-- pom.xml - `-- pom.xml ------ - -*** The Solution - - If we are to aggregate my-module into my-app, we would only have to modify my-app. - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - pom - - - my-module - - -+-----+ - - In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For - the packaging, its value was set to "pom", and for the modules section, we have the element - <<<\my-module\>>>. The value of <<<\>>> is the relative path from the com.mycompany.app:my-app:1 - to com.mycompany.app:my-module:1's POM (). - - Now, whenever a Maven command processes com.mycompany.app:my-app:1, that same Maven command would be ran against - com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handle project aggregation - differently. - - {{{./introduction-to-the-pom.html}[top]}} - -** {Example 4} - -*** The Scenario - - But what if we change the directory structure to the following: - ------ -. - |-- my-module - | `-- pom.xml - `-- parent - `-- pom.xml ------ - - How would the parent POM specify its modules? - -*** The Solution - - The answer? - the same way as Example 3, by specifying the path to the module. - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - pom - - - ../my-module - - -+-----+ - -* {Project Inheritance vs Project Aggregation} - - If you have several Maven projects, and they all have similar configurations, you can refactor your projects by pulling - out those similar configurations and making a parent project. Thus, all you have to do is to let your Maven projects - inherit that parent project, and those configurations would then be applied to all of them. - - And if you have a group of projects that are built or processed together, you can create a parent project and have that - parent project declare those projects as its modules. By doing so, you'd only have to build the parent and the rest - will follow. - - But of course, you can have both Project Inheritance and Project Aggregation. Meaning, you can have your modules - specify a parent project, and at the same time, have that parent project specify those Maven projects as its modules. - You'd just have to apply all three rules: - - * Specify in every child POM who their parent POM is. - - * Change the parent POMs packaging to the value "pom" . - - * Specify in the parent POM the directories of its modules (children POMs) - - [] - - {{{./introduction-to-the-pom.html}[top]}} - -** {Example 5} - -*** The Scenario - - Given the previous original artifact POMs again, - - <> - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - -+-----+ - - <> - -+-----+ - - 4.0.0 - - com.mycompany.app - my-module - 1 - -+-----+ - - and this <> - ------ -. - |-- my-module - | `-- pom.xml - `-- parent - `-- pom.xml ------ - -*** The Solution - - To do both project inheritance and aggregation, you only have to apply all three rules. - - <> - -+-----+ - - 4.0.0 - - com.mycompany.app - my-app - 1 - pom - - - ../my-module - - -+-----+ - - <> - -+-----+ - - 4.0.0 - - - com.mycompany.app - my-app - 1 - ../parent/pom.xml - - - my-module - -+-----+ - - <> Profile inheritance the same inheritance strategy as used for the POM itself. - - {{{./introduction-to-the-pom.html}[top]}} - -* {Project Interpolation} and Variables - - One of the practices that Maven encourages is . However, there are circumstances where you will need to use the same value in several different locations. - To assist in ensuring the value is only specified once, Maven allows you to use both your own and pre-defined variables in the POM. - - For example, to access the <<>> variable, you would reference it like so: - -+----+ - ${project.version} -+----+ - - One factor to note is that these variables are processed inheritance as outlined above. This means that if a parent project uses a variable, then its definition in the child, not the parent, will be the one eventually used. - -** {Available Variables} - -*** Project Model Variables - - Any field of the model that is a single value element can be referenced as a variable. For example, <<<$\{project.groupId\}>>>, <<<$\{project.version\}>>>, <<<$\{project.build.sourceDirectory\}>>> and so on. - Refer to the POM reference to see a full list of properties. - - These variables are all referenced by the prefix "<<>>". You may also see references with <<>> as the prefix, or the prefix omitted entirely - these forms are now deprecated and should not be used. - -*** Special Variables - -*-----------------------------------+--------------------------------------+ -| <<>> | The directory that the current project resides in. | -*-----------------------------------+--------------------------------------+ -| <<>> | The directory that the current project resides in, represented as an URI. | -*-----------------------------------+--------------------------------------+ -| <<>> | The timestamp that denotes the start of the build (UTC). | -*-----------------------------------+--------------------------------------+ - - The format of the build timestamp can be customized by declaring the property <<>> as - shown in the example below: - -+----+ - - ... - - yyyy-MM-dd'T'HH:mm:ss'Z' - - ... - -+----+ - - The format pattern has to comply with the rules given in the API documentation for - {{{https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html}SimpleDateFormat}}. - If the property is not present, the format defaults to the value already given in the example. - -*** Properties - - You are also able to reference any properties defined in the project as a variable. Consider the following example: - -+----+ - - ... - - 3.0 - - - - - org.apache.maven - maven-artifact - ${mavenVersion} - - - org.apache.maven - maven-core - ${mavenVersion} - - - ... - -+----+ - - {{{./introduction-to-the-pom.html}[top]}} - diff --git a/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt b/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt deleted file mode 100644 index 531208bcb4..0000000000 --- a/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt +++ /dev/null @@ -1,86 +0,0 @@ - ------ - Introduction to the Standard Directory Layout - ------ - Jason van Zyl - ------ - 2014-03-09 - ------ - -~~ 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 - -Introduction to the Standard Directory Layout - - Having a common directory layout allows users familiar with one Maven project to immediately feel - at home in another Maven project. The advantages are analogous to adopting a site-wide look-and-feel. - - The next section documents the directory layout expected by Maven and the directory layout created by - Maven. Try to conform to this structure as much as possible. However, if you can't, these settings can - be overridden via the project descriptor. - -*-----------------------------------+-----------------------------------------------+ -| <<>> | Application/Library sources -*-----------------------------------+-----------------------------------------------+ -| <<>> | Application/Library resources -*-----------------------------------+-----------------------------------------------+ -| <<>> | Resource filter files -*-----------------------------------+-----------------------------------------------+ -| <<>> | Web application sources -*-----------------------------------+-----------------------------------------------+ -| <<>> | Test sources -*-----------------------------------+-----------------------------------------------+ -| <<>> | Test resources -*-----------------------------------+-----------------------------------------------+ -| <<>> | Test resource filter files -*-----------------------------------+-----------------------------------------------+ -| <<>> | Integration Tests (primarily for plugins) -*-----------------------------------+-----------------------------------------------+ -| <<>> | Assembly descriptors -*-----------------------------------+-----------------------------------------------+ -| <<>> | Site -*-----------------------------------+-----------------------------------------------+ -| <<>> | Project's license -*-----------------------------------+-----------------------------------------------+ -| <<>> | Notices and attributions required by libraries that the project depends on -*-----------------------------------+-----------------------------------------------+ -| <<>> | Project's readme -*-----------------------------------+-----------------------------------------------+ - - - At the top level, files descriptive of the project: a <<>> file. - In addition, there are textual documents meant for the user to be able to - read immediately on receiving the source: <<>>, <<>>, etc. - - There are just two subdirectories of this structure: <<>> and <<>>. The only other - directories that would be expected here are metadata like <<>>, <<<.git>>> or <<<.svn>>>, and any - subprojects in a multiproject build (each of which would be laid out as above). - - The <<>> directory is used to house all output of the build. - - The <<>> directory contains all of the source material for building the project, its site and so on. - It contains a subdirectory for each type: <<
>> for the main build artifact, <<>> for - the unit test code and resources, <<>> and so on. - - Within artifact producing source directories (ie. <<
>> and <<>>), there is one - directory for the language <<>> (under which the normal package hierarchy exists), and one for - <<>> (the structure which is copied to the target classpath given the default resource definition). - - If there are other contributing sources to the artifact build, they would be under other subdirectories. For - example <<>> would contain Antlr grammar definition files. diff --git a/content/apt/guides/mini/guide-3rd-party-jars-local.apt b/content/apt/guides/mini/guide-3rd-party-jars-local.apt deleted file mode 100644 index 870092558e..0000000000 --- a/content/apt/guides/mini/guide-3rd-party-jars-local.apt +++ /dev/null @@ -1,59 +0,0 @@ - ------ - Guide to installing 3rd party JARs - ------ - Jason van Zyl - Robert Scholte - ------ - 2013-07-13 - ------ - -~~ 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 - -Guide to installing 3rd party JARs - - Occasionally, you will have 3rd party JARs that you need to put in your local repository for use in your - builds, since they don't exist in any public repository like {{{https://search.maven.org}Maven Central}}. - The JARs must be placed in the local repository in the correct place in order for it to be correctly - picked up by Apache Maven. - - To make this easier, and less error prone, we have provided an <<>> goal in the - {{{/plugins/maven-install-plugin/}maven-install-plugin}} which should make this relatively painless. - - To install a JAR in the local repository use the following command: - ----- -mvn install:install-file -Dfile= -DgroupId= -DartifactId= -Dversion= -Dpackaging= ----- - - If there's a pom-file as well, you can install it with the following command: - ----- -mvn install:install-file -Dfile= -DpomFile= ----- - - With version 2.5 of the maven-install-plugin, it can get even simpler: if the JAR was built by Apache Maven, it'll contain a - pom.xml in a subdirectory of the META-INF/ directory, which will be read by default. In that case, all you need to do is: - ----- -mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile= ----- - - diff --git a/content/apt/guides/mini/guide-3rd-party-jars-remote.apt b/content/apt/guides/mini/guide-3rd-party-jars-remote.apt deleted file mode 100644 index 9670586d2a..0000000000 --- a/content/apt/guides/mini/guide-3rd-party-jars-remote.apt +++ /dev/null @@ -1,87 +0,0 @@ - ------ - Guide to deploying 3rd party JARs to remote repository - ------ - Allan Ramirez - ------ - 2006-02-22 - ------ - -~~ 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 - -Guide to deploying 3rd party JARs to remote repository - - Same concept of the {{{./guide-3rd-party-jars-local.html}install:install-file}} - goal of the maven-install-plugin where the 3rd party JAR is installed - in the local repository. But this time instead to local repository the - JAR will be install both in the local and remote repository. - - To deploy a 3rd party JAR use the deploy:deploy-file goal under - maven-deploy-plugin. - - First, the wagon-provider(wagon-ftp, wagon-file, etc..) must be placed to - your <<<$\{maven.home\}/lib>>>. - - Then execute the command: - ------- -mvn deploy:deploy-file -DgroupId= \ - -DartifactId= \ - -Dversion= \ - -Dpackaging= \ - -Dfile= \ - -DrepositoryId= \ - -Durl= ------- - -* Deploying a 3rd party JAR with a generic POM - - By default, deploy:deploy-file generates a generic POM(.pom) to be deploy - together with the 3rd party JAR. To disable this feature we should set the - <<>> argument to false. - ------- --DgeneratePom=false ------- - -* Deploying a 3rd party JAR with a customized POM - - If a POM is already existing for the 3rd Party JAR and you want to deploy - it together with the JAR we should use the <<>> argument of the - deploy-file goal. See sample below. - ------- -mvn deploy:deploy-file -DpomFile= \ - -Dfile= \ - -DrepositoryId= \ - -Durl= ------- - - Note that <<>>, <<>>, <<>> and <<>> - arguments are not included here because deploy-file goal will get these - information from the given POM. - -* Deploying Source Jars - -~~ TODO: Check the following, cause i don't this is true anymore. I assume packaging should be jar -~~  and the classifier should be set to source. - - To deploy a 3rd party source jar, packaging should be set to <<>>, and - generatePom should be set to <<>>. diff --git a/content/apt/guides/mini/guide-archive-configuration.apt b/content/apt/guides/mini/guide-archive-configuration.apt deleted file mode 100644 index f0011a2514..0000000000 --- a/content/apt/guides/mini/guide-archive-configuration.apt +++ /dev/null @@ -1,71 +0,0 @@ - ------ - Guide to Configuring Archive Plugins - ------ - Brett Porter - ------ - 2006-06-21 - ------ - -~~ 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 - -Guide to Configuring Archive Plugins - - Many Java archive generating plugins accept the <<>> configuration element to customize the generation of the archive. - In the standard Maven Plugins, this includes the <<>>, <<>>, <<>>, <<>> and <<>> plugins. - -* Disabling Maven Meta Information - - By default, Maven generated archives include the <<>> directory, which contains the <<>> file used to - build the archive, and a <<>> file that includes some basic properties in a small, easier to read format. - - To disable the generation of these files, include the following configuration for your plugin (in this example, the WAR plugin - is used): - -+----+ - - ... - - - - org.apache.maven.plugins - maven-war-plugin - 2.6 - - - false - - - - - - ... - - -+----+ - -~~ other things: index, compress - -* Configuring the Manifest - - The archive configuration also accepts manifest configuration. See {{{./guide-manifest.html}Guide to Working with Manifests}} for more information. - - - diff --git a/content/apt/guides/mini/guide-bash-m2-completion.apt b/content/apt/guides/mini/guide-bash-m2-completion.apt deleted file mode 100644 index 96ac937748..0000000000 --- a/content/apt/guides/mini/guide-bash-m2-completion.apt +++ /dev/null @@ -1,37 +0,0 @@ - ------ - Guide to Maven auto completion using BASH - ------ - Trygve Laugstol - Jason van Zyl - Karl Heinz Marbaise - ------ - 2016-01-24 - ------ - -~~ 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 - -Guide to Maven auto completion using BASH - - If you like having bash completion which i can recommend if you are working - with Maven on command line i would suggest to install - the following {{{https://github.com/juven/maven-bash-completion}Maven Bash Auto Completion}} - to fullfil you needs. - diff --git a/content/apt/guides/mini/guide-building-for-different-environments.apt b/content/apt/guides/mini/guide-building-for-different-environments.apt deleted file mode 100644 index b1813f55e8..0000000000 --- a/content/apt/guides/mini/guide-building-for-different-environments.apt +++ /dev/null @@ -1,161 +0,0 @@ - --- - Building For Different Environments - --- - Trygve Laugstøl - --- - 2006-01-01 - --- - -~~ 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 - -Building For Different Environments - - Building the same artifact for different environments has always been an annoyance. You have multiple environments, - for instance test and production servers or, maybe a set of servers that run the same application with different - configurations. In this guide I'll explain how you can use profiles to build and package artifacts configured for - specific environments. See {{{../introduction/introduction-to-profiles.html}Introduction to Build Profiles}} for a - more in-depth explanation of the profile concept. - - Note: - - * This guide assume that you have basic Maven knowledge. - - * It will show a way to configure Maven to solve simple configuration set-ups only. By simple configuration set-up I - mean cases where you only have a single file or a small set of files that vary for each environment. There are - other and better ways to handle two and many-dimensional configuration issues. - - - This example assume the use of the - {{{../introduction/introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}. - ----- -pom.xml -src/ - main/ - java/ - resources/ - test/ - java/ ----- - - - Under <<>> there are three files: - - * <<>> - This is the default configuration and will be packaged in the artifact by default. - - * <<>> - This is the variant for the test environment. - - * <<>> - This is basically the same as the test variant and will be used in the - production environment. - - In the project descriptor, you need to configure the different profiles. Only the test profile is showed here. - -+----+ - - - test - - - - maven-antrun-plugin - - - test - - run - - - - - - - - - - - - maven-surefire-plugin - - true - - - - maven-jar-plugin - - - package - - jar - - - test - - - - - - - - - .. Other profiles go here .. - - -+----+ - - Three things are configured in this snippet: - - [[1]] It configures the antrun plugin to execute the run goal in the test phase where it will copy the - <<>> file to <<>>. - - [[2]] It will configure the test plugin to skip all tests when building the test and production artifacts. - This is useful as you probably don't want to run tests against the production system - - [[3]] It configures the JAR plugin to create an "attached" JAR with the "test" classifier. - - To activate this profile execute <<>> and Maven will execute the steps in the profile - in addition to the normal steps. From this build you will get two artifacts, "foo-1.0.jar" and "foo-1.0-test.jar". - These two jars will identical. - -Caveats - - * Currently Maven doesn't allow a project build to only produce attached artifacts. (i.e. it has to produce a - "main" artifact as well) This results in two equal JARs being packaged and installed. The JAR plugin probably - should also get improved support for this use case to that two different output directories will be used as the - basis for building the JAR. - - * The usage of the delete task might seem a bit odd but is required to make sure that the copy task actually will - copy the file. The copy task will look at the timestamps of the source and destination files, only when copying the - files it won't know that the actually source file might be different than the last time it was executed. - - * After the build the test configuration will be in target/classes and won't be overridden because the resources - plugin uses the same timestamp checking, so you should always do a clean after executing Maven with a profile. - - * For the reasons given above it's imperative that you only build an artifact for a single environment in a single - execution at a time and that you execute "mvn clean" whenever you change the profile switches. If not, you might get - artifacts with a mixed set of configuration files. - -Resources - - [[1]] {{{../introduction/introduction-to-profiles.html}Introduction to Build Profiles}} - - [[2]] {{{../introduction/introduction-to-the-standard-directory-layout.html}Standard Directory Layout}} - diff --git a/content/apt/guides/mini/guide-configuring-maven.apt b/content/apt/guides/mini/guide-configuring-maven.apt deleted file mode 100644 index 9f58970a73..0000000000 --- a/content/apt/guides/mini/guide-configuring-maven.apt +++ /dev/null @@ -1,171 +0,0 @@ - ------ - Guide to Configuring Maven - ------ - Brett Porter - ------ - 2005-04-12 - ------ - -~~ 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 - -Configuring Maven - - Maven configuration occurs at 3 levels: - - * - most static configuration occurs in <<>> - - * - this is configuration added once for a Maven installation - - * - this is configuration specific to a particular user - - The separation is quite clear - the project defines information that applies to the project, no matter who is - building it, while the others both define settings for the current environment. - - <> the installation and user configuration cannot be used to add shared project information - - for example, setting <<<\>>> or <<<\>>> company-wide. - - For this, you should have your projects inherit from a company-wide parent <<>>. - - ~~TODO: versioning doc that discusses this - - You can specify your user configuration in <<<$\{user.home\}/.m2/settings.xml>>>. A - {{{../../maven-settings/settings.html}full reference}} to the configuration file is available. This section will show how - to make some common configurations. Note that the file is not required - defaults will be used if it is not found. - -* Configuring your Local Repository - - The location of your local repository can be changed in your user configuration. - The default value is <<<$\{user.home\}/.m2/repository/>>>. - -+-------------+ - - ... - /path/to/local/repo/ - ... - -+-------------+ - - <> The local repository must be an absolute path. - -* Configuring a Proxy - - Proxy configuration can also be specified in the settings file. - - For more information, see the {{{./guide-proxies.html} Guide to using a Proxy}}. - -* Configuring Parallel Artifact Resolution - - By default, Maven 2.1.0+ will download up to 5 artifacts (from different groups) at once. To change the size of the thread pool, start Maven using - <<<-Dmaven.artifact.threads>>>. For example, to only download single artifacts at a time: - ----- -mvn -Dmaven.artifact.threads=1 verify ----- - - You may wish to set this option permanently, in which case you can use the <<>> environment variable. For example: - ----- -export MAVEN_OPTS=-Dmaven.artifact.threads=3 ----- - -* Security and Deployment Settings - - Repositories to deploy to are defined in a project in the <<<\>>> section. - However, you cannot put your username, password, or other security settings in that project. For that reason, - you should add a server definition to your own settings with an - <<>> that matches that of the deployment repository in the project. - - In addition, some repositories may require authorization to download from, so the corresponding settings can - be specified in a <<>> element in the same way. - - Which settings are required will depend on the type of repository you are deploying to. As of the first release, - only SCP deployments and file deployments are supported by default, so only the following SCP configuration - is needed: - -+-------------+ - - ... - - - repo1 - repouser - - - ... - - ... - -+-------------+ - - To encrypt passwords in these sections, refer to {{{./guide-encryption.html} Encryption Settings}}. - -* Using Mirrors for Repositories - - Repositories can be declared inside a project, which means that if you have your own custom repositories, those - sharing your project easily get the right settings out of the box. However, you may want to use an alternative - mirror for a particular repository without changing the project files. Refer to {{{./guide-mirror-settings.html} Guide to Mirror Settings}} - for more details. - - -* Profiles - - Repository configuration can also be put into a profile. You can have multiple - profiles, with one set to active so that you can easily switch environments. - Read more about profiles in {{{../introduction/introduction-to-profiles.html}Introduction to Build Profiles}}. - - - - -* Optional configuration - - Maven will work for most tasks with the above configuration, however if you have any environmental specific configuration outside of individual - projects then you will need to configure settings. The following sections refer to what is available. - - -** Settings - - Maven has a settings file located in the Maven installation and/or user home directory that configure environmental specifics such as: - - * HTTP proxy server - - * repository manager location - - * server authentication and passwords - - * other configuration properties - - [] - - For information on this file, see the {{{/settings.html}Settings reference}} - -** Security - - You can encrypt passwords in your settings file. However, you must first configure a master password. For more information on - both server passwords and the master password, see the {{{./guide-encryption.html}Guide to Password Encryption}}. - -** Toolchains - - You can build a project using a specific version of JDK independent from the one Maven is running with. - For more information, see the {{{./guide-using-toolchains.html}Guide to Using Toolchains}}. diff --git a/content/apt/guides/mini/guide-configuring-plugins.apt b/content/apt/guides/mini/guide-configuring-plugins.apt deleted file mode 100644 index b152eebc28..0000000000 --- a/content/apt/guides/mini/guide-configuring-plugins.apt +++ /dev/null @@ -1,766 +0,0 @@ - ------ - Guide to Configuring Plug-ins - ------ - Jason van Zyl - Vincent Siveton - ------ - 2009-08-26 - ------ - -~~ 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 - -Guide to Configuring Plug-ins - -%{toc|fromDepth=2} - -* Introduction - - In Maven, there are two kinds of plugins, build and reporting: - - * <> are executed during the build and configured in the <<<\>>> - element. - - * <> are executed during the site generation and configured in the - <<<\>>> element. - - [] - - All plugins should have at least the minimal required - {{{/ref/current/maven-model/maven.html#class_plugin}information}}: - <<>>, <<>> and <<>>. - - <>: Always define the version of each plugin used to guarantee - build reproducibility. A good practice is to specify each build plugin's version in a <<<\\\>>> - element. Often the \ element is found in the parent POM. - For reporting plugins, specify each version in the <<<\\\>>> element - (and in the <<<\\\>>> element too). - -* {Generic Configuration} - - Maven plugins (build and reporting) are configured by specifying a <<<\>>> element where the child elements of the - <<<\>>> element are mapped to fields, or setters, inside your Mojo. (Remember that a plug-in consists of - one or more Mojos where a Mojo maps to a goal.) Say, for example, you have a Mojo that performs a query against - a particular URL, with a specified timeout and list of options. The Mojo might look like the following: - -+----+ -@Mojo( name = "query" ) -public class MyQueryMojo - extends AbstractMojo -{ - @Parameter(property = "query.url", required = true) - private String url; - - @Parameter(property = "timeout", required = false, defaultValue = "50") - private int timeout; - - @Parameter(property = "options") - private String[] options; - - public void execute() - throws MojoExecutionException - { - ... - } -} -+----+ - - To configure the Mojo from your POM with the desired URL, timeout and options you might have something like - the following: - -+----+ - - ... - - - - maven-myquery-plugin - 1.0 - - http://www.foobar.com/query - 10 - - - - - - - - - - ... - -+----+ - - The elements in the configuration match the names of the fields in the Mojo. - The mapping is straight forward. The - <<>> element maps to the <<>> field, the <<>> element maps to the <<>> field, and the - <<>> element maps to the <<>> field. The mapping mechanism can deal with arrays by inspecting - the type of the field and determining if a suitable mapping is possible. - - For Mojos that are intended to be executed directly from the CLI, their parameters usually provide a means to be - configured via system properties instead of a <<<\>>> section in the POM. The plugin documentation - for those parameters will list an that denotes the system properties for the configuration. In the - Mojo above, the parameter <<>> is associated with the expression <<<$\{query.url\}>>>, meaning its value can - be specified by the system property <<>> as shown below: - ------- -mvn myquery:query -Dquery.url=http://maven.apache.org ------- - - The name of the system property does not necessarily match the name of the mojo parameter. While this is - a rather common practice, you will often notice plugins that employ some prefix for the system properties to avoid - name clashes with other system properties. Though rarely, there are also plugin parameters that (e.g. for historical - reasons) employ system properties which are completely unrelated to the parameter name. So be sure to have a close - look at the plugin documentation. - -** {Help Goal} - - Most Maven plugins have a <<>> goal that prints a description - of the plugin and its parameters and types. For instance, to see help - for the javadoc goal, type: - ------- -mvn javadoc:help -Ddetail -Dgoal=javadoc ------- - - And you will see all parameters for the javadoc:javadoc goal, similar to this - {{{/plugins/maven-javadoc-plugin/javadoc-mojo.html}page}}. - -** {Configuring Parameters} - - Parameterization of Mojos relies internally on the Plexus Component Configuration API provided by {{{https://github.com/eclipse/sisu.plexus}sisu-plexus}}. - -*** {Mapping Value Objects} - - Mapping value types, like Boolean or Integer, is very simple. The <<<\>>> element might look like - the following: - -+----+ - -... - - a string - true - 10 - 1.0 - c:\temp - http://maven.apache.org - -... - -+----+ - - The detailed type coercion is explained in the table below. - For conversion to primitive types their according {{{https://docs.oracle.com/javase/tutorial/java/data/autoboxing.html}wrapper classes are used and automatically unboxed}}. - -*---------------------*--------------* -|| Parameter Class || Conversion from String -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-}<<>>}} of the first character in the given string -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-}<<>>}} for the following patterns: <<>>, <<>>, <<>> or <<>> -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-}<<>>}} with the file separators normalized to <<>>. In case the file is relative, is is made absolute by prefixing it with the project's base directory. -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | n/a -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-}<<>>}} -*---------------------*--------------* - <<>> | {{{https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-}<<>>}} -*---------------------*--------------* - -*** {Mapping Complex Objects} - - Mapping complex types is also fairly straight forward. Let's look at a simple example where we - are trying to map a configuration for Person object. The <<<\>>> element might look like the - following: - -+----+ - -... - - - Jason - van Zyl - - -... - -+----+ - - The rules for mapping complex objects are as follows: - - * There must be a private field that corresponds to name of the element being mapped. So in our case the - <<>> element must map to a <<>> field in the mojo. - - * The object instantiated must be in the same package as the Mojo itself. So if your mojo is in - <<>> then the mapping mechanism will look in that package for an - object named <<>>. The mechanism capitalizes the first letter of - the element name and uses that to search for the object to instantiate. - - * If you wish to have the object to be instantiated live in a different package or have a more - complicated name, specify this using an <<>> attribute like the - following: - - [] - -+----+ - -... - - - Jason - van Zyl - - -... - -+----+ - -*** {Mapping Collection Types} - - The configuration mapping mechanism can easily deal with most collections so let's go through a few examples - to show you how it's done: - -**** {Mapping Collections and Arrays} - - Mapping to collections works in much the same way as mapping to arrays. Each item is given in the XML - as dedicated element. The element name does not matter in that case. So if you have a mojo like the following: - -+----+ -public class MyAnimalMojo - extends AbstractMojo -{ - @Parameter(property = "animals") - private List animals; - - public void execute() - throws MojoExecutionException - { - ... - } -} -+----+ - - where you have a field named <<>> then your configuration for the plug-in would look like the following: - -+----+ - - ... - - - - maven-myanimal-plugin - 1.0 - - - cat - dog - aardvark - - - - - - ... - -+----+ - - Where each of the animals listed would be entries in the <<>> field. Unlike arrays, collections do not necessarily have - a specific component type. In order to derive the type of a collection item, the following strategy is used: - - [[1]] If the first item XML element contains an <<>> hint attribute, try to load the class with the given fully qualified class name from the attribute value - - [[2]] If the first item XML element contains a <<<.>>>, try to load the class with the fully qualified class name given in the element name - - [[3]] Try the first item XML element name (with capitalized first letter) as a class in the same package as the mojo/object being - configured - - [[4]] Use the parameter type information from either - {{{https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()}<<>>}} or - {{{https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()}<<>>}} - - [[5]] If the element has no children, assume its type is <<>>. Otherwise, the configuration will fail. - - [] - - The following collection implementations are being used when there is no <<>> hint attribute in the XML element representing the collection: - -*---------------------*--------------* -|| Collection Class || Used for -*---------------------*--------------* -<<>> | for all types assignable to <<>> -*---------------------*--------------* -<<>> | for all types assignable to <<>> -*---------------------*--------------* -<<>> | for every other <<>> type which is not a <<>> -*---------------------*--------------* - - Since Maven 3.3.9 ({{{https://issues.apache.org/jira/browse/MNG-5440}MNG-5440}}), you can list individual items alternatively as comma-separated list in the XML value of animals directly. - This approach is also used if configuring collection/array parameters via command line - The following example is equivalent to the example above: - -+----+ - - ... - - - - maven-myanimal-plugin - 1.0 - - cat,dog,aardvark - - - - - ... - -+----+ - - Each item is mapped again according to the rules of this section depending on the type of the collection/array. - - -**** {Mapping Maps} - - In the same way, you could define maps like the following: - -+-----+ -... - @Parameter - private Map myMap; -... -+-----+ - -+-----+ - -... - - - value1 - value2 - - -... - -+-----+ - - Unlike Collections the value type for Maps is always derived from the parameter type information from either - {{{https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()}<<>>}} or - {{{https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()}<<>>}}. - It falls back to <<>>. - The key type must always be <<>>. - - In contrast to value objects and collections/arrays there is no string coercion defined for maps, i.e. you cannot give parameters of that type via CLI argument. - - The map implementation class is by default <<>> but can be overridden with an <<>> attribute on the XML element representing the map. - -**** {Mapping Properties} - - Properties should be defined like the following: - -+-----+ -... - @Parameter - private Properties myProperties; -... -+-----+ - -+-----+ - -... - - - - propertyName1 - propertyValue1 - - - propertyName2 - propertyValue2 - - - -... - -+-----+ - - In contrast to value objects and collections/arrays there is no string coercion defined for properties, i.e. you cannot give parameters of those type via CLI argument. - -* {Configuring Build Plugins} - - The following is only to configure Build plugins in the <<<\>>> element. - -** {Using the <<<\>>> Tag} - - You can also configure a mojo using the <<<\>>> tag. This is most commonly used for mojos that are - intended to participate in some phases of the {{{../introduction/introduction-to-the-lifecycle.html}build lifecycle}}. - Using <<>> as an example, you may have something that will look like: - -+----+ - - ... - - - - maven-myquery-plugin - 1.0 - - - execution1 - test - - http://www.foo.com/query - 10 - - - - - - - - query - - - - execution2 - - http://www.bar.com/query - 15 - - - - - - - - query - - - - - - - ... - -+----+ - - The first execution with id "execution1" binds this configuration to the test phase. The second execution does not - have a <<<\>>> tag, how do you think will this execution behave? Well, goals can have a default phase binding - as discussed further below. If the goal has a default phase binding then it will execute in that phase. But if the - goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle. - - Note that while execution id's have to be unique among all executions of a single plugin within a POM, they don't - have to be unique across an inheritance hierarchy of POMs. Executions of the same id from different POMs are merged. - The same applies to executions that are defined by profiles. - - How about if we have a multiple executions with different phases bound to it? - How do you think will it behave? Let us use the example POM above again, but - this time we shall bind <<>> to a phase. - -+----+ - - ... - - - - ... - - - execution1 - test - ... - - - execution2 - install - - http://www.bar.com/query - 15 - - - - - - - - query - - - - - - - ... - -+----+ - - If there are multiple executions bound to different phases, then the mojo is - executed once for each phase indicated. Meaning, <<>> will be - executed applying the configuration setup when the phase of the build is test, - and <<>> will be executed applying the configuration setup when - the build phase is already in install. - - Now, let us have another mojo example which shows a default lifecycle phase binding. - -+----+ -@Mojo( name = "query", defaultPhase = LifecyclePhase.PACKAGE ) -public class MyBoundQueryMojo - extends AbstractMojo -{ - @Parameter(property = "query.url", required = true) - private String url; - - @Parameter(property = "timeout", required = false, defaultValue = "50") - private int timeout; - - @Parameter(property = "options") - private String[] options; - - public void execute() - throws MojoExecutionException - { - ... - } -} -+----+ - - From the above mojo example, <<>> is by default bound to the package phase - (see the <<<@phase>>> notation). But if we want to execute this mojo during the install - phase and not with package we can rebind this mojo into a new lifecycle phase - using the <<<\>>> tag under <<<\>>>. - -+----+ - - ... - - - - maven-myquery-plugin - 1.0 - - - execution1 - install - - http://www.bar.com/query - 15 - - - - - - - - query - - - - - - - ... - -+----+ - - Now, <<>> default phase which is package has been overridden by - install phase. - - <> Configurations inside the <<<\>>> element used to differ from those that are outside - <<<\>>> in that they could not be used from a direct command line - invocation because they were only applied when the lifecycle phase they were - bound to was invoked. So you had to move a configuration section - outside of the executions section to apply it globally to all invocations - of the plugin. - Since Maven 3.3.1 this is not the case anymore as you can specify on the command line - the execution id for direct plugin goal invocation. Hence if you want to - run the above plugin and it's specific execution1's configuration from the - command-line, you can execute: - ------- -mvn myquery:query@execution1 ------- - -** {Using the <<<\>>> Tag} - - You could configure the dependencies of the Build plugins, commonly to use a more recent dependency version. - - For instance, the Maven Antrun Plugin version 1.2 uses Ant version 1.6.5, if you want to use the latest Ant version - when running this plugin, you need to add <<<\>>> element like the following: - -+----+ - - ... - - - - org.apache.maven.plugins - maven-antrun-plugin - 1.2 - ... - - - org.apache.ant - ant - 1.7.1 - - - org.apache.ant - ant-launcher - 1.7.1 - - - - - - ... - -+----+ - -** {Using the <<<\>>> Tag In Build Plugins} - - By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use - the <<<\>>> tag: - -+----+ - - ... - - - - org.apache.maven.plugins - maven-antrun-plugin - 1.2 - false - ... - - - - ... - -+----+ - - -* {Configuring Reporting Plugins} - - The following is only to configure Reporting plugins in the <<<\>>> element. - -** {Using the <<<\>>> Tag VS <<<\>>> Tag} - - Configuring a reporting plugin in the <<<\>>> or <<<\>>> elements in the pom does not exactly have the same results. - - [<<>>] Since maven-site-plugin 3.4, it uses the parameters defined in the <<<\>>> element of each reporting Plugin - specified in the <<<\>>> element, in addition to the parameters defined in the - <<<\>>> element of each plugin specified in <<<\>>> (parameters from <<<\>>> section were previously ignored). - - [<<>>] It <> the parameters defined in the <<<\>>> element of each - reporting Plugin specified in the <<<\>>> element; only parameters - defined in the <<<\>>> element of each plugin specified in <<<\>>> are used. - - [] - -** {Using the <<<\>>> Tag} - - You can configure a reporting plugin using the <<<\>>> tag. This is most commonly used to generate - reports selectively when running <<>>. The following will generate only the project team report. - -+----+ - - ... - - - - org.apache.maven.plugins - maven-project-info-reports-plugin - 2.1.2 - - - - project-team - - - - - - - ... - -+----+ - - <>: - - [[1]] To exclude all reports, you need to use: - -+----+ - - - - - -+----+ - - [[2]] Refer to each Plugin Documentation (i.e. plugin-info.html) to know the available report goals. - - [] - -** {Using the <<<\>>> Tag In Reporting Plugins} - - Similar to the build plugins, to break the inheritance, you can use the <<<\>>> tag: - -+----+ - - ... - - - - org.apache.maven.plugins - maven-project-info-reports-plugin - 2.1.2 - false - - - - ... - -+----+ - diff --git a/content/apt/guides/mini/guide-creating-archetypes.apt b/content/apt/guides/mini/guide-creating-archetypes.apt deleted file mode 100644 index d432deab01..0000000000 --- a/content/apt/guides/mini/guide-creating-archetypes.apt +++ /dev/null @@ -1,242 +0,0 @@ - ------ - Guide to Creating Archetypes - ------ - Jason van Zyl, Alexander Hars, Franz Allan Valencia See - ------ - 2010-04-10 - ------ - -~~ 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 - -Guide to Creating Archetypes - - Creating an archetype is a pretty straight forward process. An archetype is a - very simple artifact, that contains the project prototype you wish to create. - An archetype is made up of: - - * an {{{/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html}archetype descriptor}} - (<<>> in directory: - <<>>). It lists all the files that will be - contained in the archetype and categorizes them so they can be processed - correctly by the archetype generation mechanism. - - * the prototype files that are copied by the archetype plugin (directory: - <<>>) - - * the prototype pom (<<>> in: - <<>>) - - * a pom for the archetype (<<>> in the archetype's root directory). - - [] - - - To create an archetype follow these steps: - -* 1. Create a new project and pom.xml for the archetype artifact - - An example <<>> for an archetype artifact looks as follows: - -+----+ - - - 4.0.0 - - my.groupId - my-archetype-id - 1.0-SNAPSHOT - maven-archetype - - - - - org.apache.maven.archetype - archetype-packaging - 3.1.1 - - - - - -+----+ - - All you need to specify is a <<>>, <<>> and - <<>>. These three parameters will be needed later for invoking the - archetype via <<>> from the commandline. - -* 2. Create the archetype descriptor - - The {{{/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html}archetype descriptor}} - is a file called <<>> which must be - located in the <<>> directory. An example of an archetype - descriptor can be found in the quickstart archetype: - -+----+ - - - - - src/main/java - - - src/test/java - - - - -+----+ - - The attribute <<>> tag should be the same as the <<>> in the - archetype <<>>. - - The boolean attribute <<>> show if this archetype is representing a full Maven project or only parts. - - The <<>>, <<>> and <<>> tags represent the differents parts of the project: - - * <<<\>>> : List of required properties to generate a project from this archetype - - * <<<\>>> : File sets definition - - * <<<\>>> : Modules definition - - - [] - - - At this point one can only specify individual files to be created but not empty - directories. - - Thus the quickstart archetype shown above defines the following directory - structure: - ----- - -archetype -|-- pom.xml -`-- src - `-- main - `-- resources - |-- META-INF - | `-- maven - | `--archetype-metadata.xml - `-- archetype-resources - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- App.java - `-- test - `-- java - `-- AppTest.java - ----- - -* 3. Create the prototype files and the prototype pom.xml - - The next component of the archetype to be created is the prototype - <<>>. Any <<>> will do, just don't forget to the set - <<>> and <<>> as variables ( <<<$\{artifactId\}>>> / - <<<$\{groupId\}>>> ). Both variables will be initialized from the commandline - when calling <<>>. - - An example for a prototype <<>> is: - -+----+ - - - 4.0.0 - - ${groupId} - ${artifactId} - ${version} - jar - - ${artifactId} - http://www.myorganization.org - - - - junit - junit - 4.12 - test - - - - -+----+ - -* 4. Install the archetype and run the archetype plugin - - Now you are ready to install the archetype: - ------- - -mvn install - ------- - - Now that you have created an archetype, you can try it on your local system by - using the following command. In this command, you need to specify the full - information about the archetype you want to use (its <<>>, its - <<>>, its <<>>) and the information about the new project - you want to create (<<>> and <<>>). Don't forget to - include the version of your archetype (if you don't include the version, you - archetype creation may fail with a message that version:RELEASE was not found) - - ------- - -mvn archetype:generate \ - -DarchetypeGroupId= \ - -DarchetypeArtifactId= \ - -DarchetypeVersion= \ - -DgroupId= \ - -DartifactId= - ------- - - Once you are happy with the state of your archetype, you can deploy (or submit - it to {{{/guides/mini/guide-central-repository-upload.html}Maven Central}}) - it as any other artifact and the archetype will then be - available to any user of Maven. - -* Alternative way to start creating your Archetype - - Instead of manually creating the directory structure needed for an archetype, - simply use - --------- -mvn archetype:generate - -DgroupId=[your project's group id] - -DartifactId=[your project's artifact id] - -DarchetypeGroupId=org.apache.maven.archetypes - -DarchetypeArtifactId=maven-archetype-archetype --------- - - Afterwhich, you can now customize the contents of the <<>> - directory, and <<>>, then, proceed to Step#4 (Install the archetype and run - the archetype plugin). diff --git a/content/apt/guides/mini/guide-default-execution-ids.apt b/content/apt/guides/mini/guide-default-execution-ids.apt deleted file mode 100644 index 3ee8ae1b9d..0000000000 --- a/content/apt/guides/mini/guide-default-execution-ids.apt +++ /dev/null @@ -1,218 +0,0 @@ - --- - Guide to Configuring Default Mojo Executions - --- - John Casey - --- - 2009-06-10 - --- - -~~ 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 - -Guide to Configuring Default Mojo Executions - - In most cases where you need to configure a plugin, there are two options that work well: plugin-level configuration and execution-level configuration. - Plugin-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default - lifecycle, or that use a common configuration across all invocations. In fact, for direct invocation from the command line, plugin-level configuration - has been the option historically. - - On the other hand, in cases where a more advanced build process requires the execution of mojos - sometimes the same mojos, sometimes different ones - - from a single plugin that use different configurations, the execution-level configuration is most commonly used. These cases normally involve plugins - that are introduced as part of the standard build process, but which aren't present in the default lifecycle mapping for that particular packaging. In - these cases, common settings shared between executions are still normally specified in the plugin-level configuration. - - However, these two options leave out a few important configuration use cases: - - * Mojos run from the command line during the build, when the CLI-driven invocation requires its own configuration. - - * Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases - where the same mojos need to be added to a second execution with different configuration. - - * Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but - require separate configurations. - - [] - -*Default <<>>s for Implied Executions - - When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable - to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've - implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Each - mojo invoked directly from the command line will have an execution Id of <<>> assigned to it, which will allow the configuration - of that execution from the POM by using this default execution Id. Likewise, each mojo bound to the build lifecycle via the default lifecycle - mapping for the specified POM packaging will have an execution Id of <<>>> assigned to it, to allow configuration of each - default mojo execution independently. - -**Example: Command-line variant invocation of the assembly plugin - - Consider the case where the user wants to execute the <<>> mojo directly on the command line, but already - has a configuration for the <<>> mojo that runs during the main build lifecycle. Since these configurations require different - options, the user cannot use the plugin-level configuration section to specify common elements. - - In this case, the assembly-plugin configuration might look like this: - -+---+ - - maven-assembly-plugin - - gnu - - - - build-distros - package - - single - - - - src/main/assembly/bin.xml - src/main/assembly/src.xml - - - - - default-cli - - - jar-with-dependencies - project - - - - - -+---+ - - In the above example, you can see several interesting things. First, the main build process will invoke the <<>> mojo during - the <<>> phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with - the project. Second, all invocations of the assembly plugin should use a <<>> strategy of <<>>. Finally, when the assembly - plugin is invoked from the command line, it will build the standard <<>> and <<>> artifacts for the project, - and ignore the custom assembly descriptors in <<>>. - - Now, notice the difference in the way the two execution blocks reference assembly descriptors. One uses custom descriptors via the <<>> - section, and the other uses standard descriptors via the <<>> section. These two sections cannot override one another, so it's - impossible to setup one section - say, <<>> - in the plugin-level configuration block (to provide CLI access to it, as historical - versions of Maven would require), then have the <<>> invocation override it with the custom descriptors specified in the - <<>> section. - -**Example: Configuring <<>> to run twice - - In this scenario, the user wants to run the <<>> mojo twice for his <<>> packaging project. The main reason for this - is to provide an entry point into the application that will warn the user if he's using a Java version older than 1.5, then exit gracefully. - Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1.4 or older - JRE. - - Therefore, the user needs to compile the bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point) - to target an older specification...say, 1.3. The first execution will specify the <<>> and <<>> values at <<<1.5>>>, - and add an <<>> section to avoid compiling the entry point for the application. The second pass will then re-specify <<>> - and <<>> to <<<1.3>>>, and basically invert the original <<>> section to be an <<>> section, so as to compile - the entry point class. - - The resulting configuration might look something like this: - -+---+ - - maven-compiler-plugin - - 1.5 - 1.5 - - - - default-compile - - - **/cli/* - - - - - build-java14-cli - compile - - compile - - - 1.3 - 1.3 - - **/cli/* - - - - - -+---+ - - There are three important things to notice in the above compiler-plugin configuration: - - * The default <<>> and <<>> compatibility levels are for Java 1.5. This means that the compiler will generate binaries - for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden. - - * The default pass of the <<>> goal will the <<<**/cli/*>>> path pattern, but will compile everything else in - <<>> to run under Java 1.5. - - * The second pass of the <<>> mojo - in the execution called <<>> - resets the <<>> and <<>> - versions to <<<1.3>>>, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce - 1.4-targeted binaries for the classes matching the <<<**/cli/*>>> path pattern. - - [] - -**Example: Configuring <<>> and <<>> mojos separately - - Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target - version 1.4 of the Java specification as his runtime platform. However, he still wants the convenience and other advantages to be found in - a unit-testing framework like TestNG. This forces the user to configure the <<>> mojo with one set of <<>> and <<>> - values - specifically, <<<1.4>>> - and the <<>> mojo with another (<<<1.5>>>). - - The resulting compiler-plugin configuration might look something like the following: - -+---+ - - maven-compiler-plugin - - - default-compile - - 1.3 - 1.3 - - - - default-testCompile - - 1.5 - 1.5 - - - - -+---+ - - This example is fairly simple and straightforward. First, the <<>> execution sets the <<>> and <<>> values to <<<1.3>>> - to allow older Java versions to run the project. Then, the <<>> execution resets the <<>> and <<>> values to - <<<1.5>>>, which enables the project to use tools like TestNG that use annotations. - - Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1.3 by default, so - the only configuration that's really required is the <<>> execution. The <<>> execution respecifies plugin - defaults. The only time this might be useful is when a parent POM defines a plugin-level configuration for <<>> and <<>> that needs - to be changed for the purposes of these different compiler executions. This example is meant to be illustrative of the potential for separate configuration - of default lifecycle mojos. diff --git a/content/apt/guides/mini/guide-deployment-security-settings.apt b/content/apt/guides/mini/guide-deployment-security-settings.apt deleted file mode 100644 index d05839c11e..0000000000 --- a/content/apt/guides/mini/guide-deployment-security-settings.apt +++ /dev/null @@ -1,66 +0,0 @@ - ------ - Guide to Deployment and Security Settings - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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 - -Security and Deployment Settings - - Repositories to deploy to are defined in a project in the <<>> section. However, you cannot put - your username, password, or other security settings in that project. For that reason, you should add a server - definition to your own settings with an id that matches that of the deployment repository in the project. - - In addition, some repositories may require authorisation to download from, so the corresponding settings can be - specified in a server element in the same way. - - Which settings are required will depend on the type of repository you are deploying to. As of the first release, - only SCP deployments and file deployments are supported by default, so only the following SCP - configuration is needed: - -+-----+ - - - . - . - - - repo1 - repouser - - - - . - . - - -+-----+ - - To encrypt passwords in these sections, refer to {{{./guide-encryption.html} Encryption Settings}}. - - <>: The settings descriptor documentation can be found on the {{{../../maven-settings/settings.html}Maven Local Settings Model Website}}. diff --git a/content/apt/guides/mini/guide-encryption.apt b/content/apt/guides/mini/guide-encryption.apt deleted file mode 100644 index 3b655fc96f..0000000000 --- a/content/apt/guides/mini/guide-encryption.apt +++ /dev/null @@ -1,258 +0,0 @@ - ---- - Password Encryption - ----- - Oleg Gusakov - Robert Scholte - ----- - 2014-03-23 - ------ - -~~ 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 - -{Password Encryption} - - [[1]] {{{Introduction}Introduction}} - - [[2]] {{{How_to_create_a_master_password}How to create a master password}} - - [[3]] {{{How_to_encrypt_server_passwords}How to encrypt server passwords}} - - [[4]] {{{How_to_keep_the_master_password_on_removable_drive}How to keep the master password on removable drive}} - - [[5]] {{{Tips}Tips}} - - -* {Introduction} - - Maven supports server password encryption. The main use case, addressed by this solution is: - - * multiple users share the same build machine (server, CI box) - - * some users have the privilege to deploy Maven artifacts to repositories, some don't. - - ** this applies to any server operations, requiring authorization, not only deployment - - * <<>> is shared between users - - The implemented solution adds the following capabilities: - - * authorized users have an additional <<>> file in their <<<$\{user.home\}/.m2>>> directory - - ** this file either contains encrypted <>, used to encrypt other passwords - - ** or it can contain a <> - reference to another file, possibly on removable storage - - ** this password is created first via CLI for now - - * server entries in the <<>> have passwords and/or keystore passphrases encrypted - - ** for now - this is done via CLI <> master password has been created and stored in appropriate location - -* {How to create a master password} - - Use the following command line: - --------------------------------------- -mvn --encrypt-master-password --------------------------------------- - - Since Maven 3.2.1 the password argument should no longer be used (see {{{Tips}Tips}} below for more information). Maven will prompt for the password. Earlier versions of Maven will not prompt for a password, so it must be typed on the command-line in plaintext. - - This command will produce an encrypted version of the password, something like - ------------------------------------- -{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} ------------------------------------- - - Store this password in the <<<$\{user.home\}/.m2/settings-security.xml>>>; it should look like - -+------------------------------------+ - - {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} - -+------------------------------------+ - - When this is done, you can start encrypting existing server passwords. - -* {How to encrypt server passwords} - - You have to use the following command line: - --------------------------------------- -mvn --encrypt-password --------------------------------------- - - Just like <<<--encrypt-master-password>>> the password argument should no longer be used since Maven 3.2.1 (see {{{Tips}Tips below for more information.}}). - - This command produces an encrypted version of it, something like - ------------------------------------- -{COQLCE6DU6GtcS5P=} ------------------------------------- - - Copy and paste it into the servers section of your <<>> file. This will look like: - -+------------------------------------+ - -... - -... - - my.server - foo - {COQLCE6DU6GtcS5P=} - -... - -... - -+------------------------------------+ - - Please note that password can contain any information outside of the curly brackets, so that the following will still work: - -+------------------------------------+ - -... - -... - - my.server - foo - Oleg reset this password on 2009-03-11, expires on 2009-04-11 {COQLCE6DU6GtcS5P=} - -... - -... - -+------------------------------------+ - - Then you can use, say, deploy plugin, to write to this server: - --------------------------------------- -mvn deploy:deploy-file -Durl=https://maven.corp.com/repo \ - -DrepositoryId=my.server \ - -Dfile=your-artifact-1.0.jar \ --------------------------------------- - - - -* {How to keep the master password on removable drive} - - Create the master password exactly as described above, and store it on a - removable drive, for instance on OSX, my USB drive mounts as <<>>, - so I store - -+------------------------------------+ - - {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} - -+------------------------------------+ - - in the file <<>> - - And then I create <<<$\{user.home\}/.m2/settings-security.xml>>> with the following content: - -+------------------------------------+ - - /Volumes/mySecureUsb/secure/settings-security.xml - -+------------------------------------+ - - This assures that encryption only works when the USB drive is mounted by the OS. - This addresses a use case where only certain people are authorized to deploy and - are issued these devices. - -* {Tips} - -** Escaping curly-brace literals in your password <(Since: Maven 2.2.0)> - - At times, you might find that your password (or the encrypted form of it) - contains '\{' or '\}' as a literal value. If you added such a password as-is - to your settings.xml file, you would find that Maven does strange things with it. - Specifically, Maven treats all the characters preceding the '\{' literal, and - all the characters after the '\}' literal, as comments. Obviously, this is not the - behavior you want. What you really need is a way of <> - the curly-brace literals in your password. - - You can do this with the widely used '\' escape character. - If your password looks like this: - ------ -jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+{EF1iFQyJQ= ------ - - Then, the value you would add to your settings.xml looks like this: - ------ -{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+\{EF1iFQyJQ=} ------ - -** Password Security - - Editing <<>> and running the above commands can still leave your password stored - locally in plaintext. You may want to check the following locations: - - * Shell history (e.g. by running <<>>). You may want to clear your history after - encrypting the above passwords - - * Editor caches (e.g. <<<~/.viminfo>>>) - - Also note that the encrypted passwords can be decrypted by someone that has the master password - and settings security file. Keep this file secure (or stored separately) if you expect the - possibility that the <<>> file may be retrieved. - -** Password Escaping on different platforms - - On some platforms it might be necessary to quote the password if it contains - special characters like <<<%>>>, <<>>, <<<$>>>, etc. - For example on Windows you have to be careful about things like the following: - - The following example will not work on Windows: - ------- -mvn --encrypt-master-password a!$%^b ------- - - whereas the following will work on Windows: - ------- -mvn --encrypt-master-password "a!$%^b" ------- - - If you are on a linux/unix platform you should use single quotes for the above - master password. Otherwise the master password - will not work (caused by the dollar sign and the exclamation mark). - -** Prompting for Password - - In Maven before version 3.2.1 you have to give the password on the command line as - an argument which means you might need to escape your password. In addition - usually the shell stores the full history of commands you have entered, - therefore anyone with access to your computer could restore the password from - the shell`s history. - - Starting with Maven 3.2.1, the password is an optional argument. If - you omit the password, you will be prompted for it which prevents all the issues - mentioned above. - - We strongly recommend using Maven 3.2.1 and above to prevent - problems with escaping special characters and of course security issues related - to bash history or environment issues in relationship with the password. diff --git a/content/apt/guides/mini/guide-generating-sources.apt b/content/apt/guides/mini/guide-generating-sources.apt deleted file mode 100644 index f98d53192f..0000000000 --- a/content/apt/guides/mini/guide-generating-sources.apt +++ /dev/null @@ -1,74 +0,0 @@ - ------ - Guide to generating Sources - ------ - Jason van Zyl - Karl Heinz Marbaise - ------ - 2005-10-12 - 2016-06-11 - ------ - -~~ 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 - -Guide to generating sources - - Let's run though a short example. To generate sources you must first have a plugin that - participates in the <<>> phase - like the {{{https://www.antlr.org/api/maven-plugin/latest/}ANTLR4 Maven Plugin}}. - You configure its execution in the POM: - -+----+ - - - ... - - - - org.antlr - antlr4-maven-plugin - 4.5.3 - - - antlr - - antlr4 - - - - - - - ... - - -+----+ - - When you type <<>>, Maven walks through the - {{{../introduction/introduction-to-the-lifecycle.html}lifecycle}} - and eventually hits the <<>> phase. It sees that a plugin is configured that - wants to participate in that phase, and executes the ANTLR4 Maven Plugin with - the given configuration. Later, during the compile phase, - all the code generated from the grammar files is compiled - without further configuration. - - - [] - diff --git a/content/apt/guides/mini/guide-http-settings.apt b/content/apt/guides/mini/guide-http-settings.apt deleted file mode 100644 index 64d352c2cd..0000000000 --- a/content/apt/guides/mini/guide-http-settings.apt +++ /dev/null @@ -1,467 +0,0 @@ - ------ - Guide to Advanced Wagon Transport Configuration - ------ - John Casey - ------ - 2011-12-12 - ------ - -~~ 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 - -Advanced configuration to HttpClient HTTP Wagon - - <> - -%{toc} - - You can use the default wagon implementation for a given - protocol, or you can select an alternative wagon <<>> on a per-protocol basis. - For more information, see the {{{./guide-wagon-providers.html}Guide to Wagon Providers}} \[3\]. - The default wagon http(s) is the HttpClient based on {{{https://hc.apache.org/httpcomponents-client-4.5.x/}Apache Http Client 4.5}}. - HTTP connection pooling prevents reopening new connections to the same server for each request. - This pool feature is configurable with some parameters \[4\]. - The default wagon comes with some default configuration: - - * http(s) connection pool: default to 20. - - * readTimeout: default to 1800000 (~30 minutes) (see section <<>> below) - - * default Preemptive Authentication only with PUT (GET doesn't use anymore default Preemptive Authentication) - -*Introduction - - The HttpClient-based HTTP wagon offers more control over the - configuration used to access HTTP-based Maven repositories. For starters, you have fine-grained control over what HTTP headers - are used when resolving artifacts. In addition, you can also configure a wide range of parameters to control the behavior - of HttpClient itself. Best of all, you have the ability to control these headers and parameters for all requests, or individual - request types (GET, HEAD, and PUT). - -*The Basics - - Without any special configuration, Maven's HTTP wagon uses some default HTTP headers and client parameters when managing - artifacts. The default headers are: - ------ -Cache-control: no-cache -Cache-store: no-store -Pragma: no-cache -Expires: 0 -Accept-Encoding: gzip ------ - - In addition, PUT requests made with the HTTP wagon use the following HttpClient parameter: - ------ -http.protocol.expect-continue=true ------ - - From the HttpClient documentation\[2\], this parameter provides the following functionality: - ------ -Activates 'Expect: 100-Continue' handshake for the entity enclosing methods. -The 'Expect: 100-Continue' handshake allows a client that is sending a request -message with a request body to determine if the origin server is willing to -accept the request (based on the request headers) before the client sends the -request body. - -The use of the 'Expect: 100-continue' handshake can result in noticeable performance -improvement for entity enclosing requests (such as POST and PUT) that require -the target server's authentication. - -'Expect: 100-continue' handshake should be used with caution, as it may cause -problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. ------ - - Without this setting, PUT requests that require authentication transfer their entire payload to the server before that server - issues an authentication challenge. In order to complete the PUT request, the client must then re-send the payload with the proper - credentials specified in the HTTP headers. This results in twice the bandwidth usage, and twice the time to transfer each artifact. - - Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication - headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event - you have an unused <<<\>>> entry that specifies an invalid username/password combination, some servers may respond with - a <<<401 Unauthorized>>> even if the server doesn't actually require any authentication for the request. In addition, blindly sending - authentication credentials with every request regardless of whether the server has made a challenge can result in a security hole, - since the server may not make provisions to secure credentials for paths that don't require authentication. - - We'll discuss preemptive authentication in another example, below. - -*Configuring GET, HEAD, PUT, or All of the Above - - <> - - In all of the examples below, it's important to understand that you can configure the HTTP settings for all requests made to a given - server, or for only one method. To configure all methods for a server, use the following section of the <<>> file: - -+---+ - - [...] - - - the-server - - - - [ Your configuration here. ] - - - - - - -+---+ - - On the other hand, if you can live with the default configuration for most requests — say, HEAD and GET requests, which are used to - check for the existence of a file and retrieve a file respectively — maybe you only need to configure the PUT method: - -+---+ - - [...] - - - the-server - - - - [ Your configuration here. ] - - - - - - -+---+ - - For clarity, the other two sections are <<<\>>> for GET requests, and <<<\>>> for HEAD requests. I know that's going to - be hard to remember... - -*Taking Control of Your HTTP Headers - - As you may have noticed above, the default HTTP headers do have the potential to cause problems. For instance, some websites - set the encoding for downloading GZipped files as <<>>, in spite of the fact that the HTTP request itself isn't being - sent using GZip compression. If the client is using the <<>> header, this can result in the client itself - decompressing the GZipped file and writing the decompressed file to the local disk with the original filename. - This can be misleading to say the least, and can use up an inordinate amount of disk space on the local computer. - - To turn off this default behavior, simply disable the default headers. Then, respecify the other headers - that you are still interested in, like this: - -+---+ - - [...] - - - openssl - - - - false - - - Cache-control - no-cache - - - Cache-store - no-store - - - Pragma - no-cache - - - Expires - 0 - - - Accept-Encoding - * - - - - - - - [...] - - [...] - -+---+ - -*Fine-Tuning HttpClient Parameters - - Going beyond the power of HTTP request parameters, HttpClient provides a host of other configuration options. In most cases, - you won't need to customize these. But in case you do, Maven provides access to specify your own fine-grained configuration - for HttpClient. Again, you can specify these parameter customizations per-method (HEAD, GET, or PUT), or for all methods of - interacting with a given server. For a complete list of supported parameters, see the link\[2\] in Resources section below. - -**Non-String Parameter Values - - Many of the configuration parameters for HttpClient have simple string values; however, there are important exceptions to - this. In some cases, you may need to specify boolean, integer, or long values. In others, you may even need to specify - a collection of string values. You can specify these using a simple formatting syntax, as follows: - - [[1]] <> <<<%b,\>>> - - [[2]] <> <<<%i,\>>> - - [[3]] <> <<<%l,\>>> (yes, that's an 'L', not a '1') - - [[4]] <> <<<%d,\>>> - - [[5]] <> <<<%c,\,\,\,...>>>, which could also be specified as: - ------ -%c, -, -, -, -... ------ - - [] - - As you may have noticed, this syntax is similar to the format-and-data strategy used by functions like <<>> - in many languages. The syntax has been chosen with this similarity in mind, to make it a little more intuitive to use. - -***Example: Using Preemptive Authentication - - Using the above syntax, you can configure preemptive authentication for PUT requests using the boolean HttpClient parameter - <<>>, like this: - -+---+ - - - - my-server - - - - - - http.authentication.preemptive - %b,true - - - - - - - - -+---+ - - Another option is to make write it like this: - -+---+ - - - - my-server - - - - true - - - - - - -+---+ - -**Example: Lifting auth scope restriction for external authentication systems - - Maven Wagon by default limits supplied credentials to the host:port combination - scope, ignoring any other target servers. When the target server delegates - authentication to an external system, you need to deliberately lift that scope - limitation. Configure your server element to pass authentication to all target - servers which challenge the client. -+---+ - - - - my-server - - - ANY - ANY - - - - - - http.protocol.cookie-policy - standard - - - - - - - - -+---+ - -**Ignoring Cookies - - Like the example above, telling the HttpClient to ignore cookies for all methods of request is a simple matter of - configuring the <<>> parameter (it uses a regular string value, so no special syntax - is required): - -+---+ - - - - my-server - - - - - - http.protocol.cookie-policy - ignore - - - - - - - - -+---+ - - The configuration above can be useful in cases where the repository is using cookies - like the session cookies - that are often mistakenly turned on or left on in appservers - alongside HTTP redirection. In these cases, it - becomes far more likely that the cookie issued by the appserver uses a <<>> that is inconsistent with - the one used by the client to access the server. If you have this problem, and know that you don't need to use - this session cookie, you can ignore cookies from this server with the above configuration. - -*Support for General-Wagon Configuration Standards - - It should be noted that configuration options previously available in the HttpClient-driven HTTP wagon are still - supported in addition to this new, fine-grained approach. These include the configuration of HTTP headers - and connection timeouts. Let's examine each of these briefly: - -**HTTP Headers - - In all HTTP Wagon implementations, you can add your own HTTP headers like this: - -+---+ - - - - my-server - - - - Foo - Bar - - - - - - -+---+ - - It's important to understand that the above approach doesn't allow you to turn off all of the default HTTP headers; nor - does it allow you to specify headers on a per-method basis. However, this configuration remains available in both the - lightweight and httpclient-based Wagon implementations. - -**Connection Timeouts - - All wagon implementations that extend the <<>> class, including those for SCP, HTTP, FTP, and more, - allow the configuration of a connection timeout, to allow the user to tell Maven how long to wait before giving - up on a connection that has not responded. This option is preserved in the HttpClient-based wagon, but this wagon - also provides a fine-grained alternative configuration that can allow you to specify timeouts per-method for a - given server. The old configuration option - which is still supported - looks like this: - -+---+ - - - - my-server - - 6000 - - - - -+---+ - - ...while the new configuration option looks more like this: - -+---+ - - - - my-server - - - - 10000 - - - - - - -+---+ - - If all you need is a per-server timeout configuration, you still have the option to use the old <<<\>>> - parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that - specified directly above. - -** Read time out - - The default timeout is 30 minutes. - If you want to change this value, you can add the following setup in your settings: - -+---+ - - - - my-server - - - - 120000 - - - - - - -+---+ - -*Resources - - [[1]] {{{https://hc.apache.org/httpcomponents-client-4.5.x/}HttpClient website}} - - [[2]] {{{https://hc.apache.org/httpclient-3.x/preference-api.html}HttpClient preference architecture and configuration guide}} - - [[3]] {{{./guide-wagon-providers.html}Guide to Wagon Providers}} - - [[4]] {{{/wagon/wagon-providers/wagon-http/}Wagon Http}} - - [] diff --git a/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt b/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt deleted file mode 100644 index 6d82915c98..0000000000 --- a/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt +++ /dev/null @@ -1,243 +0,0 @@ - ------ - Guide to Large Scale Centralized Deployments - ------ - Phil Clay - ------ - 2021-01-01 - ------ - -~~ 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 - -Guide to Large Scale Centralized Deployments - - This guide covers a simple optimized approach to using a - {{{../../repository-management.html}repository manager}} - in a large organization with hundreds/thousands of Maven projects. - - The pillars of this approach are: - - [[1]] Use a centralized {{{../../repository-management.html}repository manager}}. - - * Maven clients should download needed artifacts from the repository manager. - - * Maven clients should upload proprietary artifacts to the repository manager. - - [[2]] Configure the location to download/upload artifacts in Maven <<>> files, - rather than in <<>> files. - - [[3]] Centrally manage the <<>> files, and distribute them via automation. - - -* {Repository Manager Layout} - - Repository managers generally have at least three types of repositories: - - [hosted] contains artifacts uploaded to the repository manager - - [proxy] proxies a remote repository and caches artifacts - - [virtual] aggregates several repositories into one - - - The simplest way to organize repositories within a repository manager is - to have a single virtual repository that aggregates: - - * a proxy repository for each public repository to mirror. (For example: Maven Central) - - * a hosted repository for releases - - * a hosted repository for snapshots - - * a hosted repository that can contain both releases and snapshots - (Only needed if some projects are still using Maven Deploy Plugin \< 2.8. - See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.) - - Separate hosted repositories are generally used for releases and snapshots - due to the need for different artifact retention policies. - - The following sections describe how to configure Maven clients to: - - * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository. - - * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the hosted repositories. - -* {Managing Downloads from the Repository Manager} - - All artifacts used by Maven projects in the organization should be downloaded - from the single virtual repository of the repository manager. - - Maven can be instructed to download artifacts from the repository manager's virtual repository - by defining a mirror in the Maven <<>> file as described in the - {{{./guide-mirror-settings.html}Guide to Mirror Settings}}. - - Example: To download artifacts from the corporate repository manager's <<>> repository: - -+-----+ - - ... - - - - corp-repository-manager - Corporate Repository Manager - external:* - https://corp-repository-manager-host/maven-virtual - - - ... - -+-----+ - -* {Managing Uploads to the Repository Manager} - - All proprietary artifacts produced by Maven projects in the organization should be uploaded - to the repository manager's hosted repositories. - - The {{{../../plugins/maven-deploy-plugin}Maven Deploy Plugin}} can be instructed to upload artifacts - to the repository manager's repositories by defining the <<>> properties - in the Maven <<>> file. - When these properties are defined, the Maven Deploy Plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}} - goal uses them instead of the <<<\>>> section of <<>> files - to determine where to upload artifacts. - - Defining the upload destination of artifacts in <<>> files rather than - in the <<<\>>> section of <<>> files allows the destinations - to be centrally managed, which simplifies maintenance if the destinations need to change. - In other words, rather than changing a huge number of <<>> files, - you just need to change {{{Settings_File_Locations}relatively few}} - <<>> files if/when the distribution locations need to change. - - The ability to specify separate alternate deployment repositories for releases and snapshots - via the <<>> and <<>> properties, - respectively, was added in Maven Deploy Plugin 2.8. - To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin \>=2.8. - If some projects are still using an older version of Maven Deploy Plugin (\>=2.3 and \<2.8), then - specify a single alternate deployment repository via the <<>> property - that points to a repository capable of containing both releases and snapshots. - - Typically, only continuous integration servers are allowed to upload artifacts to the repository manager. - Therefore, these settings should only be specified in <<>> files on continuous integration servers, - and should not be in <<>> files on developer machines. - Alternatively, if you want developers to be able to upload artifacts to the repository manager, - then include these properties in the <<>> files used by developers. - - Example: To upload artifacts to one of the corporate repository manager's hosted repositories: - -+-----+ - - ... - - - - corp-repository-manager - - - - corp::default::https://corp-repository-manager-host/maven-snapshots - - - corp::default::https://corp-repository-manager-host/maven-releases - - - corp::default::https://corp-repository-manager-host/maven-combined - - - - - corp - - https://ignored - - true - never - - - true - always - - - - - - - corp - - https://ignored - - true - never - - - true - always - - - - - - - - corp-repository-manager - - ... - -+-----+ - - -* {Settings File Locations} - - Maven <<>> files need to be available wherever Maven builds are performed, typically: - - * on continuous integration servers, and - - * on developer machines - - Both locations should have the mirror settings mentioned in - {{{Managing_Downloads_from_the_Repository_Manager}Managing Downloads from the Repository Manager}}. - - Typically, only continuous integration servers should have the deployment repository settings - mentioned in {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}}, - because only continuous integration servers should be allowed to upload to the repository manager. - Alternatively, if you want developers to be able to upload artifacts to the repository manager, - then include the deployment repository properties in the <<>> files used by developers. - - How the <<>> files are stored and updated is beyond the scope of this document. - The general recommendation is to manage a few <<>> files centrally, - and then use automation to distribute them to continuous integration servers and developer machines. diff --git a/content/apt/guides/mini/guide-manifest.apt b/content/apt/guides/mini/guide-manifest.apt deleted file mode 100644 index 1f977c1a4b..0000000000 --- a/content/apt/guides/mini/guide-manifest.apt +++ /dev/null @@ -1,44 +0,0 @@ - ------ - Guide to Working with Manifests - ------ - Jason van Zyl - Dennis Lundberg - ------ - 2010-08-19 - ------ - -~~ 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 - -Guide to Working with Manifests - - In order to modify the manifest of the archive produced by the packaging - plug-ins you need to create a configuration for it. The definitive guide for - this is {{{/shared/maven-archiver/index.html}the site for the Maven Archiver shared component}}. - This component is used by all our packaging plugins. - - -~~ suggestion by jorg -~~ it would be nice if the Specification-Version could be easily generated to be major.minor of pom.currentVersion i.e. that -~~ -~~ 1.2 ==> 1.2 -~~ 1.2.1 ==> 1.2 -~~ 1.2-SNAPSHOT ==> 1.2 -~~ for the javaapp-plugin I did something like this in Jelly ... diff --git a/content/apt/guides/mini/guide-maven-classloading.apt b/content/apt/guides/mini/guide-maven-classloading.apt deleted file mode 100644 index 9a5cf871d1..0000000000 --- a/content/apt/guides/mini/guide-maven-classloading.apt +++ /dev/null @@ -1,154 +0,0 @@ - ------ - Guide to Maven Classloading - ------ - Jason van Zyl - Anders Kristian Andersen - Konrad Windszus - ------ - 2022-11-16 - ------ - -~~ 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 - -Guide to Maven Classloading - - This is a description of the classloader hierarchy in Maven. - -%{toc|section=1|fromDepth=2} - -* Overview - - Maven uses the {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}} classloading framework to - create the classloader graph. If you look in your <<<$\{maven.home\}/boot>>> directory, you will see a single JAR - which is the Classworlds JAR we use to boot the classloader graph. The Classworlds JAR is the only element of - the Java <<>>. The other classloaders are built by Classworlds ("realms" in Classworlds terminology). - - Each realm exposes - - [[1]] optionally some classes imported from 0..n other classloaders - - [[2]] optionally some classes from a directory or JAR - - [[3]] one parent classloader - - [] - - The search order is always as given above. - -* {Platform Classloader} - - This is the classloader exposing all JRE classes. - -* {System Classloader} - - It contains only Plexus Classworlds and imports the platform classloader. - -* {Core Classloader} - - The second classloader down the graph contains the core requirements of Maven. <>. - The core classloader has the libraries in <<<$\{maven.home\}/lib>>>. In general these are just Maven libraries. For example instances of - <<<{{{/ref/current/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>> - belong to this classloader. - - You can add elements to this classloader by the means outlined in {{{./guide-using-extensions.html}Core Extension}}. - These are loaded through the same classloader as <<<$\{maven.home\}/lib>>> and hence are available - to the Maven core and all plugins for the current project (through the API Classloader, see next paragraph). - More information is available in {{{./guide-using-extensions.html}Core Extension}}. - -* {API Classloader} - - The API classloader is a filtered view of the Core Classloader, done by exposing only the exported packages from all Core Extensions. - The main API is listed in {{{/ref/current/maven-core/core-extensions.html}Maven Core Extensions Reference}}. - - This has been introduced with Maven 3.3.1 ({{{https://issues.apache.org/jira/browse/MNG-5771}MNG-5771}}). - -* {Build Extension Classloaders} - -[../../buildExtensionClassRealm.svg] Build Extension Class Realm - - For every plugin which is marked with <<<\true\>>> and every {{{/ref/current/maven-model/maven.html#class_extension}build extension}} listed in the according section of the POM, there is - a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. - It imports everything from the API classloader. - All JSR 330 or Plexus components declared in the underlying JAR are registered in the global Plexus container - while creating the classloader. - In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container. - Build extensions have limited effect as they are loaded late. - -* {Project Classloaders} - - There is one project classloader per Maven project (identified through its coordinates). - This one imports the API Classloader. In addition it exposes all classes from all Build Extension Classloaders which are bound to the current project. - This is only released with the container. - During the build outside Mojo executions, the thread's context classloader is set to the project classloader. - -* {Plugin Classloaders} - -[../../pluginClassRealm.svg] Plugin Class Realm - - Each plugin (which is not marked as build extension) has its own classloader that imports the Project classloader. - - Plugins marked with <<<\true\>>> leverage the Build Extension classloader instead of the Plugin classloader. - - Users can add dependencies to this classloader by adding dependencies - to a plugin in the <<<{{{/ref/current/maven-model/maven.html#class_plugin}plugins/plugin}}>>> - section of their project <<>>. - Here is a sample of adding <<>> to the plugin classloader of the Antrun Plugin and hereby enabling the use - of additional/optional Ant tasks: - -+---+ - - org.apache.maven.plugins - maven-antrun-plugin - 1.3 - - - org.apache.ant - ant-nodeps - 1.7.1 - - - ... - -+---+ - - Plugins can inspect their effective runtime class path via the expressions <<<$\{plugin.artifacts\}>>> or - <<<$\{plugin.artifactMap\}>>> to have a list or map, respectively, of resolved artifacts injected from the - <<<{{{/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html}PluginDescriptor}}>>>. - - Please note that the plugin classloader does neither contain the - {{{/ref/current/maven-model/maven.html#class_dependency}dependencies}} - of the current project nor its build output. Instead, plugins can query the project's compile, runtime and test class path from the - <<<{{{/ref/current/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>> - in combination with the mojo annotation <<>> from the - {{{/developers/mojo-api-specification.html}Mojo API Specification}}. For instance, flagging a - mojo with <<<@requiresDependencyResolution runtime>>> enables it to query the runtime class path of the current project - from which it could create further classloaders. - - When a build plugin is executed, the thread's context classloader is set to the plugin classloader. - - -* {Custom Classloaders} - - Plugins are free to create further classloaders. For example, a plugin might want to create a - classloader that combines the plugin class path and the project class path. - - It is important to understand that the plugin classloader cannot load classes from any of those custom classloaders. - Some factory patterns require that. Here you must add the classes to the plugin classloader as shown before. diff --git a/content/apt/guides/mini/guide-mirror-settings.apt b/content/apt/guides/mini/guide-mirror-settings.apt deleted file mode 100644 index afce1fd5c4..0000000000 --- a/content/apt/guides/mini/guide-mirror-settings.apt +++ /dev/null @@ -1,178 +0,0 @@ - ------ - Guide to Mirror Settings - ------ - Jason van Zyl - Brian Fox - Robert Scholte - ------ - 2015-01-02 - ------ - -~~ 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 Mirrors for Repositories - - With {{{/guides/introduction/introduction-to-repositories.html}Repositories}} you specify from - which locations you want to certain artifacts, such as dependencies and maven-plugins. - Repositories can be {{{../mini/guide-multiple-repositories.html}declared inside a project}}, which means that if you have your own custom repositories, those sharing - your project easily get the right settings out of the box. However, you may want to use an alternative mirror - for a particular repository without changing the project files. - - Some reasons to use a mirror are: - - * There is a synchronized mirror on the internet that is geographically closer and faster - - * You want to replace a particular repository with your own internal repository which you have greater control over - - * You want to run a {{{../../repository-management.html}repository manager}} to provide a local cache to a mirror and need to use its URL instead - - [] - - To configure a mirror of a given repository, you provide it in your settings file (<<<$\{user.home\}/.m2/settings.xml>>>), - giving the new repository its - own <<>> and <<>>, and specify the <<>> setting that is the ID of the repository you are using a - mirror of. For example, the ID of the main Maven Central repository included by default is <<>>, so to use - the different mirror instance, you would configure the following: - -+-----+ - - ... - - - other-mirror - Other Mirror Repository - https://other-mirror.repo.other-company.com/maven2 - central - - - ... - -+-----+ - - Note that there can be at most one mirror for a given repository. In other words, you cannot map a single - repository to a group of mirrors that all define the same <<<\>>> value. Maven will not aggregate the - mirrors but simply picks the first match. If you want to provide a combined view of several repositories, use a - {{{../../repository-management.html}repository manager}} instead. - - The settings descriptor documentation can be found on the {{{../../maven-settings/settings.html}Maven Local Settings - Model Website}}. - - <>: The official Maven repository is at <<>> hosted by the Sonatype Company and is distributed worldwide via CDN. - - A list of known mirrors is available in the {{{https://repo.maven.apache.org/maven2/.meta/repository-metadata.xml}Repository Metadata}}. These -mirrors may not have the same contents and we don't support them in any way. - -Using A Single Repository - - You can force Maven to use a single repository by having it mirror all repository requests. The repository must - contain all of the desired artifacts, or be able to proxy the requests to other repositories. This setting is most - useful when using an internal company repository with a {{{../../repository-management.html}Maven Repository Manager}} to proxy external requests. - - To achieve this, set <<>> to <<<*>>>. - - <> This feature is only available in Maven 2.0.5+. - -+-----+ - - ... - - - internal-repository - Maven Repository Manager running on repo.mycompany.com - http://repo.mycompany.com/proxy - * - - - ... - -+-----+ - -Advanced Mirror Specification - - A single mirror can handle multiple repositories. This is typically used in conjunction with a repository manager, - that gives easy centralised configuration of the list of repositories behind. - - The syntax: - - * <<<\*>>> matches all repo ids. - - * <<>> matches all repositories except those using localhost or file based repositories. This is used when you want to exclude redirecting repositories that are defined for Integration Testing. - - * since Maven 3.8.0, <<>> matches all repositories using HTTP except those using localhost. - - * multiple repositories may be specified using a comma as the delimiter - - * an exclamation mark may be used in conjunction with one of the above wildcards to exclude a repository id - - [] - - Be careful not to include extra whitespace around identifiers or wildcards in comma separated lists. For example, - a mirror with <<<>>> set to <<>> will not mirror anything while <<>> will mirror - everything but <<>>. - - The position of wildcards within a comma separated list of repository identifiers is not important as the wildcards - defer to further processing and explicit includes or excludes stop the processing, overruling any wildcard match. - - When you use the advanced syntax and configure multiple mirrors, the declaration order matters. - When Maven looks for a mirror of some repository, it first checks for a mirror whose <<<\>>> exactly - matches the repository identifier. If no direct match is found, Maven picks the first mirror declaration that matches - according to the rules above (if any). Hence, you may influence match order by changing the order of the definitions - in the <<>> - - Examples: - - * <<<\*>>> = everything - - * <<>> = everything not on the localhost and not file based. - - * <<>> = repo or repo1 - - * <<<\*,!repo1>>> = everything except repo1 - - [] - -+-----+ - - ... - - - internal-repository - Maven Repository Manager running on repo.mycompany.com - http://repo.mycompany.com/proxy - external:*,!foo - - - foo-repository - Foo - http://repo.mycompany.com/foo - foo - - - ... - -+-----+ - -Creating Your Own Mirror - - The size of the central repository is {{{https://search.maven.org/stats}increasing steadily}} - To save us bandwidth and you time, mirroring the entire central repository is not allowed. - (Doing so will get you automatically banned.) Instead, we suggest you setup a - {{{../../repository-management.html}repository manager}} as a proxy. diff --git a/content/apt/guides/mini/guide-multiple-modules.apt b/content/apt/guides/mini/guide-multiple-modules.apt deleted file mode 100644 index 14b48f4935..0000000000 --- a/content/apt/guides/mini/guide-multiple-modules.apt +++ /dev/null @@ -1,88 +0,0 @@ - ------ - Guide to Working with Multiple Modules - ------ - Brett Porter - Karl Heinz Marbaise - ------ - 2015-03-13 - ------ - -~~ 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 - -Guide to Working with Multiple Modules - - (If you're working with Maven 4, please refer to the {{{./guide-multiple-modules-4.html} Maven 4 edition of this guide}}) - - As seen in the introduction to the POM, Maven supports project aggregation in addition to project inheritance. This section outlines how Maven processes projects with multiple modules, and how you can work with them more effectively. - -* The Reactor - - The mechanism in Maven that handles multi-module projects is referred to as the . This part of the Maven core does the following: - - * Collects all the available modules to build - - * Sorts the projects into the correct build order - - * Builds the selected projects in order - -** Reactor Sorting - - Because modules within a multi-module build can depend on each other, it is important that the reactor sorts all the projects in a way that guarantees any project is built before it is required. - - The following relationships are honoured when sorting projects: - - * a project dependency on another module in the build - - * a plugin declaration where the plugin is another module in the build - - * a plugin dependency on another module in the build - - * a build extension declaration on another module in the build - - * the order declared in the <<<\>>> element (if no other rule applies) - - Note that only "instantiated" references are used - <<>> and <<>> elements do not cause a change to the reactor sort order. - -** Command Line Options - - No special configuration is required to take advantage of the reactor, however it is possible to customize its behavior. - - The following command line switches are available: - - * <<<--resume-from>>> - resumes a reactor from the specified project (e.g. when it fails in the middle) - - * <<<--also-make>>> - build the specified projects, and any of their dependencies in the reactor - - * <<<--also-make-dependents>>> - build the specified projects, and any that depend on them - - * <<<--fail-fast>>> - the default behavior - whenever a module build fails, stop the overall build immediately - - * <<<--fail-at-end>>> - if a particular module build fails, continue the rest of the reactor and report all failed modules at the end instead - - * <<<--non-recursive>>> - do not use a reactor build, even if the current project declares modules and just build the project in the current directory - - Refer to the Maven command line interface reference for more information on these switches. - -* More information - - * {{{http://books.sonatype.com/mvnex-book/reference/multimodule.html} Chapter 6. A Multi-module Project (Maven by Example)}} - - diff --git a/content/apt/guides/mini/guide-multiple-repositories.apt b/content/apt/guides/mini/guide-multiple-repositories.apt deleted file mode 100644 index 4ab83eb8e7..0000000000 --- a/content/apt/guides/mini/guide-multiple-repositories.apt +++ /dev/null @@ -1,140 +0,0 @@ - ------ - Guide to using Multiple Repositories - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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 - -Setting up Multiple Repositories - - There are two different ways that you can specify the use of multiple repositories. The first - way is to specify in a POM which repositories you want to use. That is supported both inside and outside of build profiles: - -+----+ - - -... - - - my-repo1 - your custom repo - http://jarsm2.dyndns.dk - - - my-repo2 - your custom repo - http://jarsm2.dyndns.dk - - -... - - -+----+ - - <> You will also get the standard set of repositories as defined in the - {{{../introduction/introduction-to-the-pom.html#Super_POM}Super POM}}. - - - - The other way you can specify multiple repositories is by creating a profile in the - <<<$\{user.home\}/.m2/settings.xml>>> or <<<$\{maven.home\}/conf/settings.xml>>> file like the following: - -+----+ - - - ... - - ... - - myprofile - - - my-repo2 - your custom repo - http://jarsm2.dyndns.dk - - - - ... - - - - myprofile - - ... - - -+----+ - - If you specify repositories in profiles you must remember to activate that - particular profile! As you can see above we do this by registering a profile - to be active in the <<>> element. - - You could also activate this profile on the command like by executing the following - command: - ------- - -mvn -Pmyprofile ... - ------- - - In fact the <<<-P>>> option will take a CSV list of profiles to activate if you wish to - activate multiple profiles simultaneously. - - <>: The settings descriptor documentation can be found on the {{{../../maven-settings/settings.html}Maven Local Settings Model Website}}. - -* Repository Order - - Remote repository URLs are queried in the following order for artifacts until one returns a valid result: - - [[1]] effective settings: - - [[A]] Global <<>> - - [[A]] User <<>> - - [[1]] local effective build POM: - - [[A]] Local <<>> - - [[A]] Parent POMs, recursively - - [[A]] Super POM - - [[1]] effective POMs from dependency path to the artifact. - - [] - - For each of these locations, the repositories within the profiles are queried first in the order outlined at {{{../introduction/introduction-to-profiles.html}Introduction to build profiles}}. - - Before downloading from a repository, {{{./guide-mirror-settings.html}mirrors configuration}} is applied. - - Effective settings and local build POM, with profile taken into account, can easily be reviewed to see their repositories order with - <<>> and <<>>. - -* Repository IDs - - Each repository must have a <>. Clashing repository IDs within either effective settings or effective POMs lead to build failures. However, repositories from POM get - overwritten by repositories with the same ID from effective settings. Repository IDs are also used in the {{{https://maven.apache.org/ref/3-LATEST/maven-repository-metadata/}local repository metadata}}. diff --git a/content/apt/guides/mini/guide-naming-conventions.apt b/content/apt/guides/mini/guide-naming-conventions.apt deleted file mode 100644 index 1b6470b2da..0000000000 --- a/content/apt/guides/mini/guide-naming-conventions.apt +++ /dev/null @@ -1,63 +0,0 @@ - ------ - Guide to Naming Conventions - ------ - Carlos Sanchez - ------ - 2005-11-01 - ------ - -~~ 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 - -Guide to naming conventions on groupId, artifactId, and version - - [] - - * <> uniquely identifies your project across all projects. - A group ID should follow {{{https://docs.oracle.com/javase/specs/jls/se6/html/packages.html#7.7}Java's - package name rules}}. This means it starts with a reversed domain name you control. - For example, - - <<>>, <<>> - - Maven does not enforce this rule. There are many legacy projects that do not follow - this convention and instead use single word group IDs. However, it will be difficult - to get a new single word group ID approved for inclusion in the Maven Central repository. - - You can create as many subgroups as you want. - A good way to determine the granularity of the <<>> is to use the project structure. That is, if - the current project is a multiple module project, it should append a new identifier to the parent's - <<>>. For example, - - <<>>, <<>>, <<>> - - * <> is the name of the jar without version. If you created it, then you can choose - whatever name you want with lowercase letters and no strange symbols. If it's a third party jar, - you have to take the name of the jar as it's distributed. - - eg. <<>>, <<>> - - * <> if you distribute it, then you can choose any typical version with numbers and dots - (1.0, 1.1, 1.0.1, ...). - Don't use dates as they are usually associated with SNAPSHOT (nightly) builds. If it's a third - party artifact, you have to use their version number whatever it is, and as strange as it can look. - For example, - - <<<2.0>>>, <<<2.0.1>>>, <<<1.3.1>>> diff --git a/content/apt/guides/mini/guide-new-committers.apt b/content/apt/guides/mini/guide-new-committers.apt deleted file mode 100644 index ae216d2f8b..0000000000 --- a/content/apt/guides/mini/guide-new-committers.apt +++ /dev/null @@ -1,45 +0,0 @@ - ------ - Guide for new committers - ------ - Jason van Zyl - ------ - 2005-11-20 - ------ - -~~ 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 - -Guide for new committers - - First thing is to sort out some administrative tasks. Before your account - is created and commit access granted you must complete and fax back to - Apache the {{{http://www.apache.org/licenses/#clas}Committer's License - Agreement}}. - - While this process is sorting itself out it is recommended that you peruse - the various guides provided by Apache. All the guides are located in the - {{{http://www.apache.org/dev/}Development Infrastructure Information}}. - - Of particular interest is the {{{http://www.apache.org/dev/committers.html}Committer's FAQ}} and the - {{{http://www.apache.org/dev/new-committers-guide.html}New Committer's Guide}}. - - If you have any questions please feel free to ask any of the Maven - developers. - diff --git a/content/apt/guides/mini/guide-proxies.apt b/content/apt/guides/mini/guide-proxies.apt deleted file mode 100644 index 8eb1d3173c..0000000000 --- a/content/apt/guides/mini/guide-proxies.apt +++ /dev/null @@ -1,70 +0,0 @@ - ------ - Guide to using proxies - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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 - -Configuring a proxy - - You can configure a proxy to use for some or all of your HTTP requests with Maven. The username and password are only - required if your proxy requires basic authentication (note that later releases may support storing your passwords in - a secured keystore - in the mean time, please ensure your settings.xml file (usually $\{user.home\}/.m2/settings.xml) is secured with permissions - appropriate for your operating system). - - The <<>> setting accepts wild cards, and each host not to proxy is separated by the | character. This matches - the JDK configuration equivalent. - -+----+ - - - . - . - - - example-proxy - true - http - proxy.example.com - 8080 - proxyuser - somepassword - www.google.com|*.example.com - - - . - . - - -+----+ - - Please note that currently NTLM proxies are not supported as they have not been tested. Some transports allow to use - the relevant Java system properties to make this work, but that approach is specific for given implementation, - and should not be considered the "official" way of configuring proxies. - -* Resources - - [[1]] {{{../../maven-settings/settings.html}Settings descriptor documentation}} - - [[2]] {{{./guide-configuring-maven.html}Configuring Maven}} diff --git a/content/apt/guides/mini/guide-releasing.apt b/content/apt/guides/mini/guide-releasing.apt deleted file mode 100644 index b2961fa1dd..0000000000 --- a/content/apt/guides/mini/guide-releasing.apt +++ /dev/null @@ -1,311 +0,0 @@ - ----- - Guide to using the release plugin - ----- - Jason van Zyl - Trent Rosenbaum - Vincent Massol - Karl Heinz Marbaise - ----- - 2006-10-07 - 2015-07-31 - ----- - -~~ 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 - -Releasing - -* Introduction - - The main aim of the maven-release plugin is to provide a standard mechanism to release - project artifacts outside the immediate development team. The plugin provides basic functionality to create - a release and to update the project's SCM accordingly. - - To create a release the maven-release plugin is executed through maven in 2 stages: - - [[1]] Preparing the release. - - [[2]] Performing the release. - - [] - -* Preparing the release - - The plugin will record release information into a new revision of the project's file as well as - applying SCM versioning to the project's resources. - - The <<>> goal will: - - [[1]] Verify that there are no uncommitted changes in the workspace. - - [[2]] Prompt the user for the desired tag, release and development version names. - - [[3]] Modify and commit release information into the file. - - [[4]] Tag the entire project source tree with the new tag name. - - [] - - The following example shows how to run the <<>> goal with a Subversion SCM. The commandline example directs the plugin to - locate a Subversion SCM on a local file system. - - ------ -mvn release:prepare \ - -Dproject.scm.developerConnection=scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk \ - -DtagBase=file:///D:/subversion_data/repos/my_repo/my-app-example/tags ------ - - - When using the <<>> goal, the user must supply maven with information regarding the current location of the project's SCM. - In the previous example maven was supplied with the current location of the development trunk and the new location to record tagged instances of the project. - - * <> - - The current location of the development trunk. A valid SCM URL format appropriate to the SCM provider. The "SCM:Provider:" prefix is used to determine the provider being used. - - * <> - - The new location to record a tagged release. A valid SCM URL format appropriate to the SCM provider without the "SCM:Provider:" prefix. - - [] - - The previous goal parameters can be supplied while executing maven on the commandline, (as shown in the previous example) - or they can be defined and maintained within the project's file. The location of the current development trunk is defined - within the file in the following form: - -+-----+ - - 4.0.0 - com.mycompany.app - app - jar - 1.0-SNAPSHOT - Application - http://app.mycompany.com - ... - - scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk - - ... - - - ... - - maven-release-plugin - 2.5.2 - - ... - - file:///D:/subversion_data/repos/my_repo/my-app-example/tags - - ... - - - ... - - - ... - -+-----+ - - To define the tagBase parameter within the file a tagBase element must be defined within a element. - The following example shows how this would look within the file. - -+-----+ - - 4.0.0 - com.mycompany.app - app - jar - 1.0-SNAPSHOT - Application - http://app.mycompany.com - ... - - scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk - - ... - - - ... - - maven-release-plugin - 2.5.2 - - ... - - file:///D:/subversion_data/repos/my_repo/my-app-example/tags - - ... - - - ... - - - ... - -+-----+ - - During the execution of the <<>> goal maven will interact with the user to gather information about the current release. - Maven will prompt the user for the following information: - - * <>. - - This is a SCM provider specific value, in the case of the Subversion SCM provider this value - is equal to the directory name that will appear under the URL provided by the the tagBase parameter. - - * <>. - - This value is placed in the that will define the current release. If a development holds a version value of 1.0-SNAPSHOT - then the release version would be 1.0. This is not enforced and can be a value appropriate to yourself or a company environment. - - * <>. - - This value is the placed in the next revision of the file used for continuing development. If the current - release represented version 1.0 then an appropriate value could be 2.0-SNAPSHOT. The SNAPSHOT designator is required to prepare and - perform future releases. This value is then committed in the next development revision of the file. - - [] - - After maven has been supplied with the required information the maven-release plugin will interact with the project's - SCM and define a relese to be extracted and deployed. At the same time the project's development trunk is updated allowing developers - to continue with further modifications that will be included within future releases. - - -* Performing the release - - The plugin will extract file revisions associated with the current release. Maven will compile, test and package the versioned project - source code into an artifact. The final deliverable will then be released into an appropriate maven repository. - - The <<>> goal will: - - [[1]] Extract file revisions versioned under the new tag name. - - [[2]] Execute the maven build lifecycle on the extracted instance of the project. - - [[3]] Deploy the versioned artifacts to appropriate local and remote repositories. - - [] - - The following example shows how to run the <<>> goal from the commandline. - ------ -mvn release:perform ------ - - The <<>> goal requires a file called to be present within the project root directory. - The file is constructed during the execution of the <<>> goal and contains all the information - needed to locate and extract the correctly tagged version of the project. Shown below is an example of the contents that can - appear within an instance of the file. - - <> The location of the file is under review and could be moved to the target directory. - ------ -#Generated by Release Plugin on: Sat Nov 12 11:22:33 GMT 2005 -#Sat Nov 12 11:22:33 GMT 2005 -maven.username=myusername -checkpoint.transformed-pom-for-release=OK -scm.tag=1.0 -scm.url=scm\:svn\:file\:///D\:/subversion_data/repos/my_repo/my-app-example/trunk -scm.tag-base=file\:///D\:/subversion_data/repos/my_repo/my-app-example/tags -checkpoint.transform-pom-for-development=OK -checkpoint.local-modifications-checked=OK -checkpoint.initialized=OK -checkpoint.checked-in-release-version=OK -checkpoint.tagged-release=OK -checkpoint.prepared-release=OK -checkpoint.check-in-development-version=OK ------ - - The file is created while preparing the release. After performing the release the file remains within the project root - directory until the maven user deletes it. The file can be given to any developer within the team and - by simply excuting the <<>> goal can create and deploy a new instance of the project artifact time and again. - - During the execution of the <<>> goal the entire maven build lifecycle is executed on the project. - The tagged project source code is extracted, compiled, tested, documented and deployed. An instance of the release artifact is deployed - to the machine's local repository. An another instance of the release can be deployed to a remote repository by configuring the - element within the file. - - The following is an example of how a distributionManagement element can be configured within a project file. - -+-----+ - - 4.0.0 - com.mycompany.app - app - jar - 1.0-SNAPSHOT - Application - http://app.mycompany.com - ... - - - myRepoId - myCompanyReporsitory - ftp://repository.mycompany.com/repository - - - ... - -+-----+ - - If the distributionManagement element is not configured within the file then the deployment of the artifact will fail. Maven will - report a failure back to the user for the execution of the maven-deploy plugin. Please refer maven documentationa and additional mini - guides for the use of the maven-deploy plugin. - - The following delvierables are created and deployed to local and remoted repositories after the execution of the <<>> goal has finished. - - * -.jar - - The binaries for the current release of the project. - - * --javadoc.jar - - The javadoc explaining the current functionality of the classes within the current release. - - * --source.jar - - The source code revisions used to build the current release of the project. - - * -.pom - - The contents of the file used to create the current release of the project. - - [] - -* Troubleshooting - -** I get a "The authenticity of host '' can't be established." error and the build hangs - - This is because your <<<~user/.ssh/known_hosts>>> file doesn't have the host listed. You'd normally get a prompt to add the host to the - known host list but Maven doesn't propagate that prompt. The solution is to add the host the <<>> file before - executing Maven. On Windows, this can be done by installing an OpenSSH client (for example - {{{http://sshwindows.sourceforge.net/download/}SSHWindows}}), running <<>>> and accepting to add the host. - -** The site deploy goal hangs - - First, this means that you have successfully deployed the artifacts to the remote repo and that it's only the site - deployment that is now an issue. Stop your build, cd to <>> and run the build again by - executing <<>>. You should see a prompt asking you to enter a password. This happens if your key is not - in the authorized keys on the server. - - - diff --git a/content/apt/guides/mini/guide-relocation.apt b/content/apt/guides/mini/guide-relocation.apt deleted file mode 100644 index 0a64fa82ac..0000000000 --- a/content/apt/guides/mini/guide-relocation.apt +++ /dev/null @@ -1,216 +0,0 @@ - ------ - Guide to relocation - ------ - Dennis Lundberg - ------ - 2006-07-08 - ------ - -~~ 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 - -Guide to relocation - - Sometimes it is necessary to relocate artifacts in the repository. One - example of that is when a project moves from one groupId to a different groupId. - - Making changes to the repository can have far reaching consequences. So it is - best to get it right the first time, hence this guide. - - <<2020 rework in progress>>, see - {{{https://lists.apache.org/thread.html/r5e940260cfe5234f540c20fdb7bb7dacbb63b911a4b902c75f4f0cd2%40%3Cdev.maven.apache.org%3E}discussion on dev mailing list}}, - still need analysis of issues, definition of improvements, and of course implementation... - -* How to relocate a Maven 2 artifact to a different groupId - - The goal of the example below is for the <<>> project to relocate its groupId from <<>> to - <<>>. - -** Working on past versions - - [[1]] Copy all <<>>-related files from <<>> in your Maven 2 - repository to a temporary location. - - [[2]] Change the groupId to <<>> in all <<>>-related POM files in the - temporary location. - - [[3]] Copy all files from the temporary location to <<>> in - your Maven 2 repository. - - [[4]] Create a minimal Maven 2 POM file for every old release of <<>> in - your Maven 2 repository. The POM files only need to include <<>>, - <<>>, <<>> and the relocation section. - - <> Before you replace your old POM files in <<>> with these - minimal POM files, make sure you have made backups! - - The minimal POM file might look like this for version 1.0 of <<>>: - -+----+ - - 4.0.0 - bar - foo - 1.0 - - - org.bar - - - -+----+ - - In this case we are relocating because the groupId has changed. We only need - to add the element that has changed to the <<>> element. For - information on which elements are allowed in the <<>> element, - see - {{{/ref/current/maven-model/maven.html#class_relocation}the POM reference}}. - - [[5]] If your project uses MD5 or SHA1 checksums you must now create new checksums for - the pom files in <<>> in your Maven 2 repository. If the POM file needs - to be signed, do that as well. - - [[6]] If your project syncs with Central, you should now initiate that sync. - This might happen automatically depending on your projects sync policy. - - [] - - Your <<>>-artifacts are now available to Maven users with both the old - and the new groupId. Projects using the old groupId will automatically be - redirected to the new groupId and a warning telling the user to update their - dependencies will be issued. - -** Releasing the next version - - When the next release of <<>> is made, you should publish two Maven 2 POM - files: first you should publish <<>>'s POM with the new groupId <<>>. - - Because data in the repository is not supposed to change, Maven doesn't - download POM files that it has already downloaded. Therefore you will also need - to publish a relocation POM file with the old groupId <<>> for the new version: this - should be a minimal relocation POM (as described in step 4 above), but for the - new version of <<>>. - - For the release after that, you only need to publish a Maven POM with a - groupId of <<>>, since users of the previous version have been - informed of the changed groupId. - -* Examples - -** Apache Ant - - [[1]] has published its releases until 1.6.5 to Maven 1-compliant <<>> coordinates - (see {{{https://repo.maven.apache.org/maven2/ant/ant/}repository content}}), - - [[2]] starting with 1.7.0, moved to reverse-DNS compliant Maven 2+ <<>> coordinates, - (see {{{https://repo.maven.apache.org/maven2/org/apache/ant/ant/}repository content}}), - - [[3]] published one <<>> relocation POM - in old groupId to advertise about the move - (see {{{https://repo.maven.apache.org/maven2/ant/ant/1.7.0/}repository content}}). - - [] - - Notice that past <<>> versions POMs (until 1.6.5) have not been modified to advertise about the move: - Central POM content is not expected to be changed once published (because initial content has been downloaded - many times and is not expected to be re-loaded later). - -** Apache POI - - [[1]] has published its releases until 3.0-alpha-3 to Maven 1-compliant <<>> coordinates - (see {{{https://repo.maven.apache.org/maven2/poi/poi/}repository content}}), - - [[2]] starting with 3.0-FINAL, moved to reverse-DNS compliant Maven 2+ <<>> coordinates, - (see {{{https://repo.maven.apache.org/maven2/org/apache/poi/poi/}repository content}}), - - [[3]] published <<>> relocation POM <> - in old groupId to advertise about the move - (see {{{https://repo.maven.apache.org/maven2/poi/poi/3.0-FINAL/}repository content}}). - - [[4]] published <<>> relocation POMs for 3.0.1-FINAL, 3.0.2-beta1/beta2/FINAL and 3.1-beta1/beta2/FINAL - in old groupId to advertise about the move - (see {{{https://repo.maven.apache.org/maven2/poi/poi/}repository content}}). - -[] - -** Testing - - Using <<>> - -+-----+ - - - 4.0.0 - - test - relocation-test - 1.0-SNAPSHOT - - - - ant - ant - 1.7.0 - - - poi - poi - 3.0-FINAL - - - -+-----+ - - Dependency resolution of these relocated artifacts follows to the new relocated coordinates, issuing a warning: - ------- -$ mvn dependency:list dependency:tree -[INFO] Scanning for projects... -[INFO] -[INFO] ------------------------< test:relocation-test >------------------------ -[INFO] Building relocation-test 1.0-SNAPSHOT -[INFO] from pom.xml -[INFO] --------------------------------[ jar ]--------------------------------- -[WARNING] The artifact ant:ant:jar:1.7.0 has been relocated to org.apache.ant:ant:jar:1.7.0 -[WARNING] The artifact poi:poi:jar:3.0-FINAL has been relocated to org.apache.poi:poi:jar:3.0-FINAL -[INFO] -[INFO] --- dependency:3.6.0:list (default-cli) @ relocation-test --- -[INFO] -[INFO] The following files have been resolved: -[INFO] org.apache.ant:ant:jar:1.7.0:compile -- module ant (auto) -[INFO] org.apache.ant:ant-launcher:jar:1.7.0:compile -- module ant.launcher (auto) -[INFO] org.apache.poi:poi:jar:3.0-FINAL:compile -- module poi (auto) -[INFO] commons-logging:commons-logging:jar:1.1:compile -- module commons.logging (auto) -[INFO] log4j:log4j:jar:1.2.13:compile -- module log4j (auto) -[INFO] -[INFO] -[INFO] --- dependency:3.6.0:tree (default-cli) @ relocation-test --- -[WARNING] The artifact ant:ant:jar:1.7.0 has been relocated to org.apache.ant:ant:jar:1.7.0 -[WARNING] The artifact poi:poi:jar:3.0-FINAL has been relocated to org.apache.poi:poi:jar:3.0-FINAL -[INFO] test:relocation-test:jar:1.0-SNAPSHOT -[INFO] +- org.apache.ant:ant:jar:1.7.0:compile -[INFO] | \- org.apache.ant:ant-launcher:jar:1.7.0:compile -[INFO] \- org.apache.poi:poi:jar:3.0-FINAL:compile -[INFO] +- commons-logging:commons-logging:jar:1.1:compile -[INFO] \- log4j:log4j:jar:1.2.13:compile -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ ------- diff --git a/content/apt/guides/mini/guide-repository-ssl.apt b/content/apt/guides/mini/guide-repository-ssl.apt deleted file mode 100644 index 9746b7f763..0000000000 --- a/content/apt/guides/mini/guide-repository-ssl.apt +++ /dev/null @@ -1,155 +0,0 @@ - ----- - Remote repository access through authenticated HTTPS - ----- - Arnaud Bailly - ----- - 2005-11-11 - ----- - -~~ 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 - -Guide to Remote repository access through authenticated HTTPS - - This document describes how to configure Maven to access a remote - repository that sits behind an HTTPS server which requires client - authentication with certificates. - -* The problem - - There is a maven repository at - <<>>. This server only serves clients - authenticated through SSL protocol by a valid certificate signed by an approved certificate - authority's certificate which we call the <<>>. In the - simplest case where the server is used internally by an identified - community of users (e.g. corporate intranet), the server's certificate is the certificate authority - as the server is used only internally. - - So we assume that we have access to the trusted certificate in X.509 - format stored in a file named: - ------------- - /somewhere/in/filesystem/CACert.cert ------------- - - The client's certificate has been issued by some means not - described in this document in PKCS#12 format, which is the format - that is accepted by browsers (at least Firefox and Internet Explorer) - for import into their keystore. - This file is named: - ---------------------- - /home/directory/mycertificate.p12 ---------------------- - - and we assume it is accessible when launching maven. - This file contains the client's private key which may be - very sensitive information so it is secured by a password: - --------------------- - CeRtPwD --------------------- - - The remote repository is referenced either through the <<>> - file: - ---------------- -maven.repo.remote=https://my.server.com/maven,http://www.ibiblio.org/maven ---------------- - -* The solution - - For maven to use this repository, we should take the following steps: - - [[1]] Create a store to hold the server's certificate usings Oracle's - {{{https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html} keytool}}, - - [[2]] Define properties to be used by HttpClient for finding keys and - certificate - -** Storing certificate - - The following command line imports the certififcate authority's - certificate into a JKS formatted key store named <<>>, the - . - ------------------------------ -$> keytool -v -alias mavensrv -import \ - -file /somewhere/in/filesystem/CACert.cert\ - -keystore trust.jks -Enter keystore password: -Owner: .... -Issuer: .... -Serial number: .... -Valid from: Mon Feb 21 22:34:25 CET 2005 until: Thu Feb 19 22:34:25 CET 2015 -Certificate fingerprints: - MD5: ....... - SHA1: ..... -Trust this certificate? [no]: yes -Certificate was added to keystore -[Storing trust.jks] -$> ------------------------------- - - Note that it should be possible to import a full chain of certificates - with only one root certificate being trusted but the author did not test it. - -** Setting properties - - The following properties must be set at start of maven to be - accessible when HttpClient starts up. - - [javax.net.ssl.trustStore] the path to the keystore where trusted certificates are stored - - [javax.net.ssl.trustStoreType] the type of storage for this store, maybe either - <<>> (default) or <<>> - - [javax.net.ssl.trustStorePassword] the password protecting the store - - [javax.net.ssl.keyStore] the path to the keystore where user's private key is stored - - [javax.net.ssl.keyStoreType] the type of storage for this store, maybe either - <<>> (default) or <<>> - - [javax.net.ssl.keyStorePassword] the password protecting the store - - - Not all the properties must be set depending of your precise settings: type of store may - left to default, password may be empty. - - They may be set either on maven's command-line, in - <<<.mavenrc>>> file or in <<>> environment - variable. For the setting defined in this document, here is an example - <<<.mavenrc>>> file: - -------------- -MAVEN_OPTS="-Xmx512m -Djavax.net.ssl.trustStore=trust.jks \ - -Djavax.net.ssl.trustStorePassword= \ - -Djavax.net.ssl.keyStore=/home/directory/mycertificate.p12 \ - -Djavax.net.ssl.keyStoreType=pkcs12 \ - -Djavax.net.ssl.keyStorePassword=XXXXXX" ---------------- - -* Links - - The following links may be useful in understanding SSL infrastructure - management in Java: - - * {{{http://hc.apache.org/httpclient-3.x/sslguide.html} HttpClient}}'s SSL guide diff --git a/content/apt/guides/mini/guide-reproducible-builds.apt b/content/apt/guides/mini/guide-reproducible-builds.apt deleted file mode 100644 index 85513046a3..0000000000 --- a/content/apt/guides/mini/guide-reproducible-builds.apt +++ /dev/null @@ -1,137 +0,0 @@ - ------ - Guide to Configuring for Reproducible Builds - ------ - Hervé Boutemy - ------ - 2019-11-03 - ------ - -~~ 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 - -Configuring for Reproducible Builds - -* What are Reproducible Builds? - - {{{https://reproducible-builds.org/}Reproducible builds}} are a set of software development practices that create an - independently-verifiable path from source to binary code. A build is <> if given the same source code, - build environment and build instructions, any party can recreate <> identical copies of all specified artifacts. - - {{{https://github.com/jvm-repo-rebuild/reproducible-central}Reproducible Central}} lists projects releases that - have been checked as reproducible by rebuilding independently from the reference build published in Central Repository. - -* How do I configure my Maven build? - - There is no Maven version prerequisite. Everything happens at plugin level: - - [[1]] Upgrade your plugins to reproducible versions: to easily detect {{{/plugins/maven-artifact-plugin/plugin-issues.html}required upgrades}}, run - --------- -mvn artifact:check-buildplan --------- - - [[2]] Enable Reproducible Builds mode for plugins, by adding {{{https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-OutputArchiveEntriesTimestamp}<<>> property}} to the project's <<>>: - -+--------+ - - 2023-01-01T00:00:00Z - -+--------+ - - [] - - Notice: starting with Maven 4.0.0-beta-5, Reproducible Builds mode will be active by default (see {{{https://issues.apache.org/jira/browse/MNG-8258}MNG-8258}}), without modifying project's <<>>. - Setting a value in your <<>> will only be useful if you want to override the inherited value. - - You have the basics configured. The output should be mostly reproducible now. - -* How to test my Maven build reproducibility? - - Using {{{/plugins/maven-artifact-plugin/compare-mojo.html}<<>>'s <<>> goal}}, - you can easily check that the second build of your project produce the same output than an initial build: - - [[1]] build and <<>> your project (don't hesitate to customize arguments to better match your project): - --------- -mvn clean install --------- - - [[2]] rebuild (<<>> only, without installing) and check against the previous install: - --------- -mvn clean verify artifact:compare --------- - - [] - - Notice that this local test does NOT really prove that your build is yet reproducible by a third party, because it may still suffer from environment leaks (username, current directory, ...). But it is easy to do, and prevents basic non-reproducible issues like timestamps. - Really checking reproducibility requires to rebuild from a completely different setup: this is harder to do, even if containers may ease the task. - -* How to fix my Maven build reproducibility? - - If something is still not reproducible after initial setup and {{{/plugins/maven-artifact-plugin/plugin-issues.html}automatic check from <<>>}}: - - [[1]] Use {{{https://diffoscope.org/}diffoscope}} to find the unstable output between builds. The <<>> goal proposes a command with path to files: just copy/paste to launch. - - [[2]] Find the plugin that generated this output. - - [[3]] Check if a reproducible version of the plugin is available. - If not, please open an issue to help plugin maintainers improving Reproducible Builds support at every plugin level. - - [] - -* More Details - - Reproducible Builds for Maven: - - * Require <> in dependencies, - - * Generally give <> because of different newlines. (carriage return linefeed on Windows, linefeed on Unixes) - - * Generally depend on the <> used to compile. (Even with source/target defined, each major JDK version changes the generated bytecode) - - [] - - For detailed explanations, see {{{https://s.apache.org/reproducible-builds}Maven "Reproducible/Verifiable Builds" Wiki page}}. - -* FAQ - - * Q. Can the <<>> property in <<>> be updated automatically at release time? - - A. Yes. - - Details depend on your release process tooling: - - * if you use {{{/plugins/maven-release-plugin/}maven-release-plugin}}, you'll need <>: - it will automatically update the timestamp value in <<>> during the release in the same commit that updates version, - - * if you have a custom release process tooling, you'll need to add the feature to your release tooling. - Notice that if you're using <<>> in custom release scripts, starting with release 2.9.0, {{{https://github.com/mojohaus/versions-maven-plugin/issues/453}<<>> goal updates the property}}. - - * instead of explicitly writing a timestamp in their <<>>, some people tend to prefer using last Git commit timestamp, like <<<$\{git.commit.time}>>> from - {{{https://github.com/git-commit-id/git-commit-id-maven-plugin}git-commit-id-maven-plugin}} (with <<<\UTC>>> to be independent from user's timezone). - - [] - - Don't hesitate to share your questions or solutions on {{{/mailing-lists.html}user mailing-list}}. - - * Q. Which additional plugins need to be updated for Reproducible Builds? - - A. See the list of {{{/plugins/maven-artifact-plugin/plugin-issues.html}required upgrades}} diff --git a/content/apt/guides/mini/guide-site.apt b/content/apt/guides/mini/guide-site.apt deleted file mode 100644 index 85e713a23d..0000000000 --- a/content/apt/guides/mini/guide-site.apt +++ /dev/null @@ -1,348 +0,0 @@ - ------ - Guide to creating a site - ------ - Brett Porter - Jason van Zyl - ------ - 2015-07-18 - ------ - -~~ 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 - -Creating a site - -* Creating Content - - The first step to creating your site is to create some content. In Maven, the site content is separated by format, - as there are several available. - -------------------- -+- src/ - +- site/ - +- apt/ - | +- index.apt - ! - +- markdown/ - | +- content.md - | - +- fml/ - | +- general.fml - | +- faq.fml - | - +- xdoc/ - | +- other.xml - | - +- site.xml --------------------- - - You will notice there is now a <<<$\{project.basedir\}/src/site>>> directory within which is contained a <<>> site descriptor - along with various directories corresponding to the supported document types. - - Let's take a look at the examples of the various document types: - - * <<>>: the APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this one) - very quickly. A full reference of the {{{/doxia/references/apt-format.html}APT Format}} is available, - - * <<>>: the well known {{{https://en.wikipedia.org/wiki/Markdown}Markdown}} format, - - * <<>>: the FML format is the {{{/doxia/references/fml-format.html}FAQ format}}, - - * <<>>: an XML document conforming to a small and simple set of tags, see the {{{/doxia/references/xdoc-format.html}full reference}}. - - [] - - Other formats are available, but at this point these 4 are the best tested. - - There are also several possible output formats, but as of Maven Site Plugin, only XHTML is available. - - Note that all of the above is optional - just one index file is required in one of the input trees. Each of the paths will be merged - together to form the root directory of the site. - -* Customizing the Look & Feel - - If you want to tune the way your site looks, you can use a custom <> to provide your own CSS styles. If that is - still not enough, you can even tweak the output templates that Maven uses to generate the site documentation. - - You can visit the {{{/skins/}Skins index}} to have a - look at some of the skins that you can use to change the look of your site. - -~~ TODO: The following link is currently not available. Restore it when it becomes available again. -~~ For an in-depth discussion of site customization, please have a look at the -~~ {{{http://www.sonatype.com/book/site-generation.html} Maven User Guide, Chapter 9, "Site Generation"}}. - -* Generating the Site - - Generating the site is very simple, and fast! - ---------------- -mvn site ---------------- - - By default, the resulting site will be in <<>> - - For more information on the Maven Site Plugin, see the {{{../../plugins/maven-site-plugin/} maven-site-plugin reference}}. - -* Deploying the Site - -** Classical Website deployment - - To be able to deploy the site with a classical network protocol (ftp, scp, webdav), you must first declare a location to distribute to in your <<>>, - similar to the repository for deployment: - -+-------------- - - ... - - - website - scp://www.mycompany.com/www/docs/project/ - - - ... - -+-------------- - - * the <<<\>>> element identifies the repository, so that you can attach credentials to it in your <<>> - file using the {{{../../settings.html#Servers} <<<\>>> element}} as you would for any other repository, - - * the <<<\>>> gives the location to deploy to. Currently, only SSH is supported by default, as above which copies to the host - <<>> in the path <<>>, but you can {{{/plugins/maven-site-plugin/examples/adding-deploy-protocol.html}add more protocols as required}}. - If subprojects inherit the site URL from a parent POM, they will automatically get their <<<\>>> appended to form their effective deployment location. - - [] - - Once distribution location is configured, deploying the site is done by using the <<>> phase of the site lifecycle. - ---------------- -mvn site-deploy ---------------- - -** GitHub Pages, Apache svnpubsub/gitpubsub Deployment - - When site publication is done with a SCM commit, like with {{{https://pages.github.com/}GitHub Pages}} or - {{{https://infra.apache.org/project-site.html#tools}Apache svnpubsub/gitpubsub}}, deploying the site will be done with - {{{/plugins/maven-scm-publish-plugin/}Maven SCM Publish Plugin}}. - - For example with a project hosted on GitHub and using GitHub Pages for its site publication: - -+--------------------- - - org.apache.maven.plugins - maven-scm-publish-plugin - 3.1.0 - - ${project.scm.developerConnection} - gh-pages - - -+--------------------- - - Deploying the site is done in 2 steps: - - [[1]] staging the content by using the <<>> phase of the site lifecycle followed by <<>>: <<>> - - [[2]] publishing the staged site to the SCM: <<>> - - [] - -* Creating a Site Descriptor - - The <<>> file is used to describe the structure of the site. - A sample is given below: - -+------------------- - - - - Maven - https://maven.apache.org/images/apache-maven-project.png - https://maven.apache.org/ - - - https://maven.apache.org/images/maven-small.gif - - - - - - - - - - - - - - - - - - - - - ... - - -+------------------- - - ~~TODO: deserves more explanation. - - <> The <<<\>>> element above. - When building the site, this is replaced by a menu with links to all the - reports that you have configured. - - More information about the site descriptor is available at the - {{{/plugins/maven-site-plugin/examples/sitedescriptor.html}dedicated page of Maven Site Plugin}}. - -* Adding Extra Resources - - You can add any arbitrary resource to your site by including them in a - <<>> directory as shown below. Additional CSS files will be picked up - when they are placed in the <<>> directory within the <<>> - directory. - -------------------- -+- src/ - +- site/ - +- resources/ - +- css/ - | +- site.css - | - +- images/ - +- pic1.jpg --------------------- - - The file <<>> will be added to the default XHTML output, so it can be used to adjust the default Maven stylesheets if desired. - - The file <<>> will be available via a relative reference to the <<>> directory from any page in your site. - -* Configuring Reports - - Maven has several reports that you can add to your web site to display the current state of the project. - These reports take the form of plugins, just like those used to build the project. - - There are many standard reports that are available by gleaning information from the POM. Currently - what is provided by default are: - - * Dependencies Report - - * Mailing Lists - - * Continuous Integration - - * Source Repository - - * Issue Tracking - - * Project Team - - * License - - [] - - To find out more please refer to the - {{{../../plugins/maven-project-info-reports-plugin/}Project Info Reports Plugin}}. - - To add these reports to your site, you must add the Project Info Reports plugin to a special <<<\>>> section in the POM. The - following example shows how to configure the standard project information reports that display information from the - POM in a friendly format: - -+------------------ - - ... - - - - org.apache.maven.plugins - maven-project-info-reports-plugin - 2.8 - - - - ... - -+------------------ - - If you have included the appropriate <<<\>>> tag in your <<>> descriptor, then when you regenerate - the site those items will appear in the menu. - - Many other plugins provide reporting goals: look for "R" (Reporting) value in the "Type" column of the {{{/plugins/} list of plugins}}. - When plugins are both Build and Reporting plugins, defining explicitly the version in the reporting section is usually not - necessary since reporting will use the version from <<>> or <<>>. Since Maven Site Plugin 3.4, - reporting plugin also get configuration from <<>>. - - <> Many report plugins provide a parameter called <<>> or similar to specify the destination - for their report outputs. This parameter is only relevant if the report plugin is run standalone, i.e. by invocation - directly from the command line. In contrast, when reports are generated as part of the site, the configuration of the - Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a central location. - - ~~TODO: explain report sets - -* Internationalization - - Internationalization in Maven is very simple, as long as the reports you are using have that particular locale - defined. For an overview of supported languages and instructions on how to add further languages, please see the - related article {{{../../plugins/maven-site-plugin/i18n.html} Internationalization}} from the Maven Site Plugin. - - To enable multiple locales, add a configuration similar to the following to your POM: - -+------------------ - - ... - - - - org.apache.maven.plugins - maven-site-plugin - 3.4 - - en,fr - - - - - ... - -+------------------ - - This will generate both an English and a French version of the site. If <<>> is your current locale, then it will - be generated at the root of the site, with a copy of the French translation of the site in the <<>> subdirectory. - - To add your own content for that translation instead of using the default, place a subdirectory with that locale - name in your site directory and create a new site descriptor with the locale in the file name. For example: - -------------------- -+- src/ - +- site/ - +- apt/ - | +- index.apt (Default version) - | - +- fr/ - | +- apt/ - | +- index.apt (French version) - | - +- site.xml (Default site descriptor) - +- site_fr.xml (French site descriptor) --------------------- - - With one site descriptor per language, the translated site(s) can evolve independently. diff --git a/content/apt/guides/mini/guide-snippet-macro.apt b/content/apt/guides/mini/guide-snippet-macro.apt deleted file mode 100644 index 9be30daeb7..0000000000 --- a/content/apt/guides/mini/guide-snippet-macro.apt +++ /dev/null @@ -1,116 +0,0 @@ - ------ - Guide to the Snippet Macro - ------ - Wendy Smoak - ------ - 2014-08-20 - ------ - -~~ 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 - -~~ @todo dennisl: We should drop this document and refer to the macros page in the Doxia site - -Guide to the Snippet Macro - - When generating your project website with Maven, you have the option of - dynamically including s of source code in your pages. - - A is a section of a source code file that is surrounded by specially - formatted comments. - - This functionality is inspired by the - {{{http://www.atlassian.com/software/confluence/}Confluence}} snippet macro, - and is provided by the Maven Doxia project by way of the Maven Site Plugin. - - To include snippets of source code in your documentation, first add comments - in the source document surrounding the lines you want to include, and then - refer to the snippet by its id in the documentation file. Each snippet must be - assigned an id, and the id must be unique within the source document. The id - parameter is not required if you want to include the entire file. - - Following are examples of snippets in various source documents, as well - as the corresponding macros in the APT documentation format. - - See the Doxia - {{{/doxia/macros/index.html#Snippet_Macro}Macros Guide}} - for more information and examples. - -* Snippets in Sources - -** Java - -+----- - // START SNIPPET: snip-id - public static void main( String[] args ) - { - System.out.println( "Hello World!" ); - } - // END SNIPPET: snip-id -+----- - -** XML - -+----- - - - /logon.jsp - - success - /mainMenu.jsp - - - -+----- - -** JSP - -+------ - <%-- START SNIPPET: snip-id --%> - - <%-- END SNIPPET: snip-id --%> -+------ - -* Snippets in Documentation - -** APT - -+------ - %{snippet|id=snip-id|url=http://svn.example.com/path/to/Sample.java} - - %{snippet|id=snip-id|url=file:///path/to/Sample.java} -+------ - - As of doxia-core version 1.0-alpha-9, a 'file' parameter is also available. - If a full path is not specified, the location is assumed to be relative to - $\{project.basedir\}. - -+------ - ~~ Since doxia-core 1.0-alpha-9 - %{snippet|id=abc|file=src/main/webapp/index.jsp} -+------ - - * Macros in apt <> be indented. - - * Exactly one of <<>> or <<>> <> be specified. - diff --git a/content/apt/guides/mini/guide-using-extensions.apt b/content/apt/guides/mini/guide-using-extensions.apt deleted file mode 100644 index 79b847cbcd..0000000000 --- a/content/apt/guides/mini/guide-using-extensions.apt +++ /dev/null @@ -1,110 +0,0 @@ - ------ - Guide to using Extensions - ------ - Jason van Zyl - Konrad Windszus - ------ - 2022-11-16 - ------ - -~~ 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 Extensions - - Extensions are a way to add classes to either the {{{./guide-maven-classloading.html#Core_Classloader}Core Classloader}} (Core Extensions) - or the {{{./guide-maven-classloading.html#Project_Classloaders}Project Classloader}} (Build Extensions). - This is necessary for adjusting Maven in a way that affects more than just one plug-in. - - The mechanism allows extensions to either replace default {{{https://www.eclipse.org/sisu/}Sisu components}} with custom ones or add - new components which are used at run time. In addition one could also expose additional packages from the Core Classloader. - - Extensions are typically used to enable - {{{../../wagon/wagon-providers/}Wagon providers}}, used for the transport - of artifact between repositories, and plug-ins which {{{../../examples/maven-3-lifecycle-extensions.html}provide lifecycle enhancements}}. - -* Loading Extensions - - There are different means of loading extensions depending on the type. There are which are loaded <> - and build extensions which are loaded <>. - Some extensions require early loading as they fundamentally change Maven behaviour. - An extension's documentation should indicate whether it provides a core or a build extension. - -** Core Extension - - * Registered via extension jar in <<<$\{maven.home\}/lib/ext>>> - - * Registered via CLI argument <<>> - - * Registered via {{{../../configure.html#mvn-extensions-xml-file}<<<.mvn/extensions.xml>>> file}} - - [] - -** Build Extension - - * Registered via {{{../../pom.html#Plugins}<<build->plugins->plugin>>>}} with element <<>> being set to <<>>. This is useful for regular plug-ins carrying some extensions. - - Example: - -+----+ - - - ... - - - - org.apache.felix - maven-bundle-plugin - true - - ... - - - - - ... - - -+----+ - - * Registered as build extension in {{{../../pom.html##Extensions}<<build->extensions->extension>>>}} - - Example: - -+----+ - - - ... - - - - org.apache.maven.wagon - wagon-ftp - 2.10 - - - - ... - - -+----+ - - [] - diff --git a/content/apt/guides/mini/guide-using-modello.apt b/content/apt/guides/mini/guide-using-modello.apt deleted file mode 100644 index 0e4b31ecdd..0000000000 --- a/content/apt/guides/mini/guide-using-modello.apt +++ /dev/null @@ -1,90 +0,0 @@ - ------ - Guide to using Modello - ------ - Jason van Zyl - Hervé Boutemy - ------ - 2009-03-01 - ------ - -~~ 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 - -Guide to using Modello - - {{{https://codehaus-plexus.github.io/modello/}Modello}} is a tool for generating resources from a simple model. From a - {{{https://codehaus-plexus.github.io/modello/modello.html}simple model}} you can generate things like: - - * Java sources - - * XML serialization code for the model - - * XML deserialization code for model - - * Model documentation - - * XSD - - [] - - A typical modello model looks like the following: - -%{snippet|id=modello-model|url=https://raw.githubusercontent.com/apache/maven-archetype/master/archetype-models/archetype-descriptor/src/main/mdo/archetype-descriptor.mdo} - - To utilize Modello, you would configure the <<>> something like the following where you want - to generate the Java sources for the model, the xpp3 serialization code and the xpp3 deserialization code - (see {{{https://codehaus-plexus.github.io/modello/modello-plugins/modello-plugin-xpp3/}modello-plugin-xpp3}} for more details): - -+----+ - - - ... - - - - org.codehaus.modello - modello-maven-plugin - 1.8.3 - - - - - xpp3-reader - - xpp3-writer - - java - - - - - - src/main/mdo/archetype-descriptor.mdo - - 1.0.0 - true - - - - - ... - - -+----+ diff --git a/content/apt/guides/mini/guide-using-one-source-directory.apt b/content/apt/guides/mini/guide-using-one-source-directory.apt deleted file mode 100644 index ffacd8fbd7..0000000000 --- a/content/apt/guides/mini/guide-using-one-source-directory.apt +++ /dev/null @@ -1,194 +0,0 @@ - ------ - 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. - - 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 than - 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: <<>> and <<>>. - - 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 <<>> at the top level not to produce anything, but to include the other modules we plan to create: - -+-------- - - my-parent - pom - ... - - core - module - - -+-------- - - Next, the modules themselves are created. Here is the <<>> file you should create. The one in the - <<>> subdirectory will be similar. - -+-------- - - 4.0.0 - - my-groupId - my-parent - 1.0-SNAPSHOT - - - my-core - - - ../src/main/java - - - - maven-compiler-plugin - 2.0.2 - - **/core/** - - - - - -+-------- - - In this example, the sources are found in the parent directory <<<../src/main/java>>>, and only Java files within a - <<>> 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 (i.e., 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 (e.g., just a subset of classes, or the same JAR with - debugging enabled), Maven supports this using profiles. See {{{../introduction/introduction-to-profiles.html} Introduction to Profiles}} - for more information. diff --git a/content/apt/guides/mini/guide-using-toolchains.apt b/content/apt/guides/mini/guide-using-toolchains.apt deleted file mode 100644 index a8974a51e0..0000000000 --- a/content/apt/guides/mini/guide-using-toolchains.apt +++ /dev/null @@ -1,179 +0,0 @@ - ------ - Guide to Using Toolchains - ------ - Maria Odea Ching - Dennis Lundberg - Karl Heinz Marbaise - ------ - 2016-03-08 - ------ - -~~ 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 - - -Guide to Using Toolchains - -* What are Toolchains? - - Maven Toolchains provide a way for a project to specify the JDK (or other tools) - used to build the project, without needing to configure this in each plugin or in every <<>>. - - When Maven Toolchains are used to specify the JDK, a project can be built by a specific version of the JDK independent - of the one Maven is running with. This is similar to how JDK versions can be set in IDEs like IDEA, NetBeans and Eclipse. - -** Prerequisites - - For more details about Toolchains' design and implementation, - see {{{https://cwiki.apache.org/confluence/display/MAVENOLD/Toolchains}Toolchains}}. - - Below are some plugins which are toolchain-aware, with the toolchain-type used: - -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -|| Toolchain type || <> || <> || <> -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-compiler-plugin/}maven-compiler-plugin}}>>> | 2.1 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-jarsigner-plugin/}maven-jarsigner-plugin}}>>> | 1.3 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-javadoc-plugin/}maven-javadoc-plugin}}>>> | 2.5 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-pmd-plugin/}maven-pmd-plugin}}>>> | 3.14.0 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-surefire-plugin/}maven-surefire-plugin}}>>> | 2.5 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{/plugins/maven-failsafe-plugin/}maven-failsafe-plugin}}>>> | 2.5 | Apache Maven -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}animal-sniffer-maven-plugin}}>>> | 1.3 | MojoHaus -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{https://www.mojohaus.org/cassandra-maven-plugin/}cassandra-maven-plugin}}>>> | 0.7.0-1 | MojoHaus -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{https://www.mojohaus.org/exec-maven-plugin/}exec-maven-plugin}}>>> | 1.1.1 | MojoHaus -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{https://www.mojohaus.org/jdiff-maven-plugin/}jdiff-maven-plugin}}>>> | 1.0-beta-1-SNAPSHOT | MojoHaus -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| jdk | <<<{{{https://www.mojohaus.org/keytool/keytool-maven-plugin/}keytool-maven-plugin}}>>> | 1.4 | MojoHaus -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ -| protobuf | <<<{{{https://www.xolstice.org/protobuf-maven-plugin/examples/protobuf-toolchain.html}protobuf-maven-plugin}}>>> | 0.6.1 | github -*-----------------*----------------------------------------------------------------------------------------------+---------------------+----------------+ - -* Using Toolchains in Your Project - - There are two essential components that you need to configure in order to use toolchains: - - [[1]] the <<<{{{/plugins/maven-toolchains-plugin/}maven-toolchains-plugin}}>>> in your project POM, - - [[2]] the <<<{{{/ref/current/maven-core/toolchains.html}toolchains.xml}}>>> file on the building machine. - - [] - - The <<>> is the one that sets the toolchain to be used by the toolchain-aware plugins in your project. - - For example, you want to use a different JDK version to build your project than the version used to run Maven, you can configure - the version you want to use via this plugin as shown in the <<>> below: - -+-----+ - - ... - - org.apache.maven.plugins - maven-compiler-plugin - 3.1 - - - org.apache.maven.plugins - maven-toolchains-plugin - 1.1 - - - - toolchain - - - - - - - 1.8 - openjdk - - - - - ... - -+-----+ - - As you can see in the example above, a JDK toolchain with <<<\>>> "1.8" and <<<\>>> "openjdk" is to be used. Now how - does the plugin know where this JDK is installed? This is where the <<>> file comes in. - - The <<>> file (see below) is the configuration file where you set the installation paths of your toolchains. - This file should be put in the <<<$\{user.home\}/.m2>>> directory. When the <<>> executes, it looks for the <<>> file, - reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In this example, that is a JDK toolchain with - <<<\>>> "1.8" and <<<\>>> "openjdk". Once a match is found, - the plugin then stores the toolchain to be used in the MavenSession. As you can see in the <<>> below, there is indeed a JDK - toolchain with <<<\>>> "1.8" and <<<\>>> "openjdk" configured. So when the <<>> - configured in the <<>> above executes, it sees that a JDK toolchain is set in the MavenSession and will use - that toolchain (that would be the JDK installed at <<>> in this example) to compile the sources. - - Starting with {{{/docs/3.3.1/release-notes.html}Maven 3.3.1}} you can put the <<>> - file wherever you like by using the <<<--global-toolchains file>>> option, but it is recommended to - locate it into <<<$\{user.home\}/.m2/>>>. - - -+-----+ - - - - - jdk - - 1.8 - openjdk - - - /path/to/jdk/1.8 - - - - jdk - - 17 - azul - - - /path/to/jdk/17 - - - - - - netbeans - - 5.5 - - - /path/to/netbeans/5.5 - - - -+-----+ - - You can configure as many toolchains as you want in your <<>> file. diff --git a/content/apt/guides/mini/guide-wagon-providers.apt b/content/apt/guides/mini/guide-wagon-providers.apt deleted file mode 100644 index 642a072dbd..0000000000 --- a/content/apt/guides/mini/guide-wagon-providers.apt +++ /dev/null @@ -1,95 +0,0 @@ - --- - Guide to Selecting Alternative Wagon Providers - --- - John Casey - --- - 2009-07-13 - --- - -~~ 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 - -Guide to Selecting Alternative Wagon Providers - - By default, Maven uses the <<>> (<<>>) classes provided with the JDK to - access repositories that use the HTTP/HTTPs protocols. Unfortunately, since this implementation contains - certain bugs, Maven users may find themselves unable to connect to servers that demand some configurations. - A couple examples of weird behavior include line-wrapping the Authorization header's Base64 value when passwords - are long, and using cached values in preemptive authentication for successive connections to the same server. - - Maven 2.2.0 attempted to amend this problem by switching over to a Wagon implementation that's based on - Apache HttpClient. Unfortunately, it soon became apparent that HttpClient doesn't support NTLM (at least, - version 2), which effectively means users behind NTLMv2 proxies cannot use Maven 2.2.0. - - To hopefully resolve this once and for all, Maven 2.2.1 will contain support for specifying which Wagon - provider you want to use for a given protocol during the build. The provider name will then be appended - to the protocol using the format <<<\-\>>> to form the component role-hint for the Wagon. - - As of Maven 2.2.1, there are two ways to specify which Wagon provider should be used: via the command line, - or in the <<<\>>> configuration section of the <<>>. - -*Command-Line Configuration - - To specify the Wagon provider from the command line, simply use the - <<<-Dmaven.wagon.provider.\=\>>> command-line option, like the following: - ------ -mvn -Dmaven.wagon.provider.http=httpclient clean install ------ - - This instructs Maven to use the HttpClient-based Wagon implementation for connections to HTTP repositories. - -*<<>> Configuration - - To specify which Wagon provider to use for a particular server, modify your <<>> file to add - the <<<\>>> configuration to your <<<\>>> entry, like the following: - -+---+ - - [...] - - - central - - httpclient - [...] - - -+---+ - -*Available Wagon Providers - - Maven 2.2.1 provides two providers for HTTP/HTTPS Wagons: <<>> and <<>>. - If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the - extension binds its Wagon components to role-hints of the form <<<\-\>>> - in order to allow users to specify your alternative Wagon provider. For instance, the HttpClient - HTTP Wagon component definition looks like this: - -+---+ - - org.apache.maven.wagon.Wagon - http-httpclient - org.apache.maven.wagon.providers.http.HttpWagon - per-lookup - -+---+ - - <> The default provider for HTTP/HTTPS Wagons is <<>>. - diff --git a/content/apt/maven-features.apt b/content/apt/maven-features.apt deleted file mode 100644 index 75cda7bd62..0000000000 --- a/content/apt/maven-features.apt +++ /dev/null @@ -1,80 +0,0 @@ - ------ - Maven Features - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Feature Summary - - The following are the key features of Maven in a nutshell: - - * Simple project setup that follows best practices - get a new project or module started in seconds - - * Consistent usage across all projects - means no ramp up time for new developers coming onto a project - - * Superior dependency management including automatic updating, dependency closures (also known as transitive dependencies) - - * Able to easily work with multiple projects at the same time - - * A {{{/repository/}large and growing repository of libraries and metadata}} to use out of the box, and arrangements in place with the largest Open Source projects for - real-time availability of their latest releases - - * Extensible, with the ability to easily {{{/plugin-developers/}write plugins}} in Java or scripting languages - - * Instant access to new features with little or no extra configuration - - * Ant tasks for dependency management and deployment outside of Maven - - * Model based builds: - Maven is able to build any number of projects into predefined output types - such as a JAR, WAR, or distribution based on metadata about the project, without - the need to do any scripting in most cases. - - * Coherent site of project information: - Using the same metadata as for the build process, Maven is able to generate a - web site or PDF including any documentation you care to add, and adds to that - standard reports about the state of development of the project. - Examples of this information can be seen at the bottom of the left-hand navigation of - this site under the "Project Information" and "Project Reports" submenus. - - * Release management and distribution publication: - Without much additional configuration, Maven will integrate with your source control - system (such as Subversion or Git) and manage the release of a project based on a certain tag. - It can also publish this to a distribution location for use by other projects. - Maven is able to publish individual outputs such as a JAR, an archive including other - dependencies and documentation, or as a source distribution. - - * Dependency management: - Maven encourages the use of a central repository of JARs and other dependencies. Maven - comes with a mechanism that your project's clients can use to - download any JARs required for building your project from a - central JAR repository much like Perl's CPAN. This allows users - of Maven to reuse JARs across projects and encourages communication - between projects to ensure that backward compatibility issues are - dealt with. - - [] - -~~ this needs to be greatly expanded and is too detailed here ... jvz diff --git a/content/apt/plugin-developers/common-bugs.apt b/content/apt/plugin-developers/common-bugs.apt deleted file mode 100644 index 983304835e..0000000000 --- a/content/apt/plugin-developers/common-bugs.apt +++ /dev/null @@ -1,457 +0,0 @@ - ------ - Common Bugs and Pitfalls - ------ - Benjamin Bentmann - ------ - 2008-08-29 - ------ - -~~ 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 - -Common Bugs and Pitfalls - - Maven is not the smallest project in terms of source code and has as such already suffered from many bugs. Having a - closer look at all the issues revealed some coding problems that had widespread among the various subcomponents. This - document lists these commonly occurring anti patterns in order to help the Maven community to prevent rather than fix - bugs. Note that the primary focus is on pointing out problems that are subtle in their nature rather than giving a - comprehensive guide for Java or Maven development. - - * {{{Reading_and_Writing_Text_Files}Reading and Writing Text Files}} - - * {{{Converting_between_URLs_and_Filesystem_Paths}Converting between URLs and Filesystem Paths}} - - * {{{Handling_Strings_Case-insensitively}Handling Strings Case-insensitively}} - - * {{{Creating_Resource_Bundle_Families}Creating Resource Bundle Families}} - - * {{{Using_System_Properties}Using System Properties}} - - * {{{Using_Shutdown_Hooks}Using Shutdown Hooks}} - - * {{{Resolving_Relative_Paths}Resolving Relative Paths}} - - * {{{Determining_the_Output_Directory_for_a_Site_Report}Determining the Output Directory for a Site Report}} - - * {{{Retrieving_the_Mojo_Logger}Retrieving the Mojo Logger}} - -* {Reading and Writing Text Files} - - Textual content is composed of characters while file systems merely store byte streams. A file encoding (aka charset) - is used to convert between bytes and characters. The challenge is using the right file encoding. - - The JVM has this notion of a default encoding (given by the <<>> property) which it derives from a - system's locale. While this might be a convenient feature sometimes, using this default encoding for a project build - is in general a bad idea: The build output will depend on the machine/developer who runs the build. As such, usage - of the default encoding threatens the dream of a reproducible build. - - For example, if developer A has UTF-8 as default encoding while developer B uses ISO-8859-1, text files are very - likely to get messed up during resource filtering or similar tasks. - - Therefore, developers should avoid any direct or indirect usage of the classes/methods that simply employ the - platform's default encoding. For instance, <<>> and <<>> should usually be avoided: - -+--- -/* - * FIXME: This assumes the source file is using the platform's default encoding. - */ -Reader reader = new FileReader( javaFile ); -+--- - - Instead, the classes <<>> and <<>> can be used in combination with an - explicit encoding value. This encoding value can be retrieved from a mojo parameter such that the user can configure - the plugin to fit his/her needs. - - To save the user from configuring each plugin individually, conventions have been established that allow a user to - centrally configure the file encoding per POM. Plugin developers should respect these conventions whereever possible: - - * {{{https://cwiki.apache.org/confluence/display/MAVEN/POM+Element+for+Source+File+Encoding}Source File Encoding}} - - * {{{http://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration}Report Output Encoding}} - - [] - - Finally note that XML files require special handling because they are equipped with an encoding declaration in the - XML prolog. Reading or writing XML files with an encoding that does not match their XML prolog's <<>> - attribute is a bad idea: - -+--- -/* - * FIXME: This assumes the XML encoding declaration matches the platform's default encoding. - */ -Writer writer = new FileWriter( xmlFile ); -writer.write( xmlContent ); -+--- - - To ease the correct processing of XML files, developers are encouraged to use - <<<{{{https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/ReaderFactory.html#newXmlReader(java.io.File)}ReaderFactory.newXmlReader()}}>>> - and - <<<{{{https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/WriterFactory.html#newXmlWriter(java.io.File)}WriterFactory.newXmlWriter()}}>>> - from the Plexus Utilities. - -* {Converting between URLs and Filesystem Paths} - - URLs and filesystem paths are really two different things and converting between them is not trivial. The main source - of problems is that different encoding rules apply for the strings that make up a URL or filesystem path. For example, - consider the following code snippet and its associated console output: - -+--- -File file = new File( "foo bar+foo" ); -URL url = file.toURI().toURL(); - -System.out.println( file.toURL() ); -> file:/C:/temp/foo bar+foo - -System.out.println( url ); -> file:/C:/temp/foo%20bar+foo - -System.out.println( url.getPath() ); -> /C:/temp/foo%20bar+foo - -System.out.println( URLDecoder.decode( url.getPath(), "UTF-8" ) ); -> /C:/temp/foo bar foo -+--- - - First of all, please note that - <<<{{{http://java.sun.com/javase/6/docs/api/java/io/File.html#toURL()}File.toURL()}}>>> does not escape the space - character (and others). This yields an invalid URL, as per - {{{http://www.faqs.org/rfcs/rfc2396.html}RFC 2396, section 2.4.3 "Excluded US-ASCII Characters"}}. The class - <<>> will silently accept such invalid URLs, in contrast <<>> will not (see also - <<<{{{http://java.sun.com/javase/6/docs/api/java/net/URL.html#toURI()}URL.toURI()}}>>>). For this reason, - <<>> has been deprecated and should be replaced with <<>>. - - Next, <<<{{{http://java.sun.com/javase/6/docs/api/java/net/URL.html#getPath()}URL.getPath()}}>>> does in general not - return a string that can be used as a filesystem path. It returns a substring of the URL and as such can contain - escape sequences. The prominent example is the space character which will show up as "%20". People sometimes hack - around this by means of <<>> but that does simply not cover all cases. It's worth to mention - that on the other hand the related method - <<<{{{http://java.sun.com/javase/6/docs/api/java/net/URI.html#getPath()}URI.getPath()}}>>> does decode escapes but - still the result is not a filesystem path (compare the source for the constructor <<>>). To summarize, - the following idiom is to be avoided: - -+--- -URL url = new URL( "file:/C:/Program%20Files/Java/bin/java.exe" ); - -/* - * FIXME: This does not decode percent encoded characters. - */ -File path = new File( url.getPath() ); -+--- - - To decode a URL, people sometimes also choose - <<<{{{http://java.sun.com/javase/6/docs/api/java/net/URLDecoder.html}java.net.URLDecoder}}>>>. The pitfall with this - class is that is actually performs HTML form decoding which is yet another encoding and not the same as the URL - encoding (compare the last paragraph in class javadoc about - <<<{{{http://java.sun.com/javase/6/docs/api/java/net/URL.html}java.net.URL}}>>>). For instance, a <<>> - will erroneously convert the character "+" into a space as illustrated by the last sysout in the example above. - - In an ideal world, code targetting JRE 1.4+ could easily avoid these problems by using the constructor - <<<{{{http://java.sun.com/javase/6/docs/api/java/io/File.html#File(java.net.URI)}File(URI)}}>>> as suggested by the - following snippet: - -+--- -URL url = new URL( "file:/C:/Documents and Settings/user/.m2/settings.xml" ); - -/* - * FIXME: This assumes the URL is fully compliant with RFC 3986. - */ -File path = new File( new URI( url.toExternalForm() ) ); -+--- - - The remaining source of frustration is the conversion from <<>> to <<>>. As already said, the <<>> - class accepts malformed URLs which will make the constructor of <<>> throw an exception. And indeed, class - loaders from Sun JREs up to Java 1.4 will deliver malformed URLs when queried for a resource. Likewise, the class - loaders employed by Maven 2.x deliver malformed resource URLs regardless of the JRE version (see - {{{https://issues.apache.org/jira/browse/MNG-3607}MNG-3607}}). - - For all these reasons, it is recommended to use - <<<{{{http://commons.apache.org/io/api-release/org/apache/commons/io/FileUtils.html#toFile(java.net.URL)}FileUtils.toFile()}}>>> - from Commons IO or - <<<{{{https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/FileUtils.html#toFile(java.net.URL)}FileUtils.toFile()}}>>> - from a recent Plexus Utilities. - -* {Handling Strings Case-insensitively} - - When developers need to compare strings without regard to case or want to realize a map with case-insensitive string - keys, they often employ - <<<{{{http://java.sun.com/javase/6/docs/api/java/lang/String.html#toLowerCase()}String.toLowerCase()}}>>> or - <<<{{{http://java.sun.com/javase/6/docs/api/java/lang/String.html#toUpperCase()}String.toUpperCase()}}>>> to create - a "normalized" string before doing a simple <<>>. Now, the <<>> methods are overloaded: - One takes no arguments and one takes a <<>> object. - - The gotcha with the arg-less methods is that their output depends on the default locale of the JVM but the default - locale is out of control of the developer. That means the string expected by the developer (who runs/tests his code - in a JVM using locale <<>>) does not necessarily match the string seen by another user (that runs a JVM with - locale <<>>). For example, the comparison shown in the next code snippet is likely to fail for systems with - default locale Turkish because Turkish has unusual casing rules for the characters "i" and "I": - -+--- -/* - * FIXME: This assumes the casing rules of the current platform - * match the rules for the English locale. - */ -if ( "info".equals( debugLevel.toLowerCase() ) ) - logger.info( message ); -+--- - - For case-insensitive string comparisons which should be locale-insensitive, the method - <<<{{{http://java.sun.com/javase/6/docs/api/java/lang/String.html#equalsIgnoreCase(java.lang.String)}String.equalsIgnoreCase()}}>>> - should be used instead. If only a substring like a prefix/suffix should be compared, the method - <<<{{{http://java.sun.com/javase/6/docs/api/java/lang/String.html#regionMatches(boolean,%20int,%20java.lang.String,%20int,%20int)}String.regionMatches()}}>>> - can be used instead. - - If the usage of <<>> cannot be avoided, the overloaded version taking a <<>> object should - be used, passing in - <<<{{{http://java.sun.com/javase/6/docs/api/java/util/Locale.html#ENGLISH}Locale.ENGLISH}}>>>. The resulting code - will still run on Non-English systems, the parameter only locks down the casing rules used for the string comparison - such that the code delivers the same results on all platforms. - -* {Creating Resource Bundle Families} - - Especially reporting plugins employ resource bundles to support internationalization. One language (usually English) - is provided as the fallback/default language in the base resource bundle. Due to the lookup strategy performed by - <<<{{{http://java.sun.com/javase/6/docs/api/java/util/ResourceBundle.html#getBundle(java.lang.String,%20java.util.Locale,%20java.lang.ClassLoader)}ResourceBundle.getBundle()}}>>>, - one must always provide a dedicated resource bundle for this default language, too. This bundle should be empty - because it inherits the strings via the parent chain from the base bundle, but it must exist. - - The following example illustrates this requirement. Imagine the broken resource bundle family shown below which is - intended to provide localization for English, German and French: - ----- -src/ -+- main/ - +- resources/ - +- mymojo-report.properties - +- mymojo-report_de.properties - +- mymojo-report_fr.properties ----- - - Now, if a resource bundle is to be looked up for English on a JVM whose default locale happens to be French, the - bundle <<>> will be loaded instead of the intended bundle <<>>. - - Reporting plugins that suffer from this bug can easily be detected by executing <<>> where - <<>> denotes any other language code supported by the particular plugin. Specifying <<>> as the first locale - will have the Maven Site Plugin change the JVM's default locale to <<>> which in turn causes the lookup for - <<>> to fail as outlined above unless the plugin has a dedicated resource bundle for English. - -* {Using System Properties} - - Maven's command line supports the definition of system properties via arguments of the form <<<-D key=value>>>. - While these properties are called system properties, plugins should never use - <<<{{{http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String)}System.getProperty()}}>>> - and related methods to query these properties. For example, the following code snippet will not work reliably when - Maven is embedded, say into an IDE or a CI server: - -+--- -public MyMojo extends AbstractMojo -{ - public void execute() - { - /* - * FIXME: This prevents proper embedding into IDEs or CI systems. - */ - String value = System.getProperty( "maven.test.skip" ); - } -} -+--- - - The problem is that the properties managed by the <<>> class are global, i.e. shared among all threads in the - current JVM. To prevent conflicts with other code running in the same JVM, Maven plugins should instead query the - execution properties. These can be obtained from - <<<{{{https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getExecutionProperties()}MavenSession.getExecutionProperties()}}>>>. - -* {Using Shutdown Hooks} - - People occasionally employ shutdown hooks to perform cleanup tasks, e.g. to delete temporary files as shown in the - example below: - -+--- -public MyMojo extends AbstractMojo -{ - public void execute() - { - File tempFile = File.createTempFile( "temp", null ); - /* - * FIXME: This assumes the JVM terminates soon after - * the Maven build has finished. - */ - tempFile.deleteOnExit(); - } -} -+--- - - The problem is that the JVM executing Maven can be running much longer than the actual Maven build. Of course, this - does not apply to the standalone invocation of Maven from the command line. However, it affects the embedded usage of - Maven in IDEs or CI servers. In those cases, the cleanup tasks will be deferred, too. If the JVM is then executing a - bunch of other Maven builds, many such cleanup tasks can sum up, eating up resources of the JVM. - - For this reason, plugin developers should avoid usage of shutdown hooks and rather use <<>>/<<>> blocks - to perform cleanup as soon as the resources are no longer needed. - -* {Resolving Relative Paths} - - It is common practice for users of Maven to specify relative paths in the POM, not to mention that the Super POM does - so, too. The intention is to resolve such relative paths against the base directory of the current project. In other - words, the paths <<>> and <<<$\{project.basedir\}/target/classes>>> should resolve to the same directory for a - given POM. - - Unfortunately, the class <<<{{{http://java.sun.com/javase/6/docs/api/java/io/File.html}java.io.File}}>>> does not - resolve relative paths against the project's base directory. As mentioned in its class javadoc, it resolves relative - paths against the current working directory. In plain English: Unless a Maven component has complete control over the - current working directory, any usage of <<>> in combination with a relative path is a bug. - - At first glance, one might be tempted to argue that the project base directory is equal to the current working - directory. However, this assumption is generally not true. Consider the following scenarios: - - [[a]] Reactor Builds - - When a child module is build during a reactor build, the current working directory is usually the base directory of the - parent project, not the base directory of the current module. That is the most common scenario where users are - faced with the bug. - - [[b]] Embedded Maven Invocations - - Other tools, most notably IDEs, that run Maven under the hood may have set the current working directory to - their installation directory or whatever they like. - - [[c]] Maven Invocations using the <<<-f>>> Switch - - While it is surely an uncommon use-case, the user is free to invoke Maven from an arbitrary working directory - by specifying an absolute path like <<>>. - - [] - - Hence this example code is prone to misbehave: - -+--- -public MyMojo extends AbstractMojo -{ - /** - * @parameter - */ - private String outputDirectory; - - public void execute() - { - /* - * FIXME: This will resolve relative paths like "target/classes" against - * the user's working directory instead of the project's base directory. - */ - File outputDir = new File( outputDirectory ).getAbsoluteFile(); - } -} -+--- - - In order to guarantee reliable builds, Maven and its plugins must manually resolve relative paths against the - project's base directory. A simple idiom like the following will do just fine: - -+--- -File file = new File( path ); -if ( !file.isAbsolute() ) -{ - file = new File( project.getBasedir(), file ); -} -+--- - - Many Maven plugins can get this resolution automatically if they declare their affected mojo parameters of type - <<>> instead of <<>>. This subtle difference in parameter types will trigger a - feature known as , i.e. the Maven core will automatically resolve relative paths when it pumps the - XML configuration into a mojo. - -* {Determining the Output Directory for a Site Report} - - Most reporting plugins inherit from <<>>. In doing so, they need to implement the inherited but - abstract method <<>>. To implement this method, plugins usually declare a field named - <<>> which they return in the method. Nothing wrong so far. - - Now, some plugins need to create additional files in the report output directory that accompany the report generated - via the sink interface. While it is tempting to use either the method <<>> or the field - <<>> directly in order to setup a path for the output files, this leads most likely to a bug. More - precisely, those plugins will not properly output files when run by the Maven Site Plugin as part of the site - lifecycle. This is best noticed when the output directory for the site is configured directly in the Maven Site Plugin - such that it deviates from the expression <<<$\{project.reporting.outputDirectory\}>>> that the plugins use by default. - Multi-language site generation is another scenario to exploit this bug which is illustrated below: - -+--- -public MyReportMojo extends AbstractMavenReport -{ - /** - * @parameter default-value="${project.reporting.outputDirectory}" - */ - private File outputDirectory; - - protected String getOutputDirectory() - { - return outputDirectory.getAbsolutePath(); - } - - public void executeReport( Locale locale ) - { - /* - * FIXME: This assumes the mojo parameter reflects the effective - * output directory as used by the Maven Site Plugin. - */ - outputDirectory.mkdirs(); - } -} -+--- - - There are in principal two situations in which a report mojo could be invoked. The mojo might be run directly from - the command line or the default build lifecycle or it might be run indirectly as part of the site generation along - with other report mojos. The glaring difference between these two invocations is the way the output directory is - controlled. In the first case, the parameter <<>> from the mojo itself is used. In the second case - however, the Maven Site Plugin takes over control and will set the output directory according to its own configuration - by calling <<>> on the reports being generated. - - Therefore, developers should always use <<>> if they need to query the - effective output directory for the report. The implementation of <<>> - is only intended as a fallback in case the mojo is not run as part of the site generation. - -* {Retrieving the Mojo Logger} - - Maven employs an IoC container named Plexus to setup a plugin's mojos before their execution. In other words, - components required by a mojo will be provided by means of dependency injection, more precisely field injection. The - important point to keep in mind is that this field injection happens the mojo's constructor has finished. - This means that references to injected components are invalid during the construction time of the mojo. - - For example, the next snippet tries to retrieve the mojo logger during construction time but the mojo logger is an - injected component and as such has not been properly initialized yet: - -+--- -public MyMojo extends AbstractMojo -{ - /* - * FIXME: This will retrieve a wrong logger instead of the intended mojo logger. - */ - private Log log = getLog(); - - public void execute() - { - log.debug( "..." ); - } -} -+--- - - In case of the logger, the above mojo will simply use a default console logger, i.e. the code defect is not - immediately noticeable by a <<>>. This default logger will however use a different message - format for its output and also outputs debug messages even if Maven's debug mode was not enabled. For this reason, - developers must not try to cache the logger during construction time. The method <<>> is fast enough and - can simply be called whenever one needs it. -+--- diff --git a/content/apt/plugin-developers/cookbook/index.apt b/content/apt/plugin-developers/cookbook/index.apt deleted file mode 100644 index 5c124d0676..0000000000 --- a/content/apt/plugin-developers/cookbook/index.apt +++ /dev/null @@ -1,38 +0,0 @@ - ----- - Plugins Cookbook - ----- - Brett Porter - Vincent Siveton - ----- - 2009-08-02 - ------ - -~~ 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 - -Maven Extensions Cookbook - - Extensions are based on components, defined either with Plexus or JSR-330: - - * {{{./plexus-plugin-upgrade.html}How to upgrade from Plexus javadoc tags to Plexus Java annotations?}} - - * {{{/maven-jsr330.html}Using JSR-330 (instead of Plexus Java annotations)}} - - [] diff --git a/content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt b/content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt deleted file mode 100644 index 5820526d1e..0000000000 --- a/content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt +++ /dev/null @@ -1,189 +0,0 @@ - ----- - Cookbook - How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations - ----- - Hervé Boutemy - ----- - 2012-06-02 - ----- - -~~ 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 - -Cookbook: How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations? - -* Summary - - This recipe describes how to upgrade from Plexus Javadoc Tags to Plexus Java Annotations when defining a Plexus component. - - This is done in 2 steps: - - [[1]] replace the {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}deprecated <<>>}}, - which only supports Plexus Javadoc Tags, with its - {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}successor: <<>>}}, - which support both Plexus Javadoc Tags and Plexus Java Annotations, - - [[2]] update sources with {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/}Java Annotations for Plexus}}. - - [] - - <>: if you're targeting components for Maven 3.1.0+, using {{{/maven-jsr330.html}<<<@Named>>>/<<<@Inject>>> JSR-330 annotations}} - instead of <<<@Component>>>/<<<@Requirement>>> Plexus Java Annotations may be a good next step - -* Prerequisite Plugins - - Here is the list of the plugins used: - -*--------------------------------------------------------------------------------------------------------------+--------------+ -|| <> || <> -*--------------------------------------------------------------------------------------------------------------+--------------+ -| {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}<<>>}} | 1.3.8 -*--------------------------------------------------------------------------------------------------------------+--------------+ -| {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}<<>>}} | 1.7.1 -*--------------------------------------------------------------------------------------------------------------+--------------+ - -* Equivalence Table - -*---------*---------------------------------------------------------------------------------------------------------*--------------* -| || <> || <> -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/}project}} / | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/}project}} / -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/plugin-info.html}plugin info}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/plugin-info.html}plugin info}} -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -|| latest | 1.3.8 | 1.7.1 -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -|| phase | process-sources | process-classes -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -|| goals | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/descriptor-mojo.html}<<>>}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/generate-metadata-mojo.html}<<>>}} -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/merge-descriptors-mojo.html}<<>>}} | see <<>> parameter \ -| | | default: <<<$\{project.basedir}/src/main/resources/META-INF/plexus>>> -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/test-descriptor-mojo.html}<<>>}} | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/generate-test-metadata-mojo.html}<<>>}} -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/test-merge-descriptors-mojo.html}<<>>}} | see <<>> parameter \ -| | | default: <<<$\{project.basedir}/src/test/resources/META-INF/plexus>>> -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -| | {{{https://codehaus-plexus.github.io/plexus-maven-plugin/components-report-mojo.html}<<>>}} | reporting feature not available -*---------+---------------------------------------------------------------------------------------------------------+--------------+ -|| source annotations | javadoc tags: \ -|| | | javadoc tags + {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/}<<>>}} Java 5 annotations:\ -|| | <<<@plexus.component>>>, <<<@plexus.requirement>>>, <<<@plexus.configuration>>> \ -|| | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Component.html}<<<@Component>>>}}, -|| | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Requirement.html}<<<@Requirement>>>}}, -|| | | {{{https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Configuration.html}<<<@Configuration>>>}}, -*---------+---------------------------------------------------------------------------------------------------------+--------------+ - - -* Recipe - -** Plugin Configuration - - In your <<>>, replace <<>> configuration: - -+---------+ - - - - - org.codehaus.plexus - plexus-maven-plugin - 1.3.8 - - - - descriptor - - - - - - -+---------+ - - with corresponding <<>> configuration: - -+---------+ - - - - - org.codehaus.plexus - plexus-component-metadata - 1.7.1 - - - - generate-metadata - - - - - - -+---------+ - - If <<>> is used, move the handwritten xml file to <<<$\{project.basedir}/src/main/resources/META-INF/plexus>>>. - -** Replacing Plexus Javadoc Tags with Plexus Java 5 Annotations - - In your <<>>, add <<>> dependency: - -+---------+ - - - - org.codehaus.plexus - plexus-component-annotations - 1.7.1 - - - -+---------+ - - In your java sources, replace javadoc tags: - -+---------+ -/** - * @plexus.component role="foo.MyComponent" role-hint="hint-value" - */ -public class MyComponentImplementation - implements MyComponent -{ - /** - * @plexus.requirement - */ - private InjectedComponent; -} -+---------+ - - with corresponding Java 5 annotations - -+---------+ -import org.codehaus.plexus.component.annotations.Component; -import org.codehaus.plexus.component.annotations.Requirement; - -@Component( role = MyComponent.class, hint = "hint-value" ) -public class MyComponentImplementation - implements MyComponent -{ - @Requirement - private InjectedComponent; -} -+---------+ diff --git a/content/apt/plugin-developers/index.apt b/content/apt/plugin-developers/index.apt deleted file mode 100644 index 995f77372b..0000000000 --- a/content/apt/plugin-developers/index.apt +++ /dev/null @@ -1,77 +0,0 @@ - ----- - Plugin Developers Centre - ----- - Brett Porter - ----- - 2008-01-01 - ----- - -~~ 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 - -Plugin Developers Centre - - This documentation centre is for those who are developing Maven plugins. This might be for your own build, or as - an accompaniment to your third party tool. - -~~TODO: callout - - <> A mojo is a <>aven plain <>ld <>ava <>bject. Each mojo is an executable in - Maven, and a plugin is a distribution of one or more related mojos. - -~~TODO: tasks as buttons? - - * {{{../guides/introduction/introduction-to-plugins.html} Introduction to Plugin Development}} - Introduction to concepts - - * {{{../guides/plugin/guide-java-plugin-development.html} Your First Mojo}} - Learn how to write your first plugin - - * {{{../guides/plugin/guide-java-report-plugin-development.html} Your First Report Mojo}} - Learn how to write your first reporting plugin - - * {{{./plugin-testing.html} Testing your Plugin}} - How to write tests for your plugins - - * TODO: creating and using custom packaging (like {{{/archetype/archetype-packaging/}<<>> packaging}}) - - * {{{./common-bugs.html} Common Bugs and Pitfalls}} - Overview of problematic coding patterns - - [] - -~~TODO: trails - -* Reference - - * {{{../developers/mojo-api-specification.html} Mojo API and Annotation Reference}} - - * {{{/plugin-tools/maven-plugin-tools-annotations/index.html} Maven Plugin Tools and annotations}} - - * {{{../ref/current/index.html} Maven API Reference}} - - * {{{../guides/mini/guide-maven-classloading.html} Maven Class Loading}} - - [] - -* Extensions - - * {{{../examples/maven-3-lifecycle-extensions.html}Maven 3 lifecycle extensions}} - - * {{{./cookbook/plexus-plugin-upgrade.html}How to upgrade from Plexus javadoc tags to Plexus Java annotations?}} - - * {{{/maven-jsr330.html}Using JSR-330 (instead of Plexus Java annotations)}} - - [] diff --git a/content/apt/plugin-developers/plugin-testing.apt b/content/apt/plugin-developers/plugin-testing.apt deleted file mode 100644 index 958ab5ab82..0000000000 --- a/content/apt/plugin-developers/plugin-testing.apt +++ /dev/null @@ -1,163 +0,0 @@ - ------ - Developers centre - Testing Plugins Strategies - ------ - Vincent Siveton - ------ - 2008-01-01 - 2015-06-16 - ------ - -~~ 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 - -Introduction - - Currently, Maven only supports unit testing out of the box. This document is intended to help Maven Developers - test plugins with unit tests, integration tests, and functional tests. - -~~ <> For a review of different strategies and tools, please refer to {{{http://docs.codehaus.org/display/MAVENUSER/Review+of+Plugin+Testing+Strategies}Review of Plugin Testing Strategies}} - -Testing Styles: Unit Testing vs. Functional/Integration Testing - - A unit test attempts to verify a mojo as an isolated unit, by mocking out the rest of the Maven environment. A mojo unit test does not attempt to run your plugin in the context of a real Maven build. Unit tests are designed to be fast. - - A functional/integration test attempts to use a mojo in a real Maven build, by launching a real instance of Maven in a real project. Normally this requires you to construct special dummy Maven projects with real POM files. Often this requires you to have already installed your plugin into your local repository so it can be used in a real Maven build. Functional tests run much more slowly than unit tests, but they can catch bugs that you may not catch with unit tests. - - The general wisdom is that your code should be mostly tested with unit tests, but should also have some functional tests. - -Unit Tests - -* Using JUnit alone - - In principle, you can write a unit test of a plugin Mojo the same way you'd write any other JUnit test case, by writing a class that <<>>. - - However, most mojos need more information to work properly. For example, you'll probably need to inject a reference to a MavenProject, so your mojo can query project variables. - -* Using PlexusTestCase - - Mojo variables are injected using Plexus, and many Mojos are written to take specific advantage of the Plexus container (by executing a lifecycle or having various injected dependencies). - - If all you need are Plexus container services, you can write your class with <<>> instead of TestCase. - - With that said, if you need to inject Maven objects into your mojo, you'll probably prefer to use the maven-plugin-testing-harness. - -* maven-plugin-testing-harness - - The {{{/plugin-testing/maven-plugin-testing-harness/}maven-plugin-testing-harness}} - is explicitly intended to test the <<>> implementation. - - In general, you need to include <<>> as a dependency, - and create a *MojoTest (by convention) class which <<>>. - -+-----+ -... - - ... - - org.apache.maven.plugin-testing - maven-plugin-testing-harness - 3.3.0 - test - - ... - -... -+-----+ -+-----+ -public class YourMojoTest - extends AbstractMojoTestCase -{ - /** - * @see junit.framework.TestCase#setUp() - */ - protected void setUp() throws Exception - { - // required for mojo lookups to work - super.setUp(); - } - - /** - * @throws Exception - */ - public void testMojoGoal() throws Exception - { - File testPom = new File( getBasedir(), - "src/test/resources/unit/basic-test/basic-test-plugin-config.xml" ); - - YourMojo mojo = (YourMojo) lookupMojo( "yourGoal", testPom ); - - assertNotNull( mojo ); - } -} -+-----+ - - For more information, refer to {{{http://cwiki.apache.org/confluence/display/MAVENOLD/Maven+Plugin+Harness}Maven Plugin Harness Wiki}} - -Integration/Functional testing - -* maven-verifier - - maven-verifier tests are run using JUnit or TestNG, and provide a simple class allowing you to launch Maven and assert on its log file and built artifacts. It also provides a ResourceExtractor, which extracts a Maven project from your src/test/resources directory into a temporary working directory where you can do tricky stuff with it. Follow the {{{/shared/maven-verifier/getting-started.html}Getting Started}} guide to learn more about creating maven-verifier tests. - - Maven itself uses maven-verifier to run its core integration tests. For more information, please refer to {{{https://cwiki.apache.org/confluence/display/MAVEN/Creating+a+Maven+Integration+Test}Creating a Maven Integration Test}}. - - <>: maven-verifier and maven-verifier-plugin sound similar, but are totally different unrelated pieces of code. maven-verifier-plugin simply verifies the existence/absence of files on the filesystem. You could use it for functional testing, but you may need more features than maven-verifier-plugin provides. - -* maven-invoker-plugin - - You can use {{{https://maven.apache.org/plugins/maven-invoker-plugin/}maven-invoker-plugin}} - to invoke Maven and to provide some BeanShell/Groovy tests. Tests written in - this way don't run under JUnit/TestNG; instead, they're run by Maven itself. - - You can take a look at the {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-install-plugin/src/it/}maven-install-plugin}} - how there are integration tests are written. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-invoker-plugin - 1.10 - - src/it - - **/pom.xml - - verify - - - - - run - - - - - ... - - - ... - -+-----+ - diff --git a/content/apt/plugins/index.apt b/content/apt/plugins/index.apt deleted file mode 100644 index e93408115d..0000000000 --- a/content/apt/plugins/index.apt +++ /dev/null @@ -1,278 +0,0 @@ - ----- - Available Plugins - ----- - Brett Porter - Jason van Zyl - Dennis Lundberg - Olivier Lamy - Benson Margulies - Karl-Heinz Marbaise - ----- - 2017-05-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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Available Plugins - - Maven is - at its heart - a plugin execution framework; all work is done by plugins. Looking for - a specific goal to execute? This page lists the core plugins and others. There are the build and the reporting - plugins: - - * <> will be executed during the build and they should be configured in the <<<\>>> - element from the POM. - - * <> will be executed during the site generation and they should be configured in the - <<<\>>> element from the POM. Because the result of a Reporting plugin is part of the generated site, - Reporting plugins should be both internationalized and localized. You can read more about the - {{{./localization.html}localization of our plugins}} and how you can help. - - [] - -* Supported By The Maven Project - - To see the most up-to-date list browse the Maven repository, specifically - the {{{https://repo.maven.apache.org/maven2/org/apache/maven/plugins/} <<>>}} subdirectory. - <(Plugins are organized according to a directory structure that resembles the standard Java package naming convention)> - - ~~ TODO: the repository manager should be able to produce a page like this. Ensure all descriptions are in the POM of these plugins. - - -~~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -~~ The release dates in this table must follow the ISO-8601 standard: yyyy-MM-dd -~~ See https://maven.apache.org/guides/development/guide-documentation-style.html -~~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -|| <> || <> || <> || <> || <> || <> || <> -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| <> | | | | <> | | -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-clean-plugin/} <<>>}} | B | 3.4.0 | 2024-06-16 | Clean up after the build. | {{{https://gitbox.apache.org/repos/asf/maven-clean-plugin.git}Git}} / {{{https://github.com/apache/maven-clean-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MCLEAN}Jira MCLEAN}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-compiler-plugin/} <<>>}} | B | 3.13.0 | 2024-03-15 | Compiles Java sources. | {{{https://gitbox.apache.org/repos/asf/maven-compiler-plugin.git}Git}} / {{{https://github.com/apache/maven-compiler-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MCOMPILER}Jira MCOMPILER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-deploy-plugin/} <<>>}} | B | 3.1.3 | 2024-08-19 | Deploy the built artifact to the remote repository. | {{{https://gitbox.apache.org/repos/asf/maven-deploy-plugin.git}Git}} / {{{https://github.com/apache/maven-deploy-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MDEPLOY}Jira MDEPLOY}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/surefire/maven-failsafe-plugin/} <<>>}} | B | 3.5.1 | 2024-10-01 | Run the JUnit integration tests in an isolated classloader. | {{{https://gitbox.apache.org/repos/asf/maven-surefire.git}Git}} / {{{https://github.com/apache/maven-surefire/}GitHub}} | {{{https://issues.apache.org/jira/browse/SUREFIRE}Jira SUREFIRE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-install-plugin/} <<>>}} | B | 3.1.3 | 2024-08-19 | Install the built artifact into the local repository. | {{{https://gitbox.apache.org/repos/asf/maven-install-plugin.git}Git}} / {{{https://github.com/apache/maven-install-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MINSTALL}Jira MINSTALL}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-resources-plugin/} <<>>}} | B | 3.3.1 | 2023-03-21 | Copy the resources to the output directory for including in the JAR. | {{{https://gitbox.apache.org/repos/asf/maven-resources-plugin.git}Git}} / {{{https://github.com/apache/maven-resources-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MRESOURCES}Jira MRESOURCES}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-site-plugin/} <<>>}} | B | 3.21.0 | 2024-10-18 | Generate a site for the current project. | {{{https://gitbox.apache.org/repos/asf/maven-site-plugin.git}Git}} / {{{https://github.com/apache/maven-site-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSITE}Jira MSITE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/surefire/maven-surefire-plugin/} <<>>}} | B | 3.5.1 | 2024-10-01 | Run the JUnit unit tests in an isolated classloader. | {{{https://gitbox.apache.org/repos/asf/maven-surefire.git}Git}} / {{{https://github.com/apache/maven-surefire/}GitHub}} | {{{https://issues.apache.org/jira/browse/SUREFIRE}Jira SUREFIRE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-verifier-plugin/} <<>>}} | B | 1.1 | 2015-04-14 | Useful for integration tests - verifies the existence of certain conditions. | {{{https://gitbox.apache.org/repos/asf/maven-verifier-plugin.git}Git}} / {{{https://github.com/apache/maven-verifier-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MVERIFIER}Jira MVERIFIER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| <> | | | | <> | | -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-ear-plugin/} <<>>}} | B | 3.3.0 | 2022-10-18 | Generate an EAR from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-ear-plugin.git}Git}} / {{{https://github.com/apache/maven-ear-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MEAR}Jira MEAR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-ejb-plugin/} <<>>}} | B | 3.2.1 | 2022-04-18 | Build an EJB (and optional client) from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-ejb-plugin.git}Git}} / {{{https://github.com/apache/maven-ejb-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MEJB}Jira MEJB}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jar-plugin/} <<>>}} | B | 3.4.2 | 2024-06-16 | Build a JAR from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-jar-plugin.git}Git}} / {{{https://github.com/apache/maven-jar-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJAR}Jira MJAR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-rar-plugin/} <<>>}} | B | 3.0.0 | 2022-07-17 | Build a RAR from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-rar-plugin.git}Git}} / {{{https://github.com/apache/maven-rar-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MRAR}Jira MRAR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-war-plugin/} <<>>}} | B | 3.4.0 | 2023-06-11 | Build a WAR from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-war-plugin.git}Git}} / {{{https://github.com/apache/maven-war-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MWAR}Jira MWAR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-acr-plugin/} <<>>}} | B | 3.1.0 | 2018-06-19 | Build a JavaEE application client from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-acr-plugin.git}Git}} / {{{https://github.com/apache/maven-acr-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MACR}Jira MACR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-shade-plugin/} <<>>}} | B | 3.6.0 | 2024-05-31 | Build an Uber-JAR from the current project, including dependencies. | {{{https://gitbox.apache.org/repos/asf/maven-shade-plugin.git}Git}} / {{{https://github.com/apache/maven-shade-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSHADE}Jira MSHADE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-source-plugin/} <<>>}} | B | 3.3.1 | 2024-04-02 | Build a source-JAR from the current project. | {{{https://gitbox.apache.org/repos/asf/maven-source-plugin.git}Git}} / {{{https://github.com/apache/maven-source-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSOURCES}Jira MSOURCES}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jlink-plugin/} <<>>}} | B | 3.2.0 | 2024-02-01 | Build Java Run Time Image. | {{{https://gitbox.apache.org/repos/asf/maven-jlink-plugin.git}Git}} / {{{https://github.com/apache/maven-jlink-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJLINK}Jira MJLINK}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jmod-plugin/} <<>>}} | B | 3.0.0-alpha-1 | 2017-09-17 | Build Java JMod files. | {{{https://gitbox.apache.org/repos/asf/maven-jmod-plugin.git}Git}} / {{{https://github.com/apache/maven-jmod-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJMOD}Jira MJMOD}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| <> | | | | <> | | -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-changelog-plugin/} <<>>}} | R | 2.3 | 2014-06-24 | Generate a list of recent changes from your SCM. | {{{https://gitbox.apache.org/repos/asf/maven-changelog-plugin.git}Git}} / {{{https://github.com/apache/maven-changelog-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MCHANGELOG}Jira MCHANGELOG}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-changes-plugin/} <<>>}} | B+R | 2.12.1 | 2016-11-01 | Generate a report from an issue tracker or a change document. | {{{https://gitbox.apache.org/repos/asf/maven-changes-plugin.git}Git}} / {{{https://github.com/apache/maven-changes-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MCHANGES}Jira MCHANGES}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-checkstyle-plugin/} <<>>}} | B+R | 3.6.0 | 2024-10-22 | Generate a Checkstyle report. | {{{https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git}Git}} / {{{https://github.com/apache/maven-checkstyle-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MCHECKSTYLE}Jira MCHECKSTYLE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-doap-plugin/} <<>>}} | B | 1.2 | 2015-03-17 | Generate a Description of a Project (DOAP) file from a POM. | {{{https://gitbox.apache.org/repos/asf/maven-doap-plugin.git}Git}} / {{{https://github.com/apache/maven-doap-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MDOAP}Jira MDOAP}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-javadoc-plugin/} <<>>}} | B+R | 3.10.1 | 2024-09-26 | Generate Javadoc for the project. | {{{https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git}Git}} / {{{https://github.com/apache/maven-javadoc-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJAVADOC}Jira MJAVADOC}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jdeps-plugin/} <<>>}} | B | 3.1.2 | 2019-06-12 | Run JDK's JDeps tool on the project. | {{{https://gitbox.apache.org/repos/asf/maven-jdeps-plugin.git}Git}} / {{{https://github.com/apache/maven-jdeps-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJDEPS}Jira MJDEPS}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/jxr/maven-jxr-plugin/} <<>>}} | R | 3.6.0 | 2024-10-22 | Generate a source cross reference. | {{{https://gitbox.apache.org/repos/asf/maven-jxr.git}Git}} / {{{https://github.com/apache/maven-jxr/}GitHub}} | {{{https://issues.apache.org/jira/browse/JXR}Jira JXR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-linkcheck-plugin/} <<>>}} | R | 1.2 | 2014-10-08 | Generate a Linkcheck report of your project's documentation. | {{{https://gitbox.apache.org/repos/asf/maven-linkcheck-plugin.git}Git}} / {{{https://github.com/apache/maven-linkcheck-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MLINKCHECK}Jira MLINKCHECK}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-pmd-plugin/} <<>>}} | B+R | 3.25.0 | 2024-08-22 | Generate a PMD report. | {{{https://gitbox.apache.org/repos/asf/maven-pmd-plugin.git}Git}} / {{{https://github.com/apache/maven-pmd-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPMD}Jira MPMD}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugin-tools/maven-plugin-report-plugin/} <<>>}} | R | 3.15.1 | 2024-10-22 | Create a plugin documentation for any mojos found in the source tree. | {{{https://gitbox.apache.org/repos/asf/maven-plugin-tools.git}Git}} / {{{https://github.com/apache/maven-plugin-tools/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPLUGIN}Jira MPLUGIN}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-project-info-reports-plugin/} <<>>}} | R | 3.8.0 | 2024-10-18 | Generate standard project reports. | {{{https://gitbox.apache.org/repos/asf/maven-project-info-reports-plugin.git}Git}} / {{{https://github.com/apache/maven-project-info-reports-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPIR}Jira MPIR}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/surefire/maven-surefire-report-plugin/} <<>>}} | R | 3.5.1 | 2024-10-01 | Generate a report based on the results of unit tests. | {{{https://gitbox.apache.org/repos/asf/maven-surefire.git}Git}} / {{{https://github.com/apache/maven-surefire/}GitHub}} | {{{https://issues.apache.org/jira/browse/SUREFIRE}Jira SUREFIRE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| <> | | | | <> | | -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-antrun-plugin/} <<>>}} | B | 3.1.0 | 2022-04-18 | Run a set of ant tasks from a phase of the build. | {{{https://gitbox.apache.org/repos/asf/maven-antrun-plugin.git}Git}} / {{{https://github.com/apache/maven-antrun-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MANTRUN}Jira MANTRUN}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-artifact-plugin/} <<>>}} | B | 3.5.2 | 2024-10-15 | Manage artifacts tasks like buildinfo. | {{{https://gitbox.apache.org/repos/asf/maven-artifact-plugin.git}Git}} / {{{https://github.com/apache/maven-artifact-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MARTIFACT}Jira MARTIFACT}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/archetype/maven-archetype-plugin/} <<>>}} | B | 3.3.1 | 2024-10-25 | Generate a skeleton project structure from an archetype. | {{{https://gitbox.apache.org/repos/asf/maven-archetype.git}Git}} / {{{https://github.com/apache/maven-archetype/}GitHub}} | {{{https://issues.apache.org/jira/browse/ARCHETYPE}Jira ARCHETYPE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-assembly-plugin/} <<>>}} | B | 3.7.1 | 2024-03-15 | Build an assembly (distribution) of sources and/or binaries. | {{{https://gitbox.apache.org/repos/asf/maven-assembly-plugin.git}Git}} / {{{https://github.com/apache/maven-assembly-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MASSEMBLY}Jira MASSEMBLY}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-dependency-plugin/} <<>>}} | B+R | 3.8.1 | 2024-10-18 | Dependency manipulation (copy, unpack) and analysis. | {{{https://gitbox.apache.org/repos/asf/maven-dependency-plugin.git}Git}} / {{{https://github.com/apache/maven-dependency-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MDEP}Jira MDEP}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/enforcer/maven-enforcer-plugin/} <<>>}} | B | 3.5.0 | 2024-05-26 | Environmental constraint checking (Maven Version, JDK etc), User Custom Rule Execution. | {{{https://gitbox.apache.org/repos/asf/maven-enforcer.git}Git}} / {{{https://github.com/apache/maven-enforcer/}GitHub}} | {{{https://issues.apache.org/jira/browse/MENFORCER}Jira MENFORCER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-gpg-plugin/} <<>>}} | B | 3.2.7 | 2024-09-24 | Create signatures for the artifacts and poms. | {{{https://gitbox.apache.org/repos/asf/maven-gpg-plugin.git}Git}} / {{{https://github.com/apache/maven-gpg-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MGPG}Jira MGPG}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-help-plugin/} <<>>}} | B | 3.5.1 | 2024-10-18 | Get information about the working environment for the project. | {{{https://gitbox.apache.org/repos/asf/maven-help-plugin.git}Git}} / {{{https://github.com/apache/maven-help-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPH}Jira MPH}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-invoker-plugin/} <<>>}} | B+R | 3.8.1 | 2024-10-18 | Run a set of Maven projects and verify the output. | {{{https://gitbox.apache.org/repos/asf/maven-invoker-plugin.git}Git}} / {{{https://github.com/apache/maven-invoker-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MINVOKER}Jira MINVOKER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jarsigner-plugin/} <<>>}} | B | 3.1.0 | 2024-09-03 | Signs or verifies project artifacts. | {{{https://gitbox.apache.org/repos/asf/maven-jarsigner-plugin.git}Git}} / {{{https://github.com/apache/maven-jarsigner-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJARSIGNER}Jira MJARSIGNER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-jdeprscan-plugin/} <<>>}} | B | 3.0.0-alpha-1| 2017-11-15 | Run JDK's JDeprScan tool on the project. | {{{https://gitbox.apache.org/repos/asf/maven-jdeprscan-plugin.git}Git}} / {{{https://github.com/apache/maven-jdeprscan-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MJDEPRSCAN}Jira MJDEPRSCAN}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-patch-plugin/} <<>>}} | B | 1.2 | 2015-03-09 | Use the gnu patch tool to apply patch files to source code. | {{{https://gitbox.apache.org/repos/asf/maven-patch-plugin.git}Git}} / {{{https://github.com/apache/maven-patch-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPATCH}Jira MPATCH}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-pdf-plugin/} <<>>}} | B | 1.6.1 | 2022-08-16 | Generate a PDF version of your project's documentation. | {{{https://gitbox.apache.org/repos/asf/maven-pdf-plugin.git}Git}} / {{{https://github.com/apache/maven-pdf-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPDF}Jira MPDF}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugin-tools/maven-plugin-plugin/} <<>>}} | B | 3.15.1 | 2024-10-22 | Create a Maven plugin descriptor for any mojos found in the source tree, to include in the JAR. | {{{https://gitbox.apache.org/repos/asf/maven-plugin-tools.git}Git}} / {{{https://github.com/apache/maven-plugin-tools/}GitHub}} | {{{https://issues.apache.org/jira/browse/MPLUGIN}Jira MPLUGIN}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-release-plugin/} <<>>}} | B | 3.1.1 | 2024-07-11 | Release the current project - updating the POM and tagging in the SCM. | {{{https://gitbox.apache.org/repos/asf/maven-release.git}Git}} / {{{https://github.com/apache/maven-release/}GitHub}} | {{{https://issues.apache.org/jira/browse/MRELEASE}Jira MRELEASE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-remote-resources-plugin/} <<>>}}| B | 3.2.0 | 2024-03-03 | Copy remote resources to the output directory for inclusion in the artifact. | {{{https://gitbox.apache.org/repos/asf/maven-remote-resources-plugin.git}Git}} / {{{https://github.com/apache/maven-remote-resources-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MRRESOURCES}Jira MRRESOURCES}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/scm/maven-scm-plugin/} <<>>}} | B | 2.1.0 | 2024-04-14 | Execute SCM commands for the current project. | {{{https://gitbox.apache.org/repos/asf/maven-scm.git }Git}} / {{{https://github.com/apache/maven-scm/}GitHub}} | {{{https://issues.apache.org/jira/browse/SCM}Jira SCM}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-scm-publish-plugin/} <<>>}} | B | 3.3.0 | 2024-06-16 | Publish your Maven website to a scm location. | {{{https://gitbox.apache.org/repos/asf/maven-scm-publish-plugin.git}Git}} / {{{https://github.com/apache/maven-scm-publish-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSCMPUB}Jira MSCMPUB}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-scripting-plugin/} <<>>}} | B | 3.0.0 | 2021-03-01 | The Maven Scripting Plugin wraps the Scripting API according to JSR223. | {{{https://gitbox.apache.org/repos/asf/maven-scripting-plugin.git}Git}} / {{{https://github.com/apache/maven-scripting-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSCRIPTING}Jira MSCRIPTING}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-stage-plugin/} <<>>}} | B | 1.0 | 2015-03-03 | Assists with release staging and promotion. | {{{https://gitbox.apache.org/repos/asf/maven-stage-plugin.git}Git}} / {{{https://github.com/apache/maven-stage-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MSTAGE}Jira MSTAGE}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-toolchains-plugin/} <<>>}} | B | 3.2.0 | 2024-04-21 | Allows to share configuration across plugins. | {{{https://gitbox.apache.org/repos/asf/maven-toolchains-plugin.git}Git}} / {{{https://github.com/apache/maven-toolchains-plugin/}GitHub}} | {{{https://issues.apache.org/jira/browse/MTOOLCHAINS}Jira MTOOLCHAINS}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ -| {{{/plugins/maven-wrapper-plugin/} <<>>}} | B | 3.3.2 | 2024-05-24 | Download and unpack the maven wrapper distribution | {{{https://gitbox.apache.org/repos/asf/maven-wrapper-plugin.git}Git}} / {{{https://github.com/apache/maven-wrapper/}GitHub}} | {{{https://issues.apache.org/jira/browse/MWRAPPER}Jira MWRAPPER}} -*--------------------------------------------------------------+------------+--------------+------------+------------------+------------------------+--------------------+ - - \* <>uild or <>eporting plugin - - There are also some sandbox plugins into our {{{https://svn.apache.org/repos/asf/maven/sandbox/trunk/plugins}source repository}}. - - Previous archived versions of plugins reference documentations are {{{../plugins-archives/}located here}}. - -* Retired - -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -|| <> || <> || <> || <> || <> -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-ant-plugin/} <<>>}} | B | 2.4 | 2019-06-02 | Generate an Ant build file for the project. -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-docck-plugin/} <<>>}} | B | 1.2 | 2023-10-22 | Documentation checker plugin. -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-eclipse-plugin/} <<>>}} | B | 2.10 | 2015-10-07 | Generate an Eclipse project files for the current project. -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-idea-plugin/} <<>>}} | B | 2.2.1 | 2013-07-26 | Create/update an IDEA workspace for the current project (individual modules are created as IDEA modules) -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-one-plugin/} <<>>}} | B | 1.3 | 2013-07-30 | A plugin for interacting with legacy Maven 1.x repositories and builds. -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-reactor-plugin/} <<>>}} | B | 1.1 | 2014-03-24 | Build a subset of interdependent projects in a reactor (Maven 2 only). -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ -| {{{/plugins/maven-repository-plugin/} <<>>}} | B | 2.4 | 2019-04-30 | Plugin to help with repository-based tasks. -*--------------------------------------------------------------+------------+--------------+-------------------+------------------+ - -* Outside The Maven Land - -** At MojoHaus (formerly known as {codehaus.org}) - - There are also {{{https://www.mojohaus.org/plugins.html}many plug-ins}} available at - the {{{https://github.com/mojohaus} MojoHaus}} project at GitHub. - - Here are a few common ones: - -*---------------------------------------------------------------------------------+----------------------------------+ -|| <> (see {{{https://www.mojohaus.org/plugins.html}complete list with version}}) || <> -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/} <<>>}}| Build signatures of APIs (JDK for example) and checks your classes against them. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/build-helper-maven-plugin/} <<>>}} | Attach extra artifacts and source directories to build. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/buildplan-maven-plugin/} <<>>}} | Inspect the lifecycle of your build. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/castor-maven-plugin/} <<>>}} | Generate sources from an XSD using Castor. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/clirr-maven-plugin/} <<>>}} | Compare binaries or sources for compatibility using Clirr | -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/javacc-maven-plugin/} <<>>}} | Generate sources from a JavaCC grammar. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/jdepend-maven-plugin/} <<>>}} | Generate a report on code metrics using JDepend. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://maven-nar.github.io/} <<>>}} | Compiles C, C++, Fortran for different architectures. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/maven-native/native-maven-plugin/} <<>>}} | Compiles C and C++ code with native compilers. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/sql-maven-plugin/} <<>>}} | Executes SQL scripts from files or inline. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/taglist-maven-plugin/} <<>>}} | Generate a list of tasks based on tags in your code. -*---------------------------------------------------------------------------------+----------------------------------+ -| {{{https://www.mojohaus.org/versions-maven-plugin/} <<>>}} | Manage versions of your project, its modules, dependencies and plugins. -*---------------------------------------------------------------------------------+----------------------------------+ - -** Misc - - A number of other projects provide their own Maven plugins. This includes: - -*----------------------------------------------------------------------------+----------------+-----------------------+ -|| <> || <> || <> -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://codehaus-cargo.github.io/} <<>>}} | {{{https://codehaus-cargo.github.io/}Cargo Project}} | Start/stop/configure J2EE containers and deploy to them. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://confluence.atlassian.com/display/CLOVER/Clover-for-Maven+2} <<>>}} | {{{https://www.atlassian.com/software/clover/}Atlassian Clover}} | Generate a Clover report. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://www.eclipse.org/jetty/documentation/current/jetty-maven-plugin.html} <<>>}}| {{{https://www.eclipse.org/jetty/}Jetty Project}} | Jetty Run a Jetty container for rapid webapp development. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{http://www.triemax.com/products/jalopy/manual/plugin-maven.html} <<>>}} | {{{http://www.triemax.com/}Triemax}} | Use Jalopy to format your source code. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://creadur.apache.org/rat/} <<>>}} | {{{https://creadur.apache.org/}Apache Creadur Project}} | Release Audit Tool (RAT) to verify files. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://geronimo.apache.org/maven/genesis/plugins/tools-maven-plugin/index.html} <<>>}} | {{{https://geronimo.apache.org/}Apache Geronimo Project}} | Verify legal files in artifacts. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://tomcat.apache.org/maven-plugin.html} <<>>}}| {{{https://tomcat.apache.org/maven-plugin.html}Apache Tomcat Project}} | Run an Apache Tomcat container for rapid webapp development. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://jeremylong.github.io/DependencyCheck/} <<>>}} | {{{https://www.owasp.org/index.php/OWASP_Dependency_Check}OWASP Dependency-check Project}} | Run OWASP Dependency-Check, a utility that identifies project dependencies and checks if there are any known, publicly disclosed, vulnerabilities. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://github.com/CycloneDX/cyclonedx-maven-plugin} <<>>}} | {{{https://cyclonedx.org/}CycloneDX Project}} | Generate Software Bill of Materials (SBOM) in CycloneDX format. -*----------------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://www.simplify4u.org/pgpverify-maven-plugin/} <<>>}} | {{{https://www.simplify4u.org/}Simplify4U}} | Verify PGP signature of all project dependencies. -*----------------------------------------------------------------------------+----------------+-----------------------+ - -* Resources - - [[1]] {{{../guides/mini/guide-configuring-plugins.html}Guide to Configuring Plugins}} - - [] diff --git a/content/apt/plugins/localization.apt b/content/apt/plugins/localization.apt deleted file mode 100644 index e3e0ae944d..0000000000 --- a/content/apt/plugins/localization.apt +++ /dev/null @@ -1,193 +0,0 @@ - ----- - Localization of Plugins - ----- - Dennis Lundberg - Vincent Siveton - ----- - 2012-03-12 - ----- - -~~ 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 - -Localization of Plugins - - Most of the plugins involved with the site generation are fully - internationalized. This means that adapting them to another language, a - process known as localization, is very easy. All that is needed is to download - a couple of properties files and start translating the texts in them. If you - want to provide a patch for an unsupported language, there are detailed - instructions below. - - For the basic site generation there are currently files for three components - that needs to be localized to support a new language: Maven Site Plugin, Maven - Project Info Reports Plugin and Maven Doxia Tools. - - <> The links to SVN below goes to the latest development code. So the - files may be newer than the ones included in the latest release. - - In the table below you can see our localized plugins and which languages they - are available in. - -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -|| Plugin || ca || cs || da || de || es || fr || gl || hu || it || ja || ko || lt || nl || no || pl || pt || pt_BR || ru || sk || sv || tr || zh_CN || zh_TW || l10n report || SVN -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Changelog | - | - | - | OK | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | OK | - | - | - | {{{/plugins/maven-changelog-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-changelog-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Changes | - | - | - | OK | - | OK | - | - | - | - | - | - | - | - | - | - | OK | - | - | OK | - | - | - | {{{/plugins/maven-changes-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-changes-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Checkstyle | - | - | - | OK | - | OK | - | - | - | - | - | - | - | - | - | - | OK | - | - | OK | - | - | - | {{{/plugins/maven-checkstyle-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-checkstyle-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Dependency | - | - | - | OK | - | - | - | - | - | - | - | - | - | - | - | - | OK | - | - | OK | - | - | - | {{{/plugins/maven-dependency-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-dependency-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| DOAP | - | - | - | OK | OK | OK | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | {{{/plugins/maven-doap-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-doap-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Doxia Integration Tools | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | {{{/doxia/doxia-tools/doxia-integration-tools/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/doxia/doxia-sitetools/trunk/doxia-integration-tools/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Javadoc | - | - | - | OK | - | OK | - | - | - | - | - | - | OK | - | - | - | - | - | - | OK | - | - | - | {{{/plugins/maven-javadoc-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-javadoc-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| JXR | - | - | - | OK | - | OK | - | - | - | - | - | - | - | - | - | - | - | - | - | OK | - | - | - | {{{/plugins/maven-jxr-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/jxr/trunk/maven-jxr-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| PMD | - | - | - | OK | - | OK | - | - | OK | - | - | - | OK | - | - | - | OK | - | - | OK | - | - | - | {{{/plugins/maven-pmd-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-pmd-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Plugin | - | - | - | OK | - | OK | - | - | - | - | - | - | - | - | - | - | - | - | - | OK | - | - | - | {{{/plugins/maven-plugin-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Project Info Reports | - | OK | - | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | {{{/plugins/maven-project-info-reports-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-project-info-reports-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Surefire report | - | - | - | OK | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | OK | - | - | - | {{{/plugins/maven-surefire-report-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/surefire/trunk/maven-surefire-report-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ -| Site | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | {{{/plugins/maven-site-plugin/l10n-status.html}l10n report}} | {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-site-plugin/src/main/resources/}SVN}} -*----------------------+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+--------+-----+-----+-----+-----+--------+--------+------------------------------------------------------------------------------+------+ - - Is your favourite plugin missing a localization for your language? Please help - us expand the language support by following the instructions below. - - -* Localizing a Plugin - - * Check out the source code for the plugin you want to add a translation to. - - * Find the resource bundles that needs to be translated. They are often found - in the <<>> directory. - - * Copy the basefile for the bundle, i.e. the one <> a language - extension. The copy should have the same name as the original file, except - for the addition of a language extension. If, for example, you want to - translate the Checkstyle Plugin into Spanish, you would copy - <<>> to - <<>>. - - * Edit the new file and translate all the properties. Do not change the - formating of the file, i.e. keep the current indentation and line breaks. - This makes it easy to use a graphical diff tool to find missing keys in the - file. - - * Convert the new file so that all non-US-ASCII characters are transformed - into Unicode escapes, see below for a tool that can help with this. - - * Run "mvn install" for the plugin. - - * Configure a project to use the latest SNAPSHOT version of the plugin you are - working on. Also configure the project to produce a site in the language you - are adding a translation for. For Spanish, as we used in the example above, - it would look like this: - -+----- - - - - org.apache.maven.plugins - maven-site-plugin - - es - - - - -+----- - - * Run "mvn site" on that project to test it. - - * When you are happy with your translation, create an issue in JIRA for the - plugin in question, with a description like this: - "Add Spanish translation". Take note of the issue number. - - * Create a patch file that contains your new translation. Use the issue number - when you name the file: - ------- -svn diff > MYISSUE-123.patch ------- - - * Attach your patch file to the issue in JIRA. - - [] - - -* Tools - - There is a command line tool called <> that can be used to - convert a text file to use Unicode-encoded characters instead of - native-encoded characters. This is part of the Java SDK and you can - {{{http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/native2ascii.html}read more about it here}}. - You use it like this: - ------- -native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.properties ------- - -** Tools to find out the charset of a file - - * Unix <<>> command - - * {{{http://cpdetector.sourceforge.net/}cpdetector}} - - * {{{http://plugins.intellij.net/plugin/?id=24}IntelliJ IDEA ShowEncodingPlugin}} - - * {{{http://notepad-plus.sourceforge.net/}Notepad++}} - - [] - -** Tools to write a file in a given charset - - Any editor like Notepad++, Eclipse, IntelliJ IDEA, ... - -** Tools to convert a file from one encoding to another encoding - - * Unix <<>> command - - * Notepad++ - - [] - -** IDE plugins - - * {{{http://propedit.sourceforge.jp/index_en.html}Properties Editor Eclipse Plugin}} - - [] - -* References - - Please refer to the - {{{http://java.sun.com/javase/technologies/core/basic/intl/}Java Internationalization home page}} - for an introduction to the topic. - - You can also refer to this Sun FAQ: - {{{http://developers.sun.com/global/technology/standards/reference/faqs/determining-file-encoding.html}How Can I Determine the Encoding of a File?}} diff --git a/content/apt/repository/central-index.apt b/content/apt/repository/central-index.apt deleted file mode 100644 index 186f1c1898..0000000000 --- a/content/apt/repository/central-index.apt +++ /dev/null @@ -1,66 +0,0 @@ - ----- - Central Index - ----- - Hervé Boutemy - ----- - 2017-04-23 - ----- - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Central Index - - Central repository provides {{{https://repo.maven.apache.org/maven2/.index/}an index in <<>>}}: - - * full index (<<>>) is updated weekly, - - * incremental index (<<.gz>>> + <<>>). - - This index is build using {{{/maven-indexer/}Maven Indexer}}: see {{{/maven-indexer/indexer-core/}indexer-core documentation}} for more - details on the fields that are available. - - You can use {{{/maven-indexer/indexer-core/apidocs/}Maven Indexer API}} (see {{{/maven-indexer/indexer-examples/}examples}}) to use - this index with a dedicated API, or use {{{https://lucene.apache.org/}Apache Lucene}} indexes browsers like - {{{https://github.com/DmitryKey/luke}Luke}} or {{{https://github.com/flaxsearch/marple}Marple}} after - unpacking the index (see {{{/maven-indexer/indexer-cli/}<<<-u>>> CLI option}}). - -* Digging Into Central Index with Luke - - * download {{{https://repo.maven.apache.org/maven2/.index/}the Central index: <<>>}} - - * download {{{https://repo.maven.apache.org/maven2/org/apache/maven/indexer/indexer-cli/5.1.1/indexer-cli-5.1.1.jar}Maven Indexer CLI}} - and {{{/maven-indexer-archives/maven-indexer-LATEST/indexer-cli/}unpack}} the index to raw Lucene index directory: - ------- -java -jar indexer-cli-5.1.1.jar --unpack nexus-maven-repository-index.gz --destination central-lucene-index --type full ------- - - * download and extract {{{https://github.com/DmitryKey/luke/releases/download/luke-4.10.4/luke-with-deps.tar.gz}Luke binary tarball}} - and launch it on the Central index with Lucene format: - ------- -luke.sh -ro -index central-lucene-index ------- - - You need an old Luke version using an old Lucene version, since Maven Indexer 5.5.1 uses Lucene 3.6.2: - for this tutorial, we chose Luke version 4.10.4, but you may choose another version. - - But with more recent Maven Indexer releases, more recent Lucene version have been used: see [Maven Indexer dependencies](/maven-indexer/indexer-core/dependencies.html). diff --git a/content/apt/repository/central-metadata.apt b/content/apt/repository/central-metadata.apt deleted file mode 100644 index f9aea2d01f..0000000000 --- a/content/apt/repository/central-metadata.apt +++ /dev/null @@ -1,58 +0,0 @@ - ------ - Guide to Metadata in Central Maven Repository - ------ - Carlos Sanchez - ------ - 2005-10-31 - ------ - -~~ 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 - -Guide to add, improve or fix metadata in the Central Maven Repository - -* POM Metadata - - There are artifacts in the {{{./}Central Maven repository}} that don't have POMs. They come from projects with repositories that have - been synced into central without extra checks (particularly historical ones that were in format). We - know about the problems but can't do anything unless you provide a POM for it or you ask the project in - question to add the POM when they add the artifacts. - - We don't change dependencies in POMs already in the repository anymore as builds need to be reproducible. - Same applies to POMs that don't exist. We can only add a POM with no dependencies, because doing any other way - would break previous builds that were using that artifact. - - An alternative is to create a new version with the fixes. If the broken artifact is <<>> you can - provide a fixed POM, JAR,... under <<>> (add a comment to the POM explaining what is being fixed - and why). See {{{./guide-central-repository-upload.html}Maven Repository Upload}} for the instructions to - get this new version in the repository. - - You need to contact the original publisher of the metadata to make sure in next versions it will - be fixed or improved before getting it into the repository. - -* Other Issues - - For any other types of issues related to metadata in the repository (POM related, or - {{{/ref/current/maven-repository-metadata/}<<>>}}, or anything else), open an issue at - {{{https://issues.sonatype.org/browse/MVNCENTRAL}MVNCENTRAL}} with the relevant information and - explain the reasons why it is an issue. - - <> by default assume that we won't trust your info, so you must provide all links - to the project documentation you can to convince us that your solution is right. diff --git a/content/apt/repository/guide-central-repository-upload.apt b/content/apt/repository/guide-central-repository-upload.apt deleted file mode 100644 index 0ce4b9644c..0000000000 --- a/content/apt/repository/guide-central-repository-upload.apt +++ /dev/null @@ -1,190 +0,0 @@ - ------ - Guide to uploading artifacts to the Central Repository - ------ - Jason van Zyl - Brian Fox - ------ - 2018-12-31 - ------ - -~~ 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 - -Guide to uploading artifacts to the Central Repository - - In order for users of Maven to utilize artifacts produced by your project, you must deploy them to - a remote repository. Many open source projects want to allow users of their projects who build with - Maven to have transparent access to their project's artifacts. In order to allow for this, a project - should deploy their artifacts to the {{{/repository/}Central Repository}}. - - -Requirements - - [[1]] <>: Only can be uploaded to the Central Repository, that means files that won't change and that only depend on other files - already released and available in the repository, - - [[2]] <> for IDE lookup, - - [[3]] <>, - - [[4]] <>: There are some requirements for the minimal information in the POMs that are in the Central Repository, - see {{{https://central.sonatype.org/pages/requirements.html#sufficient-metadata}here}}, - - [[5]] <>: Picking the appropriate coordinates for your project is important. See the guidelines - {{{https://central.sonatype.org/pages/choosing-your-coordinates.html}here}}, particularly - on {{{https://central.sonatype.org/pages/producers.html#individual-projects-open-source-software-repository-hosting-ossrh}groupId and domain ownership}}. - - [] - - The updated list of requirements can be found <<{{{https://central.sonatype.org/pages/requirements.html}here}}>>. - -* Explanation - - Some folks have asked <"why do we require all this information in the POM for deployed artifacts?">, so here's a small explanation. - - The POM - being deployed with the artifact is part of the process to make transitive dependencies a reality in Maven. The logic for getting - transitive dependencies working is really not that hard, the problem is getting the data. The other applications - that are made possible by having all the POMs available for artifacts are vast, so by placing them into the Central Repository as part of the - process we open up the doors to new ideas that involve unified access to project POMs. - - We ask for the license because it is possible that your project's license may change in the course of - its lifetime, and we are trying to create tools to help sort out licensing issues. For example, knowing all the licenses - for a particular graph of artifacts, we could have some strategies that would identify potential licensing problems. - -* A basic sample: - -+----+ - - - 4.0.0 - org.apache.maven - maven - 2.0 - jar - - Maven core - The maven main core project description - http://maven.apache.org - - - - Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.txt - repo - - - - - https://svn.apache.org/viewvc/maven - - - - - ... - ... - ... - - ... - - - - - -+----+ - -* PGP Signature - - When people download artifacts from the Central Repository, they might want to verify these artifacts' PGP - signatures against a public key server. - If there are no signatures, then users have no guarantee that they - are downloading the original artifact. - - To improve the quality of the Central Repository, we require you to provide PGP signatures for all your artifacts (all - files except checksums), and distribute your public key to a key server like {{{http://pgp.mit.edu}http://pgp.mit.edu}}. Read - {{{http://central.sonatype.org/pages/working-with-pgp-signatures.html}Working with PGP Signatures}} - for more information. - -* FAQ and common mistakes - - * I have other <<>> or <<>> listed in my POM, is that a problem? - - At present, this won't preclude your project from being included, but we do strongly encourage making sure all your dependencies - are included in the Central Repository. If you rely on sketchy repositories that have junk in them or disappear, it just creates havok for - downstream users. Try to keep your dependencies among reliable repos like Central, Jboss, etc. - - * What about artifacts that can't be distributed because of their license? - - In that case only the POM for that dependency is required, listing where the dependency can be downloaded from. - {{{https://repo.maven.apache.org/maven2/javax/activation/activation/1.0.2/activation-1.0.2.pom}See an example}}. - - * I have a patched version of the foo project developed at foo.com, what <<>> should I use? - - When you patch / modify a third party project, that patched version becomes your project and therefore should be distributed under a <<>> you control - as any project you would have developed, never under <<>>. See above considerations about <<>>. - - * My project is hosted at a project hosting service like SourceForge or Github, what should I use as groupId? - - If your project name is <<>> at SourceForge, you can use <<>>. - If your username is <<>> on Github, you can use <<>>. - You can also use another reversed domain name you control. The group ID does - not have to reflect the project host. - - [] - -Publishing your artifacts to the Central Repository - -* Approved Repository Hosting - - Instead of maintaining repository rsync feeds for each projects, we now encourage projects to use an approved repository hosting location. - - Currently approved repository hosting locations: - - * {{{https://repository.apache.org/}Apache Software Foundation}} (for all Apache projects) - - * see {{{https://central.sonatype.org/publish/large-orgs/}the full list}} - - [] - - Automatic publication will be provided for Forges that provide hosting services for OSS projects and other large project repositories - that meet certain minimum criteria such as validation of PGP keys and pom contents as defined above. If you are interested in - becoming an approved Forge, {{{https://central.sonatype.org/publish/large-orgs/}contact us}}. - -* Other Projects - - The easiest way to upload another project is to use the - {{{https://central.sonatype.org/pages/ossrh-guide.html}Open Source Software Repository Hosting (OSSRH)}}, which is an approved repository provided - by Sonatype for OSS Project that wants to get its artifacts into the Central Repository. - -* Explanations - - Having each project maintain its own repository with rsync to the Central Repository was the preferred process until January 2010. - However, we are no longer accepting rsync requests on a per project basis. - - Over time, we have learned that this process is not scalable. Many of the projects being synced release very infrequently, yet - we have to hit hundreds of servers several times a day looking for artifacts that don't change. Additionally, there is no good - mechanism currently for validating the incoming data via the rsync, and this leads to bad metadata that affects everyone. - - The aggregation of projects into larger feeds allows us to sync faster and more often, and ensuring these locations - perform sufficient checks increases the quality of metadata for everyone. diff --git a/content/apt/run-maven/index.apt b/content/apt/run-maven/index.apt deleted file mode 100644 index b4019a9468..0000000000 --- a/content/apt/run-maven/index.apt +++ /dev/null @@ -1,106 +0,0 @@ - ----- - Running Maven - ----- - Brett Porter - ----- - 2006-11-03 - ----- - -~~ 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 - -Building a Project with Maven - - The vast majority of Maven-built projects can be built with the following command: - ----- -mvn verify ----- - - This command tells Maven to build all the modules, and to check if all integration tests succeeded (when any was defined) - - That's it! If you look in the <<>> subdirectory, you should find the build output and the final library or - application that was being built. - - <> Some projects have multiple modules, so the library or application you are looking for may be in a module - subdirectory. - - While this will build most projects and Maven encourages this standard convention, builds can be customisable. If this - does not suffice, please consult the project's documentation. - -* More than just the Build - - Maven can do more than just build software - it can assist with testing, run web applications and produce reports on - projects, as well as any number of other tasks provided by plug-ins. - -* When Things go Wrong - - The following are some common problems when building with Maven, and how to resolve them. - -** Missing Dependencies - - A missing dependency presents with an error like the following: - ------ -[INFO] Failed to resolve artifact. - -Missing: - ---------- -1) jnuit:junit:jar:3.8.1 - - Try downloading the file manually from the project website. - - Then, install it using the command: - mvn install:install-file -DgroupId=jnuit -DartifactId=junit \ - -Dversion=3.8.1 -Dpackaging=jar -Dfile=/path/to/file - - Path to dependency: - 1) org.apache.maven:maven:pom:2.1-SNAPSHOT - 2) jnuit:junit:jar:3.8.1 - - ---------- -1 required artifact is missing. - -for artifact: - org.apache.maven:maven:pom:2.1-SNAPSHOT - -from the specified remote repositories: - central (https://repo.maven.apache.org/maven2) ------ - - To resolve this issue, it depends on what the dependency is and why it is missing. The most common cause is because - it can not be redistributed from the repository and must be manually installed using the instructions given in the - message. This is most common with some older JARs from Sun (usually <<>> group IDs), and is further - documented in the {{{../guides/mini/guide-coping-with-sun-jars.html} Guide to Coping with Sun JARs}}. - - You can check the list of repositories at the end of the error to ensure that the expected ones are listed - it may - be that the project requires an alternative repository that has not been declared properly or is not accessible with - your Maven configuration. - - In other cases, it may be an incorrectly declared dependency (like the typo in the example above) which the project - would need to fix, like a compilation error. - -** Inconsistent output - - Most plugins are optimized to know if they have to execute their task. In some cases, the output can be polluted from - a previous build and the end result is not what you expected. In such rare situations, you can call the <<>> phase - which means: remove the output directory. - You can also call it as <<>> which means: first clean up the output directory, next build the project - and verify the outcome. diff --git a/content/apt/shared/index.apt b/content/apt/shared/index.apt deleted file mode 100644 index 652dbd177d..0000000000 --- a/content/apt/shared/index.apt +++ /dev/null @@ -1,85 +0,0 @@ - ----- - Shared Components - ----- - Dennis Lundberg - John Casey - Karl Heinz Marbaise - ----- - 2017-05-03 - ----- - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Shared Components - - The shared components are currently under transition to Maven 3.x only components. - -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -|| <> || <> || <> || <> || <> || <> | -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/file-management/} <<>>}} | 3.1.0 | 2022-06-29 | API to collect files from a given directory using several include/exclude rules. | {{{https://gitbox.apache.org/repos/asf/maven-file-management.git}Git}} / {{{https://github.com/apache/maven-file-management/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = file-management}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-archiver/} <<>>}} | 3.6.3 | 2024-10-22 | Is mainly used by plugins to handle packaging. | {{{https://gitbox.apache.org/repos/asf/maven-archiver.git}Git}} / {{{https://github.com/apache/maven-archiver/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-archiver}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-artifact-transfer/} <<>>}} | 0.13.1 | 2020-12-26 | An API to install, deploy and resolve artifacts with Maven | {{{https://gitbox.apache.org/repos/asf/maven-artifact-transfer.git}Git}} / {{{https://github.com/apache/maven-artifact-transfer/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-artifact-transfer}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-common-artifact-filters/} <<>>}} | 3.4.0 | 2024-06-05 | Filters lists of Artifact instances. | {{{https://gitbox.apache.org/repos/asf/maven-common-artifact-filters.git}Git}} / {{{https://github.com/apache/maven-common-artifact-filters/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-common-artifact-filters}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-dependency-analyzer/} <<>>}} | 1.15.1 | 2024-10-22 | Maven Dependency Analyzer component. | {{{https://gitbox.apache.org/repos/asf/maven-dependency-analyzer.git}Git}} / {{{https://github.com/apache/maven-dependency-analyzer/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-dependency-analyzer}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-dependency-tree/} <<>>}} | 3.3.0 | 2024-05-29 | Maven Dependency Tree constructs a tree model of a Maven project's dependencies. | {{{https://gitbox.apache.org/repos/asf/maven-dependency-tree.git}Git}} / {{{https://github.com/apache/maven-dependency-tree/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-dependency-tree}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/doxia/doxia-sitetools/doxia-integration-tools/} <<>>}} | | | moved to {{{/doxia/doxia-sitetools/doxia-integration-tools/} <<>>}} | | -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-filtering/} <<>>}} | 3.4.0 | 2024-08-28 | Components for filtering resources. | {{{https://gitbox.apache.org/repos/asf/maven-filtering.git}Git}} / {{{https://github.com/apache/maven-filtering/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-filtering}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-invoker/} <<>>}} | 3.3.0 | 2024-05-07 | Fires up a Maven build in a new JVM. | {{{https://gitbox.apache.org/repos/asf/maven-invoker.git}Git}} / {{{https://github.com/apache/maven-invoker/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-invoker}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-jarsigner/} <<>>}} | 3.1.0 | 2024-08-15 | This component provides some utilities to sign/verify jars/files in your Mojos. | {{{https://gitbox.apache.org/repos/asf/maven-jarsigner.git}Git}} / {{{https://github.com/apache/maven-jarsigner/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-jarsigner}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-mapping/} <<>>}} | 3.0.0 | 2015-11-19 | A shared component for all plugins that need to do mapping. | {{{https://gitbox.apache.org/repos/asf/maven-mapping.git}Git}} / {{{https://github.com/apache/maven-mapping/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-mapping}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-reporting-api/} <<>>}} | 4.0.0 | 2024-10-01 | API to manage report generation. | {{{https://gitbox.apache.org/repos/asf/maven-reporting-api.git}Git}} / {{{https://github.com/apache/maven-reporting-api/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-reporting-api}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-reporting-exec/} <<>>}} | 2.0.0 | 2024-10-15 | API to manage report plugins preparation with Maven 3. | {{{https://gitbox.apache.org/repos/asf/maven-reporting-exec.git}Git}} / {{{https://github.com/apache/maven-reporting-exec/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-reporting-exec}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-reporting-impl/} <<>>}} | 4.0.0 | 2024-10-12 | Abstract classes to manage report generation. | {{{https://gitbox.apache.org/repos/asf/maven-reporting-impl.git}Git}} / {{{https://github.com/apache/maven-reporting-impl/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-reporting-impl}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-script-interpreter/} <<>>}} | 1.6 | 2024-04-29 | Utilities to interpret/execute some scripts for various implementations: groovy or beanshell. | {{{https://gitbox.apache.org/repos/asf/maven-script-interpreter.git}Git}} / {{{https://github.com/apache/maven-script-interpreter/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-script-interpreter}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-shared-incremental/} <<>>}} | 1.1 | 2013-04-08 | Various utility classes and plexus components for supporting incremental build functionality in Maven plugins. | {{{https://gitbox.apache.org/repos/asf/maven-shared-incremental.git}Git}} / {{{https://github.com/apache/maven-shared-incremental/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-shared-incremental}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-shared-jar/} <<>>}} | 3.1.1 | 2024-06-20 | Utilities which help identify the contents of a JAR, including Java class analysis and Maven metadata analysis. | {{{https://gitbox.apache.org/repos/asf/maven-shared-jar.git}Git}} / {{{https://github.com/apache/maven-shared-jar/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-shared-jar}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-shared-resources/} <<>>}} | 6 | 2024-06-08 | This is a collection of templates that are specific to the Maven project. | {{{https://gitbox.apache.org/repos/asf/maven-shared-resources.git}Git}} / {{{https://github.com/apache/maven-shared-resources/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-shared-resources}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-shared-utils/} <<>>}} | 3.4.2 | 2023-05-11 | Utilities functions for use within Maven. | {{{https://gitbox.apache.org/repos/asf/maven-shared-utils.git}Git}} / {{{https://github.com/apache/maven-shared-utils/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-shared-utils}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-shared-io/} <<>>}} | 3.0.0 | 2015-12-23 | API for I/O support like logging, download or file scanning. | {{{https://gitbox.apache.org/repos/asf/maven-shared-io.git}Git}} / {{{https://github.com/apache/maven-shared-io/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-shared-io}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/shared/maven-verifier/} <<>>}} | 2.0.0-M1 | 2022-09-22 | Used to run Maven builds as part of tests. | {{{https://gitbox.apache.org/repos/asf/maven-verifier.git}Git}} / {{{https://github.com/apache/maven-verifier/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSHARED AND status != Closed AND component = maven-verifier}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ -| {{{/scm/} <<>>}} | 2.1.0 | 2024-04-11 | Generic API to SCM systems. | {{{https://gitbox.apache.org/repos/asf/maven-scm.git}Git}} / {{{https://github.com/apache/maven-scm/}GitHub}} | {{{https://issues.apache.org/jira/browse/SCM}JIRA}} -*----------------------------------------------------------------------------+--------------+-------------------+------------------+------------------------+---------------------+ - - - Archived version of shared libraries reference documentations are {{{../shared-archives/}located here}}. - diff --git a/content/apt/skins/index.apt b/content/apt/skins/index.apt deleted file mode 100644 index a6eaff5017..0000000000 --- a/content/apt/skins/index.apt +++ /dev/null @@ -1,93 +0,0 @@ - ----- - Available Skins - ----- - Dennis Lundberg - Karl Heinz Marbaise - Michael Osipov - ----- - 2012-04-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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Available Skins - - The following table lists skins that are available for you to use in your - Maven generated site. - -* Maintained By The Maven Project - -*-------------------------------------------------------------------+--------------+----------------------+------------------+------------------------+--------------------+ -|| <> || <> || Site Plugin Version || <> || <> || <> -*-------------------------------------------------------------------+--------------+----------------------+------------------+------------------------+--------------------+ -| {{{/skins/maven-fluido-skin/} <<>>}} | 2.0.0-M11 | [3.20.0,) | Skin based on Bootstrap CSS. | {{{http://gitbox.apache.org/repos/asf/maven-fluido-skin.git}Git}} / {{{https://github.com/apache/maven-fluido-skin/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSKINS AND status != Closed AND component = "Fluido+Skin"}JIRA}} -*-------------------------------------------------------------------+--------------+----------------------+------------------+------------------------+--------------------+ -| {{{/skins/maven-fluido-skin/} <<>>}} | 1.12.0 | [3.10.0,3.20.0) | Skin based on Bootstrap CSS. | {{{http://gitbox.apache.org/repos/asf/maven-fluido-skin.git/}Git}} / {{{https://github.com/apache/maven-fluido-skin/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSKINS AND status != Closed AND component = "Fluido+Skin"}JIRA}} -*-------------------------------------------------------------------+--------------+----------------------+------------------+------------------------+--------------------+ - -** Retired - -*-------------------------------------------------------------------+--------------+----------------------+-------------------+------------------+ -|| <> || <> || Site Plugin Version || <> || <> -*-------------------------------------------------------------------+--------------+----------------------+-------------------+------------------+ -| {{{/skins/maven-default-skin/} <<>>}} (unofficially) | 1.3 | [3.5,3.20.0) | You get this skin if you don't specify any skin or template. | {{{http://gitbox.apache.org/repos/asf/maven-default-skin.git/}Git}} / {{{https://github.com/apache/maven-default-skin/}GitHub}} | {{{https://issues.apache.org/jira/issues/?jql=project = MSKINS AND status != Closed AND component = "Default Skin"}JIRA}} -*-------------------------------------------------------------------+--------------+----------------------+------------------+------------------------+--------------------+ -| {{{/skins/maven-application-skin/} <<>>}} | 1.0 | (,3.4] | 2015-12-28 |A skin used by applications like Continuum. -*-------------------------------------------------------------------+--------------+----------------------+-------------------+------------------+ -| {{{/skins/maven-classic-skin/} <<>>}} | 1.1 | (,3.4] | 2015-12-28 | This skin resembles the look of a site generated by Maven 1. -*-------------------------------------------------------------------+--------------+----------------------+-------------------+------------------+ -| {{{/skins/maven-stylus-skin/} <<>>}} | 1.5 | (,3.4] | 2015-12-28 | The skin used for the website of Maven itself. -*-------------------------------------------------------------------+--------------+----------------------+-------------------+------------------+ - -* Outside The Maven Land - -*-------------------------------------------------------------------+----------------+-----------------------+ -|| <> || <> || <> -*-------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://olamy.github.io/reflow-maven-skin/} <<>>}} | {{{https://github.com/olamy} Olivier Lamy}} | Responsive Apache Maven skin to reflow the standard Maven site with a modern feel. -*-------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://devacfr.github.io/reflow-maven-skin/} <<>>}} | {{{https://github.com/devacfr} Friederich Christophe}} | Responsive 2 Apache Maven skin to reflow the standard Maven site with a modern feel. -*-------------------------------------------------------------------+----------------+-----------------------+ -| {{{http://docs.bernardomg.com/maven/docs-maven-skin/} <<>>}} | {{{https://github.com/Bernardo-MG} Bernardo Martínez Garrido}} | A minimalist and responsive Bootstrap-based HTML5 skin for Maven Site, which will help to use it as a documentation site. -*-------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://stevecrox.github.io/maven-site-bootstrap-skin//} <<>>}} | {{{https://github.com/stevecrox/maven-site-bootstrap-skin} Stephen Crocker}} | Responsive Maven Bootstrap Skin which has toggleable elements implemented based on the boostrap reference layouts. -*-------------------------------------------------------------------+----------------+-----------------------+ -| {{{https://sentrysoftware.org/sentry-maven-skin/} <<>>}} | {{{https://github.com/sentrysoftware/sentry-maven-skin} Sentry Software}} | Responsive skin, Bootstrap-based, with local search, light/dark colors switch, WEBP conversion, etc. -*-------------------------------------------------------------------+----------------+-----------------------+ - -* Instructions - - To use one of these skins in your project, you use the <<>> element of the - {{{/plugins/maven-site-plugin/examples/sitedescriptor.html}site descriptor}}. - This is a regular artifact or dependency-like element. For example, to use the - Maven Fluido Skin, you would include the this in your <<>> file: - -+-----+ - - ... - - org.apache.maven.skins - maven-fluido-skin - 1.12.0 - - ... - -+-----+ diff --git a/content/apt/users/getting-help.apt b/content/apt/users/getting-help.apt deleted file mode 100644 index 2ed7fd0df3..0000000000 --- a/content/apt/users/getting-help.apt +++ /dev/null @@ -1,128 +0,0 @@ - ----- - Getting Help - ----- - Dennis Lundberg - Karl Heinz Marbaise - ----- - 2007-07-24 - 2015-06-17 - ----- - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Getting Help - - So something didn't work as you expected it to? You think that - . What should you do? - - Here's a list of actions that you can take: - -*You did check the documentation, didn't you? - - Apart from the central Maven site, each of our plugins has a website. Go - to the {{{../plugins/index.html}plugins page}} and follow the link to the - plugin you are having problems with. - -* Try the latest version of Maven or the plugin in question - - Before you start intensive investigations on your problem, you should try to update Maven and/or the plugins - in question to the latest stable release. After all, the issue you encounter might have been fixed already. - To find out what is the latest stable release version, consult {{{../download.html}Maven's download section}} - and the {{{../plugins/index.html}plugin index}}. - -*Search the user-list archives - - Someone else might have experienced the same problem as you before. A list - of mail-archives can be found on - {{{https://maven.apache.org/mailing-lists.html}mailing list index page}}. Please search one of - them before going any further. - -*Ask on the user list - - Our community is very helpful, just ask it the right way. See the references - section, at the end of this page, for info on how to do that. Subscribe to - the {{{https://maven.apache.org/mailing-lists.html}users-list}} and describe your - problem there. Don't expect to get an answer right away. Sometimes it takes a - couple of days. - -*Submit an issue - - If it turns out that there is indeed something wrong with Maven - or one of the plugins, you should report it to our issue management system JIRA. - - You don't need create JIRA issue only to ask us something - - in such case please first ask on {{{https://maven.apache.org/mailing-lists.html}users-list}} - -**Request new JIRA account - - Requesting for JIRA account is preferred if you plan to contribute to project by coding or testing by longer time. - - This is so that we can communicate with you while we work together on the issue. - - * please use your real name and surname if possible in public name field - - * links to your public projects, social or professional profile can be appreciated - - * you can also tell us a little about yourself and what you intend to use this account for - - [] - - Such information is useful to verify that account is requested for real user not a bot. - - Go to the {{{https://selfserve.apache.org/jira-account.html?project=maven}Request a JIRA account}} - to request for a new account if you don't already have one. - -**Where? - - If the problem is in one of the plugins, check the site of that plugin to - get the correct link. Each plugin has its own section in JIRA, so using the - correct link is important. Click on and then - . On that page you will find the correct link. - - If the problem is in Maven itself you can find the appropriate link on the - {{{https://maven.apache.org/issue-management.html}issue management}} page. - -**How? - - Just describing the problem is not enough. It takes a developer a lot of - time to make a usable POM to even attempt to assess the problem. Issues - that states problems without something usable to try out will be closed as - incomplete. - - Please attach a working POM, or a set of POMs, that we can download and run. - We appreciate reports, but if you don't have something usable for us it's - incredibly hard for us to manage the issues. A POM goes a long way to helping - us resolve problems. - - Create a POM that can be used to verify that it is a bug. If your pom uses - plugins, make sure that you have specified the version for each and every - plugin. If you don't, then we might not be using the same version as you are - when we test it. - - What we like best are patches that fixes the problem. If you want to create a - patch for an issue please read the - {{{../guides/development/guide-maven-development.html}Maven Developer Guide}} first. - -* References - - * {{{http://www.catb.org/~esr/faqs/smart-questions.html}How To Ask Questions The Smart Way}} - - * {{{http://opensourcestrategies.blogspot.com/2005/09/how-to-get-support-from-open-source.html}How to Get Support from Open Source Mailing Lists}} diff --git a/content/apt/users/index.apt b/content/apt/users/index.apt deleted file mode 100644 index 08c09436fa..0000000000 --- a/content/apt/users/index.apt +++ /dev/null @@ -1,53 +0,0 @@ - ----- - Users Centre - ----- - Brett Porter - ----- - 2006-11-03 - ----- - -~~ 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: -~~ https://maven.apache.org/doxia/references/apt-format.html - -Maven Users Centre - - This documentation centre is for those that have decided to use Maven to build their project, and would like to get - started quickly, or are already using Maven and would like to add new functionality or fix a problem in their build. - -~~TODO: tasks as buttons? - - * {{{../download.html} Download Maven}} - Download the latest version of Maven - - * {{{../guides/getting-started/maven-in-five-minutes.html} The 5 minute test}} - Learn how to use Maven in 5 minutes - - * {{{../guides/getting-started/index.html} Getting Started Tutorial}} - An in depth tutorial once you've learned the basics - - * {{{./getting-help.html} Getting Help}} - How to get help with Maven - -~~TODO: old getting started guide should become a beginners trail, and remove content covered in the 5 minute tutorial - -~~TODO: link to repository centre and plugin developers centre, and the reasons why they would progress there - -* Reference - - * {{{../pom.html} POM Reference}} - - * {{{../settings.html} Settings Reference}} - diff --git a/content/markdown/archives/maven-2.x/index.md b/content/markdown/archives/maven-2.x/index.md new file mode 100644 index 0000000000..b968e7e6bd --- /dev/null +++ b/content/markdown/archives/maven-2.x/index.md @@ -0,0 +1,38 @@ +--- +title: Maven 2 Graveyard +author: + - Karl-Heinz Marbaise +date: 2014-03-22 +--- + + + + + + + + + + + + + + + + + +# This is the Maven 2 Graveyard + +Based on a decision for the End Of Lifetime of Maven 2 this location is intended as a graveyard for Maven 2 only related information and links\. + +## Plugin List + +The following list of plugins contains plugins which are Maven 2 specific\. Apart from that for those plugins which are listed here there are no updates/bug fixes planned etc\. + +|**Plugin**|**Type\***|**Version**|**Last Release Date**|**Description**|**Date of Funeral**| +|---|---|---|---|---|---| +|**Core plugins**||||**Plugins corresponding to default core phases \(ie\. clean, compile\)\. They may have multiple goals as well\.**|| +|[ `reactor`](/plugins/maven\-reactor\-plugin/)|B|1\.0|2008\-09\-27|Build a subset of interdependent projects in a reactor|2014\-03\-24| + +\* **B**uild or **R**eporting plugin + diff --git a/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md b/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md new file mode 100644 index 0000000000..6a5a1208e3 --- /dev/null +++ b/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md @@ -0,0 +1,147 @@ +# h1\. Maven 2\.1 \-\- Jason van Zyl + + + + + + + + + + + + + + + + + +# Discussion: need some answers to these before even pushing this to the list TODO: Jesse and Greg spent a lot of time getting the async SSL working so a little description this work would be useful TODO: architecture document about Mercury transport as the async HTTP/DAV client TODO: example of user facing API for Mercury TODO: architecture document and spec for mercury \(largely in the wiki\) TODO: example of user facing API for maven\-shared\-model TODO: architecture document on maven itself, plugin manager, lifecycle executor, profile construction TODO: check with kenney to see if his work survived in substituting components or if it's his work that's actually making it work + +# Technical Preparation: not necessary before discussions can start but helpful to help guide how we concretely determine backward compat TODO: get an explanation of the process Arnaud and Benjamin have for plugins\. I started by capturing the log TODO: document standard setup for Hudson we have so people can see the results of testing TODO: setup hudson with emma for code coverage and ask VELO to help us setup coverage for integration tests + +# h2\. Architectural Goals + +# h3\. Backward Compatibility + +# We must ensure that plugins and reports written against the Maven 2\.0\.x APIs remain to work in 2\.1\. We don't want people to have to rewrite their plugins\. There are several plugins that are using the current artifact resolution code that will not be supported \(please see the Mercury section below\)\. The ones that are in our control we can port over to use Mercury, and external users will have to deal with the major version change\. Most people will not be affected and Mercury will be a far better solution\. + +# We must also ensure that POMs of version 4\.0\.0 are supported in 2\.1\.x along with the behavior currently experienced\. We are relying heavily on our integrations tests right now but as we move forward the work that Shane is doing on the project builder with maven\-shared\-model will help us to accommodate different versions of a POM, and different formats we decide to support\. The maven\-shared\-model code has no limitation to formats of XML, or any of format like YAML, script, or anything else anyone can dream up\. These implementations may find use outside of Maven\. For example someone might build something with the Maven Embedder, JRuby, and Mercury to create a JRuby\-based system\. The same could be done for Groovy, or Intercal\. + +# h2\. Plugin and Extension Loading + +# Maven's mechanisms for loading plugins and build extensions has been refactored\. You can find more information in the \[Maven 2\.1 Plugin and Extension Loading Design\] document\. + +# h2\. Lifecycle + +# h3\. Aggregator Mojo Handling + +# Aggregator mojos bound to the lifecycle have been deprecated\. This practice can produce some very strange results, and isn't really the right solution for many of the problems it attempts to solve\. I'm hoping to include some better options for bracketing the normal build \- both before, and after, explicitly \- to make aggregator mojos obsolete, but for now they've been deprecated to avoid disrupting backward compatibility\. + +# Also, aggregator mojos that \*are\* bound to the lifecycle will only be allowed to execute at most once during the build, to limit redundant execution\. These mojos are meant to act on all projects in the reactor at once, and binding them to one pom\.xml file is dangerous in that it can produce different build results depending on whether that pom\.xml is included\. This is further complicated if two modules in a reactor configure the same aggregator mojo\.\.\.in which case, it may run multiple times\.\.\.or, when the aggregator is configured in the parent pom, where it will run for each descendant module\. + +# h2\. Plugin API + +# h3\. Shading of plexus\-utils causing a ClassCastException on plugin\.getConfiguration\(\) \(\[MNG\-3012|http://jira\.codehaus\.org/browse/MNG\-3012\]\) + +The fact that plexus\-utils is hidden from plugins in the newer releases of Maven means that plugin\.getConfiguration\(\) from maven\-model can cause a ClassCastException, if used from within a mojo\. The plan to fix this is basically just to import Xpp3Dom from the shaded plexus\-utils version in maven\-core within the plugin's classrealm\. This should allow us to share the same instance of that class \(only, shouldn't really affect other p\-u classes\) and preserve backward compatibility for existing plugin releases\. + +# comment from kenney: The problem with this is that it's a hack\. If xpp3dom/plexus utils is updated and the plugin requires the new xpp3dom class, which has a new method for instance, this will break the plugin\. + +# About this specific issue \(MNG\-3012\): The best solution is to only share java\., javax\., and core maven api classes, so we can no longer export anything outside the plugin api \(which includes maven\-model, maven\-project, maven\-settings e\.a\.\)\. This would require to phase out plugin\.getConfiguration\(\) and other model methods that return xpp3dom classes, and let them return interfaces present in the maven core api\. Those interfaces would have an implementation class that implements both that interface and extends xpp3dom, which will be hidden for the plugin\. Another solution could be to use xmlplexusconfiguration + +# There's one more solution to consider; using ASM to rewrite plugins as they're loaded\. We could add code modifiers that workaround incompatibilities by detecting usage patterns, like \(Xpp3Dom\) plugin\.getConfiguration\(\)\. An example could be to modify the code to wrap Xpp3DomParser\.parse\( new StringReader\( String\.valueOf\( /plugin\.getConfiguration\(\)/ \) \) \) around the call\. This is even more of a hack though\. Perhaps a mojo that scans for plugin incompatibilities using ASM is more feasible \(no code modification\)\. + +# So the basic problem we're up against is that there can be core api changes between major versions that pose incompatibilities for plugins written against an older version\. The simplest solution would be to let plugins specify the maven versions they work against \(which is partly present: _requires__mavenVersion_2\.0\.6_/mavenVersion__/requires_\. If this field supports a versionrange, or we'd default the version interpretation above to mean \[2\.0\.6,2\.1\), we can detect plugins that won't run\. The shading mentioned above is solving only one incompatibility problem, and there are bound to be more\. Maybe we even need 2 versions of a plugin at some point, targeted toward different maven versions, though I'd really like to avoid that\. But we cannot just assume our 2\.0 plugin api will never change across 'major' \(read: minor\) releases\. + +# h3\. Strategies for ensuring backward compatibility + +## Plugin integration testing + +# code jason: so when you and benjamin went through the tests you have "integration\-tests" as the standard hook in the plugin build to grab on to? \[07:59am\] jason: why is the activator a property negation? why don't you just run in hudson with \-Pintegration\-tests? \[08:02am\] jason: i want to document what you and benjamin have done as a strategy for ensuring backward compatibility \[08:03am\] ltheussl left the chat room\. \(Client closed connection\) \[08:04am\] aheritier: I started with this idea to have an additional profile that we activate with a property like integration\-tests=true \[08:05am\] jason: yah, i think \-Pintegration\-tests=true in a schedule in hudson is fine \[08:05am\] jason: don't think the skip property is necessary \[08:05am\] bentmann joined the chat room\. \[08:05am\] aheritier: but others showed me that he major part of existing integration tests were activated with skipTests \! true \[08:05am\] aheritier: I asked why \[08:05am\] aheritier: they said it was to be sure to launch it by default \[08:06am\] aheritier: but to have the possibility to deactivate them if we skip tests \[08:06am\] jason: sure, so by default they run \[08:07am\] aheritier: yes\. \[08:07am\] aheritier: I prefer to activate them if I want \[08:07am\] jason: yes \[08:07am\] aheritier: not to have them always \[08:07am\] jason: i agree that should be the pattern \[08:07am\] aheritier: it's too long \[08:07am\] jason: a smoke test in one mode \[08:07am\] jason: and then turn them all on in hudson \[08:07am\] aheritier: it's why we invented CI servers \[08:07am\] aheritier: yes \[08:07am\] eu left the chat room\. \(Ping timeout\) \[08:08am\] jason: i will document the setup but you and ben should figure out the pattern you want for a given plugin test \[08:08am\] jason: and i'll document this as a strategy for testing 2\.1 \[08:08am\] eu joined the chat room\. \[08:08am\] ekuleshov is now known as eu\. \[08:08am\] jason: as i would like to take your setup, and parameterize the version of maven \[08:08am\] jason: so when some changes are made in 2\.1 i'll run the plugin smoke test first \[08:09am\] jason: make sure nothing we change in the apis or hooks is screwed up \[08:09am\] jason: and then run the ITs to make sure those plugins are working \[08:09am\] jason: i already know a handful that are not working \[08:09am\] bentmann: jason: How exactly do you intend to parametrize the Maven version? As far as I see, you only need to run them with the Maven of your choice\. \[08:10am\] jason: by taking the existing build, read the job, and change the version \[08:10am\] jason: i have tools for reading/writing jobs \[08:10am\] jason: but even low tech cloning the job and changing the maven installation \[08:10am\] bentmann: So the parametrization is limited to the Hudson job config, right? \[08:11am\] jason: actually you could parameterize anything if you control the job reading/writing \[08:11am\] eu left the chat room\. \(Ping timeout\) \[08:11am\] jason: but this is something kohsuke added himself about a week ago \[08:11am\] jason: in hudson itself \[08:11am\] jason: i will create a set of parameters to test old/new versions of maven with a given set of plugins \[08:12am\] jason: this is a great start, we couldn't do it if the plugins didn't have the same hook \[08:12am\] jason: so all the maven plugin builds now have "integration\-tests" profiles? \[08:12am\] bentmann: Well, not all, only those that ITs before\. \[08:12am\] ekuleshov joined the chat room\. \[08:12am\] veleno left the chat room\. \(veleno\) \[08:13am\] jason: well that's a start and they are at least consistent now \[08:13am\] ekuleshov is now known as eu\. \[08:13am\] jason: which is a great start \[08:13am\] bentmann: I believe you just need to try to setup a Hudson job with Maven 2\.1 to build "maven\-plugins" and see what's missing in terms of config \[08:14am\] jason: not sure what you mean \[08:14am\] bentmann: IIRC, both Invoker and Shitty were picking up the maven\.home from the currently running Maven, so the ITs should inherit that \[08:14am\] jason: also, do you guys have a quick way to tell what plugins don't have ITs? \[08:14am\] bentmann: Seach for src/it\.\.\. \[08:15am\] jason: yes, i want to make more a report but i can do that \[08:15am\] jason: so anything that does have ITs you guys have made consistent? \[08:15am\] jason: yes? \[08:15am\] bentmann: Not sure what kind of consistency you actually require \[08:16am\] bentmann: The IT profile should be named equal for all of them \[08:16am\] bentmann: by inheriting from the parent \[08:16am\] i386\_ left the chat room\. \(i386\_\) \[08:16am\] bentmann: whether the are run by Invoker or Shitty shouldn't matter, I guess \[08:17am\] jason: no, the actual project just needs a profile name the same\. not taken from the parent but stated in the project itself \[08:17am\] jason: though the parent could specify that profile which just echos "No ITs" \[08:17am\] jason: so in a run we would know which plugins don't have ITs at all \[08:17am\] bentmann: Ah, I see \[08:17am\] jason: so i can try what i want and that's a great start \[08:18am\] jason: if our plugins don't all have ITs i cannot reasonably test 2\.1 \[08:18am\] jason: and any discussion about compatibility is pointless until that's done code + +# h3\. POM changes + +# There are many changes that users have requested in the POM, in addition to wholesale formatting changes\. Acommodating these requests is a little tricky because we need to support different versions simultaneously so that if projecta A builds with 2\.0\.x, project B can consume the project A POM using 2\.1\.x\. We just need some way to easy support multiple versions and support mediation between the different versions\. + +## Tags: loose categorization people to use to help categorize as they see fit \* Categories: more standard categories that form over time by using category structures that exist or common tags that are used so often they become categories \* Dendency excludes: being to transitively exclude a dependency \* Properties on dependencies \* Specification Dependencies \* Schematron/RelaxNG descriptor for each plugin \-\- Bryon Jacob proposed a flexible model but XSD is hard to fight here so I'm not sure how far this will go + +# h3\. Embedding + +# Full embedding of the Maven core is a major feature of the 2\.1\.x line\. The embedder was created primarily for IDE integration and is now being consumed by m2eclipse, Mevenide and IDEA, but the embedder is also used by the Maven CLI to ensure parity between IDEs and the CLI as much as possible\. To understand how the embedder work you can refer to the \[Maven Embedder documentation|http://maven\.apache\.org/guides/mini/guide\-embedding\-m2\.html\]\. + +# h3\. Custom Components + +# As discussed in \[Substituting of Custom Components|http://docs\.codehaus\.org/display/MAVEN/Substitution\+of\+Custom\+Maven\+Components\] we now have two ways to insert new components into the system\. + +## Using a directory and specifying it in the Classworlds configuration\. Tycho simply has a special set of components that load first before the standard maven components and they override the standard Maven components\. Here's the example based on what Tycho is currently doing which allows custom components to be used\. + +# code main is org\.apache\.maven\.cli\.MavenCli from plexus\.core + +# set maven\.home default $user\.home/m2 + +![ load $maven\.home/tycho/\*\.jar load $maven\.home/lib/\*\.jar code](plexus\.core) +## The embedder has the ContainerCustomizer which allow you to inject new component descriptors\. This is used in the IDE integration \(m2ecipse, Netbeans\) for adding custom artifact resolvers\. + +# But what we ultimately need for Tycho is a way to dynamically pull in a set of components based on the packaging of a project\. In our case with Tycho the packaging is maven\-osgi\-bundle and that should kick in the set of components that do builds for OSGi bundles\. We also have another use case in Tycho where we are building OSGi bundles without a POM and actually using a manifest\. In this case we need to somehow detect the manifest and then have the custom set of components kick in\. In the case of Tycho we need a different project builder, and artifact resolver\. + +# h3\. Mercury + +# Mercury is a replacement for the current Maven Artifact subsystem, and a complete replacement for the HTTP and DAV portions of the existing transport\. + +# The primary reasons for replacing the code are that it is unmaintainable and nearly impossible to navigate, it uses completely non\-standard structures and libraries for version calculations, the API is too hard for people to use, and it is not given to users to consume as a single componment to use\. Users are forced to know how several complicated components interact in order to implement a mechanism of retrieving artifacts from a repository\. The entire mechanism needs to be replaced with something that can be maintained and is reliable\. + +# Mercury started as some fixes to Maven Artifact to first help with embeddability and error reporting for IDE integration\. This was a direct result of all IDE integrators having to reimplement the current artifact resolver to provide decent feedback to users when errors occured\. The artifact subsystem would just die and leave the IDE in an unusable state\. Milos was the first to implement his own artifact resolver, and Eugene soon had to do the same in m2eclipse\. Oleg and I were also trying to use the current artifact mechanism in an embedded mode for some Eclipse plugins and this also proved to be quite painful\. After the first attempt of removing the fail\-fast behavior, Oleg and I decided to make a break from the old codebase and attempt to create Mercury with the following goals in mind: + +## Find the best people in the world to help create an awesome HTTP and DAV implementation\. We did this by talking to Greg, Jan, and Jesse who are the Jetty folks and there just isn't anyone who knows HTTP better\. Greg and Jan are awesome, and Jesse is Maven committer so we have some deep understanding of the issues involved\. So what Oleg and I wanted to see was: \*\* Easy SSL support where mucky with certificates in the default install is not required\. \*\* Connection pooling \*\* Connection parallelization \*\* Built in DAV client support for deployment \*\* Atomic retrieval: we make sure absolutely everything is been safely transported to disk before we place it in the local Maven repository \*\* Atomic deployment: in this case we could only support this using a special filter Greg created which blocks requests for any artifacts being deploy in the current set until the entire set land safely to disk\. So it becomes impossible to ask for an artifact that refers to something else in the set before it is actually available\. \*\* Starting thinking about a client that can understand GeoIP\. Given the recent spikes in traffic we are going to start needing to distribute the load\. + +## Find the best solution possible solution for dealing with version calculations, in particular ranges\. For this we called on Daniel Le Berre and ask for some help in integrating his SAT4J library\. We learned about the SAT4J library from the P2 project over at Eclipse\.org at the last EclipseCon\. SAT4J was deemed the best way forward by the P2 team in providing the most reliable, and most workable solution for doing version calculation\. SAT4J provides ways to plug\-in strategies to deal with our scopes, conflict resolution strategies and it is deadly fast\. We felt we are in good company as we can call on Daniel and the P2 team and collaborate when difficult problems arise\. + +## Find the best people to help with with security\. This might an SSL\-based solution to secure the channel where the source is known to be safe, a PGP\-based solution where the contents must be secured assuming a hostile channel, or a combination of the two\. To that end I have contacted the folks at the Legion of the Bouncy Castle and asked them to provide us the expertise to implement a safe and correct solution\. I have not persued any help on the SSL\. + +# So in the end I believe it would be detrimental to use the Maven Artifact code in the 2\.1\.x tree and the change needs to be made to use Mercury before the first alpha ships\. Oleg and I started this work, and Oleg has subsequently worked tirelessly on Mercury along with a great deal of help from Greg, Jan and Jesse\. I think Oleg understands the requirements as he's seen Maven in action in one of the largest development environments in the world and watched how Maven can fail spectacularly\. + +# h3\. Plugin API \* Symmetric output expressions \* Java5 Mojo annotations \(Yoav Landman has this working already\) \* Clean separation of plugins from reports\. It's not good that those are the same thing in the Maven internals\. \*\* Not using concrete XML classes in the Plugin API \(Xpp3Dom\) + +# h3\. Core Refactorings \* Project Builder \(\[architecture|http://docs\.codehaus\.org/display/MAVENUSER/Project\+Builder\]\) \*\* Maven shared model work: a new way of reading in the models for Maven that is not format dependent in any way i\.e\. XML, text, YAML, scripts, whatever\. \*\* Pluggable model readers: this could leverage different implementations provided by the shared model work, but we still need a way to detect the type and version of the model that we want to consume \*\* A new terse format that uses attributes \*\* Automatic parent versioning \*\* New interpolation component \(plexus\-interpolation\) \*\* Dynamic build sections \(\[MNG\-3530|http://jira\.codehaus\.org/browse/MNG\-3530\]\) \*\* Mixin support \-\- allowing a paramterizable template which can be imported with one line\. + +## Remove the use of separate plugin repositories\. We only need to pull resources from one repository\. We started doing this but I've had a couple clients that want to separate the tools they use from the code they are developing/building\. \* Decouple script\-based Plugins from the core \-\- we are a large part of the way here I need to summarize what was done\. \* Remove Settings from the core and make it a user facing configuration \(This is primarily done \-\- jason\) \* Have one configuration model for request \* Have one configuration model for session: session takes the request in the constructor and delegates \* Domain logging \* Plugin Manager \*\* Removal of the Plugin Registry \(done\) \-\- we moved in a direction where people lock down their versions and we've helped by putting default versions in the parent POM\. \*\* Load Plugin dependencies into a separate ClassRealm \(done\) \*\* Plugin Execution Environment: Ability to run any version of a plugin where an environment is created which contains all the requirements for a particular version of the Plugin API \* Lifecycle Executor \*\* Queryable Lifecycle \*\*\* The most important change in the embedding environment\. You can actually query Maven for the complete execution before it happens\. We must know the entire model of execution before we execute\. \* OSGi\-like Classloading to support isolated execution environments + +# h3\. Java 5 + +# Java5 annotations for plugins: we have two implementations that have now been merged in plexus\-cdc\. QDOX 1\.7 has now been released so we may want to check the source level gleaning again\. Jason Dillon has created a working class processing model\. We need to deal with Plexus components and Maven plugins\. + +# h3\. Integration and promotion of scriptable plugins + +# h3\. Toolchains \* Milos has implemented this and Shane had some feedback so this needs to be linked together + +# h3\. Reporting \* Report Execution Environment: Ability to run any version of a report where an environment is created which contains all the requirements for a particular version of the Report API\. \* Decouple the reporting core\. We need to get Doxia out of the core\. Anything it needs to run should be isolated\. + +# h1\. Other Use Cases to Integrate + +# h2\. Determining project type in Eclipse \(Igor Fedorenko\) + +# Support for "java" projects in Eclipse has certain overhead and it is desirable to only enable for projects that actually require it\. More specifically, java maven projects have JRE classpath container, maven classpath container, have java\-specific UI elements enabled and are offered in various java\-related searches\. Also, tools like WTP and AJDT treat \(eclipse\) java projects specially\. + +# There is currently no direct way to tell if a \(maven\) project needs to be configured as java project in eclipse\. The closest test condition I can think off is + +# 1 the project ArtifactHandler language=java + +# and + +# 2\.1 ArtifactHandler addedToClasspath=true + +# or + +# 2\.2 MavenProject\.getCompileSourceRoots\(\)\.size\(\) > 0 + +# or + +# 2\.3 MavenProject\.getTestCompileSourceRoots\(\)\.size\(\) > 0 + +# \(in other words the project is java and either itself is added to classpath or has sources to compile\)\. + +# This test will return false negative for some WAR projects \(not added to classpath and don't have any sources to compile\)\. Also, compileSourceRoots and testCompileSourceRoots only become fully populated after running maven build lifecycle, which is expensive\. + +## Extensions \*\* Different categories of extensions: providers vs packaging vs PMD/Checkstyle resources stuff in a JAR \*\* Transparent Extension Loading \*\*\* Any Wagon or SCM providers should get picked up automatically from SCM and distributionManagement URLs \*\*\* Any extensions containing packaging/lifecycle related bits needs to be picked up automatically + diff --git a/content/markdown/developers/committer-environment.md b/content/markdown/developers/committer-environment.md new file mode 100644 index 0000000000..2a3f477f19 --- /dev/null +++ b/content/markdown/developers/committer-environment.md @@ -0,0 +1,44 @@ +--- +title: Developers centre - Committer Environment +author: + - Vincent Siveton +date: 2006-10-01 +--- + + + + + + + + + + + + + + + + + + +# Committer Environment + +## Introduction + +This document describes how to set up the Maven committer environment\. + +## Source File Encoding + +When editing source files, make sure you use the right file encoding\. For the Maven project, UTF\-8 has been chosen as the default file encoding\. UTF\-8 is an encoding scheme for the Unicode character set that can encode all characters that Java can handle\. The source files should not contain the byte order mark \(BOM\)\. There are exceptions to this general rule\. For instance, properties files are encoded using ISO\-8859\-1 as per the JRE API, so please keep this in mind, too\. + +## Maven Code Style + +Refer to [Maven Code Style And Code Conventions](\./conventions/code\.html) + +## Useful software + +The Maven Team uses assorted software\. Here is a partial list: + +- [Cygwin](https://www\.cygwin\.com/): collection of free software tools that allow various versions of Microsoft Windows to act somewhat like a Unix system +- [GnuPG](https://www\.gnupg\.org/): GNU Privacy Guard\. diff --git a/content/markdown/developers/committer-settings.md b/content/markdown/developers/committer-settings.md new file mode 100644 index 0000000000..737d3f9353 --- /dev/null +++ b/content/markdown/developers/committer-settings.md @@ -0,0 +1,76 @@ +--- +title: Developers centre - Committer Settings +author: + - Vincent Siveton + - Dennis Lundberg +date: 2011-05-23 +--- + + + + + + + + + + + + + + + + + + +# Introduction + +This document is intended to set up the Maven committer settings, i\.e\. the `${user.home}/.m2/settings.xml`\. + +## Enable Apache Servers + +Maven uses several servers configuration to deploy snapshots and releases on the Apache servers\. You need to tell to Maven what your Apache username is\. + +**It is highly recommended to use Maven's [ password encryption capabilities](\.\./guides/mini/guide\-encryption\.html) for your passwords**\. + +``` + + ... + + + + apache.snapshots.https + + + + + + apache.releases.https + + + + ... + + +``` + +## Enable sending announcement e\-mails + +To be able to send out announcements of Maven releases you need to add a couple of properties to the `apache-release` profile\. + +``` + + ... + + + apache-release + + + + + + ... + + +``` + diff --git a/content/markdown/developers/compatibility-plan.md b/content/markdown/developers/compatibility-plan.md new file mode 100644 index 0000000000..8e4529770b --- /dev/null +++ b/content/markdown/developers/compatibility-plan.md @@ -0,0 +1,48 @@ +--- +title: Maven Plugins Compatibility Plan +author: + - Hervé Boutemy +date: 2020-05-20 +--- + + + + + + + + + + + + + + + + + + +# Maven Plugins Compatibility Plan + +## Scope + +This page describes the system requirements plan, which consists of: + +1. minimum **Java** runtime prerequisite for Maven plugins, which can be extended to shared components, +1. minimum **Maven** runtime prerequisite for plugins\. + +Such requirements are displayed as "System Requirements" in every plugin info report \(see [this example](/plugins/maven\-clean\-plugin/plugin\-info\.html)\)\. + +Consolidated view for all LATEST plugins release is visible in a [daily generated report](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/dist\-tool\-prerequisites\.html)\. + +## Maven Plan + +- Until 2012, Maven 2\.2\.1 \+ Java 5 prerequisites, with plugins versions in 2\.x +- Since 2012, Maven 3\.0 \+ Java 7 prerequisites, with plugins in 3\.x\.y +- Since June 2020, Maven Plugin API used by plugins >= 3\.1\.0 \+ Java 8 prerequisites [Technical details](https://s\.apache\.org/MVN\-PLUGIN\-MIGRATION\-3\.1) +- In March 2023, Maven before 3\.2\.5 has been [marked as EOL](/docs/history\.html\#maven\-3\-6\-x\-and\-before), meaning that plugins should use 3\.2\.5 as minimum +- In April 2023, Maven before 3\.6\.3 has been [marked as EOL](/docs/history\.html\#maven\-3\-6\-x\-and\-before), meaning that plugins should use 3\.6\.3 as minimum +- In February 2024, Maven 4 after 4\.0\.0\-alpha\-12 will require Java 17 \(as per [vote on the Mailing List](https://lists\.apache\.org/thread/bfkvvjftrxypp06yj8zj919fcz0dt2zt)\)\. +## Context + +- Maven core history with Java prerequisite is available in the [release notes](/docs/history\.html) diff --git a/content/markdown/developers/conventions/code.md b/content/markdown/developers/conventions/code.md new file mode 100644 index 0000000000..b46b1bc50e --- /dev/null +++ b/content/markdown/developers/conventions/code.md @@ -0,0 +1,199 @@ +--- +title: Maven Code Style And Code Conventions +author: + - Vincent Siveton +date: 2008-07-05 +--- + + + + + + + + + + + + + + + + + + +# Maven Code Style And Code Conventions + +This document describes the rules for how the sources should be formatted in order to improve consistency, readability and maintainability\. + +As the formatting is automatically enforced or even applied with [spotless\-maven\-plugin](https://github\.com/diffplug/spotless/tree/main/plugin\-maven) for all projects using [Maven Project Parent POM 38 or newer](/pom/maven/index\.html) developers usually don't need to care and the following sections are just for informational purposes\. + +Optionally you can still import the code style formatter for your IDE from [shared\-resources](https://gitbox\.apache\.org/repos/asf?p=maven\-shared\-resources\.git;a=tree;f=src/main/resources/config;hb=HEAD) + +- [Generic Code Style And Convention](Generic\_Code\_Style\_And\_Convention) +- [Java](Java) + - [Java Code Style](Java\_Code\_Style) + - [Java Code Convention](Java\_Code\_Convention) + - [Java Code Convention \- import layouts](Java\_Code\_Convention\_\-\_import\_layouts) + - [JavaDoc Convention](JavaDoc\_Convention) +- [XML](XML) + - [XML Code Style](XML\_Code\_Style) + - [Generic XML Code Convention](Generic\_XML\_Code\_Convention) + - [POM Code Convention](POM\_Code\_Convention) + - [XDOC Code Convention](XDOC\_Code\_Convention) + - [FML Code Convention](FML\_Code\_Convention) +## Generic Code Style And Convention + +All working files \(java, xml, others\) should respect the following conventions: + +- **License Header**: Always add the current [ASF license header](https://www\.apache\.org/legal/src\-headers\.html\#headers) in all files checked into the source code repository\. +- **Trailing Whitespace**: No trailing whitespaces allowed\. + +and the following style: + +- **Indentation**: **Never** use tabs\! +- **Line wrapping**: Always use a 120\-column line width\. + +**Note**: The specific styles and conventions, listed in the next sections, can override these generic rules\. + +## Java + +### Java Code Style + +Maven adopts the [palantir Java format](https://github\.com/palantir/palantir\-java\-format)\. + +### Java Code Convention + +For consistency reasons, our Java code convention is mainly: + +- **Naming**: Constants \(i\.e\. static final members\) should always be in upper case\. Use short, descriptive names for classes and methods\. +- **Organization**: Avoid using public inner classes\. Prefer interfaces instead of default implementation\. +- **Modifier**: Avoid using final modifier on all fields and arguments\. Prefer using private or protected fields instead of public fields\. +- **Exceptions**: Throw meaningful exceptions to make debugging and testing easier\. +- **Documentation**: Document public interfaces well, i\.e\. all non\-trivial public and protected functions should include Javadoc that indicates what they do\. +- **Testing**: All non\-trivial public classes should have corresponding unit or integration tests\. +### Java Code Convention \- import layouts + +For consistency reasons, Java imports should be organized as: + +- import **javax\.\*** +- import **java\.\*** +- blank line +- import **all other imports** + +all imports in each group should be sorted alphabetically\. + +To ensure a package import order consistent with the layout described above, download [`maven-eclipse-importorder.txt`](https://gitbox\.apache\.org/repos/asf?p=maven\-shared\-resources\.git;a=blob\_plain;f=src/main/resources/config/maven\-eclipse\-importorder\.txt;hb=HEAD), select _Window > Preferences_ and navigate to _Java > Code Style > Organize Imports_\. Click on _Import\.\.\._ and select the downloaded file to change the import order\. + +### JavaDoc Convention + +TO BE DISCUSSED + +## XML + +### XML Code Style + +The Maven style for XML files is mainly: + +- **Indentation**: Always use 2 space indents, unless you're wrapping a new XML tags line in which case you should indent 4 spaces\. +- **Line Breaks**: Always use a new line with indentation for complex XML types and no line break for simple XML types\. Always use a new line to separate XML sections or blocks, for instance: + + ``` + + This is a simple type + + + This is a complex type + + + ``` + + In some cases, adding comments could improve the readability of blocks, for instance: + + ``` + + ``` + + or + + ``` + + + + ``` + +### Generic XML Code Convention + +No generic code convention exists yet for XML files\. + +### POM Code Convention + +The team has [voted](https://lists\.apache\.org/thread/h8px5t6f3q59cnkzpj1t02wsoynr3ygk) during the end of June 2008 to follow a specific POM convention to ordering POM elements\. The consequence of this vote is that the [Maven project descriptor](https://maven\.apache\.org/ref/current/maven\-model/maven\.html) is **no more** considered as the reference for the ordering\. + +The following is the recommended ordering for all Maven POM files: + +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**Comments**: + +1. The <project/> element is always on one line\. +1. The blocks are voluntary separated by a new line to improve the readingness\. +1. The dependencies in <dependencies/> and <dependencyManagement/> tags have no specific ordering\. Developers are free to choose the ordering, but grouping dependencies by topics \(like groupId i\.e\. `org.apache.maven`\) is a good practice\. +### XDOC Code Convention + +For consistency and readability reasons, XDOC files should respect: + +- **Metadata**: Always specify metadata in the <properties/> tag\. +- **Sections**: Always use a new line with indentation for <section/> tags\. +### FML Code Convention + +For readability reasons, FML files should respect: + +- **FAQ**: Always use a new line with indentation for <faq/> tags\. + diff --git a/content/markdown/developers/conventions/git.md b/content/markdown/developers/conventions/git.md new file mode 100644 index 0000000000..3329c623c6 --- /dev/null +++ b/content/markdown/developers/conventions/git.md @@ -0,0 +1,184 @@ +--- +title: Maven Git Convention +author: + - Olivier Lamy +date: 2012-09-12 +--- + + + + + + + + + + + + + + + + + + +# Maven Git Convention + +This document describes how developers should use Git\. + +## Git Configuration + +### For contributors who are not committers + +Apache git repositories are at _ <<git://git\.apache\.org_>>\. However, the ASF uses clones on github\.com to make it easier for people to contribute changes via pull requests\. + +To contribute to a Maven component that is maintained in git, please follow these steps: + +1. create a JIRA for bug or improvement that you wish to work on\. The Maven project uses JIRA to organize and track our work, and in particular to keep track of which changes are included in which releases\. +1. Make a fork of the official ASF clone from github\.com\. For example, `https://github.com/apache/maven-scm`\. +1. Make a branch named after your JIRA ticket\. This is not _required_, but it makes it easier for Maven committers to keep track of your contribution\. +1. Make your changes\. As always, unit or integration tests make it much easier for us to accept your changes\. +1. Make a pull request to pull your changes to the official clone\. Add a link to your pull request to the JIRA\. Committers will take it from here\. +### For committers + +Committers may, of course, commit directly to the ASF repositories\. For complex changes, you may find it valuable to make a pull request at github to make it easier to collaborate with others\. + +#### Commit Message Template + +Commits should be focused on one issue at a time, because that makes it easier for others to review the commit\. + +A commit message should use this template: + +``` +[ISSUE-1] <> +Submitted by: <> + +o Comments +``` + +Where: + +- **ISSUE\-1** can be omitted if there was no relevant JIRA issue, though you are strongly encouraged to create one for significant changes\. +- **Submitted by** only needs to be specified when a patch is being applied for a non\-committer\. +- **Comments** some optional words about the solution\. + +eg: + +``` +[MNG-1456] Added the foo to the bar +Submitted by: Baz Bazman + +o Applied without change +``` + +## Apply User Patch + +To keep the history of contributions clear, The committer should usually apply the patch without any **major** modifications, and then create his or her own commits for further modifications\. However, committers should never commit code to a live branch which is not suitable to release\. If a contribution requires significant work to make it useful, commit it to a branch, fix it up, and merge the branch\. + +If the user created a pull request, the committer is responsible for closing that pull request\. You do this by adding a note to a commit message: + +``` + Closes #NNN. +``` + +where NNN is the number of the pull request\. + +## Edit Commit Message + +to edit last commit comment: + +``` +$ git commit --amend -m "new comment" +``` + +## Workflow + +Workflow for svn folks is something like : + +``` + $ git pull + $ hack hack hack + $ git push + // fails, because someone else has already pushed to master + $ git pull + // this creates some merges + $ git push +``` + +A more quiet workflow : + +``` +$ git pull +$ hack hack hack +$ git push +// fails, because someone else has already pushed to master +$ git fetch +// this moves 'origin/master' +$ git rebase origin/master +// this reapplies your local changes on top of origin/master +$ git push +``` + +## Other useful Git commands while developing + +If you've done a chunk of work and you would like to ditch your changes and start from scratch use this command to revert to the original checkout: + +``` +$ git checkout . +``` + +TODO \.gitignore + +### power\-git checkout + +This checkout is typical for highly experienced git users, and may serve as inspiration for others; as usual the best way to learn is by doing\. Sample shown for maven\-surefire + +Go to https://github\.com/apache/maven\-surefire and fork surefire to your own github account\. + +Starting with nothing \(no existing clone\) + +``` +git clone https://github.com//maven-surefire.git +git remote add apache https://git-wip-us.apache.org/repos/asf/maven-surefire.git +git remote add asfgithub https://github.com/apache/maven-surefire.git +git config --add remote.asfgithub.fetch "+refs/pull/*/head:refs/remotes/asfgithub/pr/*" +git fetch --all +``` + +\(You may consider adding \-\-global to the git config statement above to always fetch pull requests for any remote named "asfgithub"\) + +In this setup, running "git push" will normally push to your personal github account\. Furthermore, all pull requests from github are also fetched to your local clone, use + +``` +gitk --all +``` + +to try to make some sense of it all\. This is an important command to understand\! \(gitk may need to be installed additionally\) + +gitk also has a quite excellent context menu that is far more context sensitive than most people realize at first impression\. Right\-clicking on a commit in a github pull\-request will allow you to cherry\-pick straight in the gui\. + +If you're working on the master branch, you can do stuff like this: + +``` +git push # your github account +git push apache # the authoritative apache repo +``` + +Using your github account as a storage for half\-finished work is excellent if you switch between multiple computers, always push to github before leaving your current computer and start by pulling at the next computer\. + +To merge a pull request + +``` +git merge pr/10 # merge pull request number 10 from asf@github into master +git push apache # upload to apache +``` + +Or if you're comfortable with rebasing; + +``` + +git checkout pr/10 +git rebase apache/master +git push apache +``` + diff --git a/content/markdown/developers/dependency-policies.md b/content/markdown/developers/dependency-policies.md new file mode 100644 index 0000000000..fa1da2dc05 --- /dev/null +++ b/content/markdown/developers/dependency-policies.md @@ -0,0 +1,59 @@ +--- +title: Maven Dependency Policies +author: + - Stephen Connolly +date: 2011-02-01 +--- + + + + + + + + + + + + + + + + + + +# Maven Dependency Policies + +## Scope + +This page describes the policies around the use of dependencies by the Apache Maven Developers in the process of developing Apache Maven itself\. + +This page does not apply to projects hosted outside of the Apache Maven project\. In order to remove all doubt, this page only applies to code which has a Github URL that starts with `https://github.com/apache/maven` or a Gitbox URL starting with `https://gitbox.apache.org/repos/asf?p=maven` + +If you have stumbled across this page and you are working on code that does not have a Github URL starting with `https://github.com/apache/maven` then this page does not apply to you\. + +## Background + +The Apache Maven PMC is tasked with ensuring \(among other things\) that all legal issues are addressed and that each and every release is the product of the community as a whole\. + +The Apache Maven project consists of quite a number of components\. For the purposes of this policy, we will make a distinction between the core Maven distribution and all the other components\. + +The core Maven distribution is the binary and source distributions made available from the https://maven\.apache\.org/download page\. + +## Applicability + +This policy applies to all changes to dependencies as and from Subversion revision 1067464\. + +## Core Maven Distribution Dependencies + +All dependencies which are included in the Core Maven Distribution must either: + +- be licensed under a [Category A license](https://www\.apache\.org/legal/resolved\.html\#category\-a); or +- be licensed under a [Category B license](https://www\.apache\.org/legal/resolved\.html\#category\-b) and approved by a majority vote of the Apache Maven PMC\. + +Votes for Category B licenses will be held on the dev@maven\.apache\.org mailing list\. A majority of the PMC must vote in favour of a Category B licensed dependency before a release can be made containing that dependency\. + +## Non\-Core Dependencies + +Non\-Core components may only use Category A or Category B licenses\. + diff --git a/content/markdown/developers/index.md b/content/markdown/developers/index.md new file mode 100644 index 0000000000..e7eb040061 --- /dev/null +++ b/content/markdown/developers/index.md @@ -0,0 +1,75 @@ +--- +title: Maven Developer Centre +author: + - Vincent Siveton + - Brett Porter +date: 2015-02-14 +--- + + + + + + + + + + + + + + + + + + +# Maven Developer Centre + +This documentation centre is for people who are Maven developers, or would like to contribute\. + +If you cannot find your answers here, feel free to ask the [Maven Developer List](mailto:dev@maven\.apache\.org)\. + +## Contributors Resources + +- [Guide to helping with Maven](\.\./guides/development/guide\-helping\.html) +- [Developing Maven](\.\./guides/development/guide\-maven\-development\.html) +- [Building Maven](\.\./guides/development/guide\-building\-maven\.html) +- [Source Code](\.\./scm\.html) +- [Continuous Integration](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/) +- [Common Bugs and Pitfalls](\.\./plugin\-developers/common\-bugs\.html) +- [Apache Maven Project Roles](\.\./project\-roles\.html) +## Committers Resources + +### General Resources + +- [Guide for new Maven committers](\./welcome\-to\-new\-committers\.html) +- [Committer Environment](\./committer\-environment\.html) +- [Committer Settings](\./committer\-settings\.html) +- [Retirement Plan for Plugins](\./retirement\-plan\-plugins\.html) +- [Maven Dependency Policies](\./dependency\-policies\.html) +- [Maven Plugins and Components Compatibility Plan](\./compatibility\-plan\.html) +- [Maven Proposals/Backlog](https://cwiki\.apache\.org/confluence/pages/viewpage\.action?pageId=5964567) +## Developers Conventions + +There are a number of conventions used in the Maven projects, which contributors and developers alike should follow for consistency's sake\. + +- [Maven Code Style And Conventions](\./conventions/code\.html) +- [Maven JIRA Convention](\./conventions/jira\.html) +- [Maven Git Convention](\./conventions/git\.html) + +**Note**: If you cannot find your answers here, feel free to ask the [Maven Developer List](mailto:dev@maven\.apache\.org)\. + +## Making Releases + +- [Making GPG Keys](\./release/pmc\-gpg\-keys\.html) +- [Release Process](\./release/index\.html) +## Maven Website + +- [Deploy Maven Website](\./website/index\.html) +## Other Resources + +- [ASF Development Infrastructure Information](https://www\.apache\.org/dev/) +- [About the Apache Software Foundation](https://www\.apache\.org/foundation/) + + + diff --git a/content/markdown/developers/release/index.md b/content/markdown/developers/release/index.md new file mode 100644 index 0000000000..25f382982c --- /dev/null +++ b/content/markdown/developers/release/index.md @@ -0,0 +1,37 @@ +--- +title: Releasing A Maven Project +author: + - Jason van Zyl +date: 2010-07-26 +--- + + + + + + + + + + + + + + + + + +# Releasing A Maven Project + +What follows is a description of releasing a Maven project to a staging repository and its documentation, whereupon it is scrutinized by the community, approved, and transferred to a production repository\. + +The steps involved are similar for any Apache project, with more specifics for parent POMs and Maven itself\. The steps involved, and the relevant documents for each, are listed below\. + + + +- [ Releasing Maven Core](\./maven\-core\-release\.html) +- [ Releasing a parent POM](\./parent\-pom\-release\.html) + +The above links all provide specific information for those types of releases, but they all refer back to the common documentation: + +- [ Maven Project Common Release procedure](\./maven\-project\-release\-procedure\.html) diff --git a/content/markdown/developers/release/maven-project-release-procedure.md b/content/markdown/developers/release/maven-project-release-procedure.md new file mode 100644 index 0000000000..ca35632268 --- /dev/null +++ b/content/markdown/developers/release/maven-project-release-procedure.md @@ -0,0 +1,304 @@ +--- +title: Releasing A Maven Project +author: + - Jason van Zyl + - Karl Heinz Marbaise +date: 2018-04-07 +--- + + + + + + + + + + + + + + + + + +# Performing a Maven Project Release + +This document covers the common release procedures used by the Maven team to perform releases\. + +## Prerequisites + +Be sure that: + +- you have a recent Git client installed and on your shell's path\. +- you have JDK 8 installed and on your shell's path to build Maven 3\.7\.0\+\. Details about minimum JDK version to build an appropriate version can be found here: [https://maven\.apache\.org/docs/history\.html](/docs/history\.html) +- if you receive an OutOfMemoryError during the build, make sure to have set the environment variable `MAVEN_OPTS=-Xmx512m` +- you must use Maven 3\.3\.9\+\. +- follow Apache environment configuration steps outlined at: [Publishing Maven Artifacts](https://www\.apache\.org/dev/publishing\-maven\-artifacts\.html\#dev\-env)\. +- check [ your Public GPG key](\./pmc\-gpg\-keys\.html) which will be used for release\. +## Before you begin + +If you started here, you may first want to review one of the following documents that cover the specifics of various types of releases we have in the Maven Project: + +- [ Releasing Maven Core](\./maven\-core\-release\.html) +- [ Releasing a parent POM](\./parent\-pom\-release\.html) +## Consider updating the parent versions + +If the item you are planning to release is not using the most recent version of its parent \(see [parent POMs](\.\./\.\./pom/) index\), consider taking this opportunity to update to it\. + +## Consider updating the project dependencies + +Generally it is a good that project use tha latest available versions of used dependencies\. + +## Prepare release notes + +- check all commits since latest release, all mentioned issue should be connected with release notes +- all issues should be **assigned** to responsible person, which fixed or merged fix +- all issues should be fixed and **CLOSED** +- check existing issues with **Blocker** priority, consider to fix it or change priority if reasonable +### Check release note at GitHub + +If a component has a history of release notes at **GitHub**, we should to continue maintain it in order to avoid user confusing\. + +We can maintain release notes at **GitHub**, by one of: + +- use release\-drafter to help prepare release notes \- in such case all PRs should a proper label +- copy paste release notes from JIRA +- put link to release notes in JIRA + +Draft of release notes at **GitHub** can be prepared before publishing\. + +## Make sure that site compilation works + +Particularly if you update the parent or if you updated your javadoc, the site compilation process may fail, or reveal a conspicuous error\. It is stressful and time\-consuming to discover this \*after\* you stage a release and then try to follow the procedure to deploy the site for review\. So you may find it more pleasant to check out the state of the site before you start: + +``` +mvn -Preporting site site:stage +``` + +## Stage the Release + +1. Follow the release preparation, **staging** and **closing** the repository steps outlined in [Publishing Maven Releases](https://infra\.apache\.org/publishing\-maven\-artifacts\.html)\. + + Staging repository `MUST` be closed with message like `VOTE Maven component name x.y.z` + +1. Stage the latest documentation as explained in [deploying Maven components reference documentation](\.\./website/deploy\-component\-reference\-documentation\.html)\. +## Call the vote + +Propose a vote on the dev list with the closed issues, the issues left, the staging repository and the staging site\. For instance: + +``` +To: "Maven Developers List" +Subject: [VOTE] Release Apache Maven XXX Plugin version Y.Z + +Hi, + +We solved N issues: +https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=XXXXXX&version=YYYYYYY&styleName=Text + +There are still a couple of issues left in JIRA: +https://issues.apache.org/jira/issues/?jql=project%20%3D%20XXXXXXXXXX%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20key%20DESC%2C%20priority%20DESC + +Staging repo: +https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/ +https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/[PATH-TO]-source-release.zip + +Source release checksum(s): +[NAME-OF]-source-release.zip sha512: [SHA512SUM] + +Staging site: +https://maven.apache.org/plugins-archives/maven-XXX-plugin-LATEST/ + +Guide to testing staged releases: +https://maven.apache.org/guides/development/guide-testing-releases.html + +Vote open for at least 72 hours. + +[ ] +1 +[ ] +0 +[ ] -1 +``` + +To get the JIRA release notes link, browse to the plugin's or component's JIRA page, select the _Releases_ link, pick a version, and use the link to _Release Notes_ that is next to the version being released\. + +To get the list of issues left in JIRA, browse to the plugin's or component's JIRA page, and from the _Preset Filters_ on the right, use the link for _Outstanding_ issues\. + +The "vote is open for at least 72 hours" means that you need to wait _at least_ 72 hours before proceeding\. This gives others time to test your release and check that everything is good\. If after that period you have not received enough \+1 votes to reach the quorum, this doesn't mean the vote failed: it just takes a bit longer\. + +Checking binary output, ideally to control that the build is reproducible, can be done by running `verify` \(NOT `install`\) followed by `artifact:compare` against the staged content: + +``` +mvn -Papache-release -Dgpg.skip clean verify \ + artifact:compare -Dreference.repo=https://repository.apache.org/content/repositories/staging/ +``` + +## Check the vote results + +Copied from [Votes on Package Releases](https://www\.apache\.org/foundation/voting\.html\#ReleaseVotes)\. + +``` +Votes on whether a package is ready to be released use majority approval +-- i.e. at least three PMC members must vote affirmatively for release, +and there must be more positive than negative votes. Releases may not be vetoed. +Generally the community will cancel the release vote if anyone identifies serious problems, +but in most cases the ultimate decision, lies with the individual serving as release manager. +The specifics of the process may vary from project to project, +but the 'minimum quorum of three +1 votes' rule is universal. +``` + +The list of PMC members is available at [https://people\.apache\.org/committers\-by\-project\.html\#maven\-pmc](https://people\.apache\.org/committers\-by\-project\.html\#maven\-pmc)\. + +### Successful vote + +Once a vote is **successful**, post the result to the `dev` list and cc the `PMC`\. For instance: + +``` +To: "Maven Developers List" +CC: "Maven Project Management Committee List" +Subject: [RESULT] [VOTE] Release Apache Maven XXX Plugin version Y.Z + +Hi, + +The vote has passed with the following result: + ++1 : <> + +PMC quorum: ... + +I will promote the source release zip file to Apache distribution area and the artifacts to the central repo. +``` + +Follow the procedure to the end\. + +### Unsuccessful vote + +Once a vote is **unsuccessful**, post the result to the `dev` list, For instance: + +``` +To: "Maven Developers List" +Subject: [CANCEL] [VOTE] Release Apache Maven XXX Plugin version Y.Z + +Hi, + +The vote has been canceled. +``` + +For canceled vote the process will need to be restarted\. + +Be sure to: + +- drop your staging repository as described in [Drop a repository](https://www\.apache\.org/dev/publishing\-maven\-artifacts\.html) +- create new version for next round `Y.Z+1` +- assign issues from version `Y.Z` also to version `Y.Z+1` +- mark the `Y.Z` version as **archived** +- report found issues and assign them to version `Y.Z+1` +- fix found issues + +Start the process for version `Y.Z+1` from the beginning\. + +## Copy the source release to the Apache Distribution Area + +The official Apache release is the 'source\-release' bundle distributed in `www.apache.org/dist`, as described in [Apache Release Distribution Policy](https://www\.apache\.org/dev/release\-distribution)\. All releases for Maven must be copied to [the official Maven release area](https://www\.apache\.org/dist/maven/)\. + +The release area is maintained with svnpubsub\. To deliver a release, you add it to [the subversion repository for the dist area](https://dist\.apache\.org/repos/dist/release/maven): add the release, its signature and sha512 checksum files, copying them from `target/checkout/target/` directory created during `mvn release:perform` step\. Currently this requires to be in maven\-pmc group \(see [INFRA\-5945](https://issues\.apache\.org/jira/browse/INFRA\-5945)\)\. If you are not a PMC member, drop a line to _private@maven\.apache\.org_ and ask them to do this step \(and the next one\) for you: the PMC member will get the source release bundle and its signature from Nexus staging repository and will create sha512 checksum file by hand, for example using shell: + +``` +for f in *.zip ; do echo -n $(sha512sum $f | cut -c -128) > $f.sha512 ; done +``` + +For example: + +``` +wagon/wagon-2.2-source-release.zip +wagon/wagon-2.2-source-release.zip.asc +wagon/wagon-2.2-source-release.zip.sha512 +``` + +You should also run 'svn rm' as needed to clear out older releases\. As per [Apache Release Policy](https://www\.apache\.org/legal/release\-policy\.html\#where\-do\-releases\-go), only the latest release on a branch should stay in the main dist areas\. So long as the previous release is at least a day old, the automatic archiver will have copied it to the archive\. + +To check that everything is ok in the dist area, dist\-tool\-plugin has been written and run once a day to produce ["Check Source Release" and "Check Errors" reports](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/)\. + +## Add the release for next board report + +After committing the 3 source\-release files, visit [Apache Committee Report Helper](https://reporter\.apache\.org/addrelease\.html?maven) to add your release data with the Full Version Name and Date of Release\. \(You will receive an e\-mail for it as well\)\. + +If you are not a PMC member, drop a line to _private@maven\.apache\.org_ and ask them to do this step for you if they did not do the update while adding to release area\. + +## Promote the release + +Once the release is deemed fit for public consumption it can be transferred to a production repository where it will be available to all users\. + +1. See [Promoting a Repo](https://www\.apache\.org/dev/publishing\-maven\-artifacts\.html\#promote) for details on promotion\. +1. Deploy the current website + + As above, deploy the web site if appropriate and update the project site for the new release: use [Component Reference Documentation Helper](\.\./website/component\-reference\-documentation\-helper\.html) to generate commands or see [Publishing versioned component reference documentation](\.\./website/deploy\-component\-reference\-documentation\.html\#Publishing\_versioned\_component\_reference\_documentation) for explanations\. Note that not all projects follow these conventions exactly\. + + In case there's an overview table with version \(e\.g\. [plugins](/plugins/index\.html), [shared](/shared/index\.html), [skins](/skins/index\.html)\), update the table: you can directly edit it on the github page\. + + For plugins and shared, you can also run `mvn -Pupdate package` of the site, then review and commit proposed `index.apt` updates\. + +1. Update the version tracking in JIRA + + In the relevant project, go to Administration, then Versions\. Mark the `Y.Z` version as 'released'\. Create version `Y.Z+1`, if that hasn't already been done\. You may also archive any deprecated releases \(milestones or alphas\) at this time\. + + Note: Currently this requires to be in the maven\-pmc group\. So, if you don't see the Administration option in JIRA, kindly ask _private@maven\.apache\.org_ to do this step for you\. + +1. Wait for everything to sync + 1. Sync to [Maven Central](https://repo\.maven\.apache\.org/maven2/org/apache/maven/) + + The sync into central staging from repository\.apache\.org occurs every 4 hours\. There is a separate hourly schedule that runs which pushes from staging to the other central machines, and then updates the indexes\. + + 1. Sync to Maven Website + + If the project you are releasing doesn't yet use svnpubsub for site deployment, the deployment of the Maven website will [take an hour or so to sync](https://www\.apache\.org/dev/release\-publishing\.html\#sync\-delay)\. + +1. Create an announcement\. + + Following instructions are done for plugins: if you are releasing anything else than a plugin, you should adapt email content to match what you are releasing\. + + **Note:** You must send this email from your apache email account, e\.g\. YOUR\_APACHE\_USERNAME@apache\.org otherwise the email to `announce@maven.apache.org` will bounce\. + + ``` + From: YOUR_APACHE_USERNAME@apache.org + To: announce@maven.apache.org, users@maven.apache.org + Cc: dev@maven.apache.org + Subject: [ANN] Apache Maven XXX Plugin Y.Z Released + + The Apache Maven team is pleased to announce the release of the Apache Maven XXX Plugin, version Y.Z + + This plugin (insert short description of the plugin's purpose). + + https://maven.apache.org/plugins/maven-XXX-plugin/ + + You should specify the version in your project's plugin configuration: + + + org.apache.maven.plugins + maven-XXX-plugin + Y.Z + + + You can download the appropriate sources etc. from the download page: + + https://maven.apache.org/plugins/maven-XXX-plugin/download.cgi + + Release Notes - Maven XXX Plugin - Version Y.Z + + (Copy Here Release Notes in Text Format from JIRA) + + Enjoy, + + -The Apache Maven team + + ``` + +1. If releasing the Apache Parent POM, notify `release-discuss@apache.org`: Several projects follow this list, and should be made aware of changes to the common parent\. This might also be a step to take if other shared resources are released, or if plugin releases are of particular interest to that group\. + + If releasing Maven Core, notify `announce@apache.org` + +1. Publish release notes at **GitHub** if it is maintained\. +1. Celebrate :o\) +## Check Consistency + +You can also check if you \(or any previous release manager\) did not miss any step by looking at the [ Dist Tool Check Errors report](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/dist\-tool\-check\-errors\.html)\. + diff --git a/content/markdown/developers/release/parent-pom-release.md b/content/markdown/developers/release/parent-pom-release.md new file mode 100644 index 0000000000..872233429b --- /dev/null +++ b/content/markdown/developers/release/parent-pom-release.md @@ -0,0 +1,75 @@ +--- +title: Releasing A Parent POM +author: + - Hervé Boutemy + - Dennis Lundberg +date: 2013-12-07 +--- + + + + + + + + + + + + + + + + + +# Releasing A Parent POM + +Releasing a Parent POM is much the same as any other Maven project\. The following guide walks through most of the steps: + +- [ Maven Project Common Release procedure](\./maven\-project\-release\-procedure\.html) + +Note that Parent POMs have particular conventions for managing and deploying the documentation\. + +## Rationale + +To be able to publish a documentation for the parent POM without affecting released `pom.xml` and `site.xml`, parent POM projects have a specific module, with the documentations `docs`\. + +## Stage the release + +Then the only difference is with commands to stage the site: + +In Maven Apache Parent POM: + +``` +cd target/checkout +mvn -f docs site +mvn -f docs scm-publish:publish-scm +``` + +In Maven Projects Parent POM: + +``` +cd target/checkout +mvn -f docs site site:stage +mvn -f docs scm-publish:publish-scm +``` + +## Call the vote + +In the vote, additional to providing links to JIRA, the parent POMs should include a link to the Git changes since the last release: + +``` +... +Hi, + +Changes since the last release: +for Maven Apache Parent POM: +https://github.com/apache/maven-apache-parent/compare/apache-...apache- + +or for Maven Projects Parent POM: +https://github.com/apache/maven-parent/compare/maven-parent-...maven-parent- + +Staging repo: +... +``` + diff --git a/content/markdown/developers/release/pmc-gpg-keys.md b/content/markdown/developers/release/pmc-gpg-keys.md new file mode 100644 index 0000000000..010c8b7c68 --- /dev/null +++ b/content/markdown/developers/release/pmc-gpg-keys.md @@ -0,0 +1,64 @@ +--- +title: Developers centre - Making GPG Keys +author: + - Vincent Siveton +date: 2006-10-01 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +**Before** a release You need to publish your Public GPG Keys in several place used by different tools for verifying release signatures\. + +All Your historical Public Keys should be available for verifying historical releases, so please **don't remove** any key used sometime\. + +All new **RSA** keys generated should be at least **4096** bits\. Do not generate new DSA keys\. + +## Maven Project Keys + +Public Keys used for signing Maven core, plugins and shared components are available for users at: +[https://downloads\.apache\.org/maven/KEYS](https://downloads\.apache\.org/maven/KEYS) + +You need edit a file and follow provided instructions in SVN at: +[https://svn\.apache\.org/repos/asf/maven/project/KEYS](https://svn\.apache\.org/repos/asf/maven/project/KEYS) + +General ASF instruction + +- [Update keys on the next release](https://infra\.apache\.org/openpgp\.html\#update\-KEYS) +- [The KEYS File](https://infra\.apache\.org/release\-signing\.html\#keys\-policy) +## Distributing Your Public Keys + +Your Public Keys **MUST** be available at public key server, you can use one or even all of currently common used key server + +- [https://keys\.openpgp\.org](https://keys\.openpgp\.org) +- [https://keyserver\.ubuntu\.com](https://keyserver\.ubuntu\.com) +- [https://pgp\.mit\.edu](https://pgp\.mit\.edu) +## Committer public key files + +You should also add Your Public Keys to [ASF Committer public key files](https://people\.apache\.org/keys/committer) + +Please follow instructions at: [https://people\.apache\.org/keys](https://people\.apache\.org/keys) + +## Generate a new key + +Please follow ASF infrastructure instruction: + +- [Generate a new key](https://infra\.apache\.org/openpgp\.html\#key\-gen\-generate\-key) +- [How to generate a strong key](https://infra\.apache\.org/openpgp\.html\#generate\-key) diff --git a/content/markdown/developers/retirement-plan-plugins.md b/content/markdown/developers/retirement-plan-plugins.md new file mode 100644 index 0000000000..5c824c6ffd --- /dev/null +++ b/content/markdown/developers/retirement-plan-plugins.md @@ -0,0 +1,121 @@ +--- +title: Retirement Plan for Plugins +author: + - Dennis Lundberg +date: 2013-07-26 +--- + + + + + + + + + + + + + + + + + + +# Retirement Plan for Plugins + +## Decide to retire + +Propose a vote on the dev\-list to retire a plugin\. The vote should be open for the standard 72 hours to allow people to voice their opinions\. Send a cc to the users\-list\. Standard Apache voting rules apply\. Only PMC votes are binding\. + +The vote must contain one or more options on how to retire the plugin\. There are multiple scenarios available\. Here are a couple that have been suggested: + +1. Move to our retired area in svn +1. Move to another Apache project +1. Move to www\.mojohaus\.org, apache\-extras\.org or another forge + +Here's a template for scenario A that can be used for the vote email: + +``` +To: "Maven Developers List" +Cc: "Maven Users List" +Subject: [VOTE] Retire Maven Foo Plugin + +Hi, + +A paragraph giving the reasons why the plugin should be retired. Make a note of +how long it has been since the latest release. + +I therefore propose that we retire maven-foo-plugin. + +If this vote is successful I will make one final release of the plugin, making +it clear on the plugin site that it has been retired. After that the source code +will be moved into the "retired" area in Subversion. + +The process for retiring a plugin is described here: +https://maven.apache.org/developers/retirement-plan-plugins.html + +The vote is open for 72 hours. + +[ ] +1 Yes, it's about time +[ ] -1 No, because... +``` + +If the vote is successful, post the result to the dev list and cc the PMC and users list\. For instance: + +``` +To: "Maven Developers List" +Cc: "Maven Users List" +CC: "Maven Project Management Committee List" +Subject: [RESULT] [VOTE] Retire Maven Foo Plugin + +Hi, + +The vote has passed with the following result: + ++1 (binding): <> ++1 (non binding): <> + +I will continue with the steps required to retire this plugin. +``` + +If the vote passes, make one final release of the plugin \(with its own standard 72h vote on source release\) before it is retired\. This allows us to make a clean break\. The person who wants to retire a plugin is the one who does the final release\. Below you will find the extra steps that you need to follow when retiring a plugin, in addition to [our standard release process](\./release/maven\-project\-release\-procedure\.html)\. + +## Make the final release + +1. Create an issue in JIRA with the issue type "Task" and the summary "Retire this plugin", and schedule it for the final release\. If the plugin includes a JIRA report in the generated site, you will need to close this issue before you make the release\. +1. Add the description "This is the final version of this plugin\. It has been retired\." to the final version in JIRA\. +1. Add a prominent notice on the front page of the plugin's site, informing that the plugin is retired\. Suggested text: + + ``` + Note: This plugin is retired. It is no longer maintained. + ``` + + If the plugin is moved elsewhere, that should also be added to the plugin's site\. Suggested text: + + ``` + Note: This plugin has retired from the Apache Maven project, + but has moved to the project. + ``` + +1. Add " \(RETIRED\)" at the end of ``/`` in the plugin's `pom.xml`\. This will show up on every page of the generated site\. +1. Go ahead with [the standard release process](\./release/maven\-project\-release\-procedure\.html), making sure that you follow the exceptions mentioned above regarding the site deployment\. +1. When updating the plugins page, move Maven Foo Plugin to under the "Retired" heading\. Remove the SVN and JIRA links and add the date of retirement\. +1. When updating the version in JIRA, do not add Y\.Z\+1 and make sure you remove any future versions\. +## Clean up after the release + +1. Remove the `.Jenkinsfile` from all branches\. This will remove the project from https://builds\.apache\.org/job/maven\-box/ +1. Remove the `.github` directory from default branch\. This will remove GitHub Actions +1. Ask INFRA for archive git repos \(gitbox \+ github\) +1. Republish documentation, postfix project name with \(RETIRED\) +1. When relevant update summary pages for [plugins](https://maven\.apache\.org/plugins/index\.html) or [shared components](https://maven\.apache\.org/shared/index\.html) +1. Add " \(RETIRED\)" at the end of the project name in JIRA\. +1. Put the JIRA project in read\-only mode in case of standalone project \(own Jira key\): apply Maven Retired Project Permissions Scheme\. \(Requires JIRA admin karma: e\.g\. ask Brian Fox\) +1. Comment the [dist\-tool configuration](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/dist\-tool\.conf\.html) entry\. +1. Remove from `Source Repository` + 1. [https://maven\.apache\.org/scm\.html](https://maven\.apache\.org/scm\.html) + 1. [https://github\.com/apache/maven\-sources](https://github\.com/apache/maven\-sources) +1. Remove distribution from current [dist area](https://dist\.apache\.org/repos/dist/release/maven/) \(history remains available in [archive](https://archive\.apache\.org/dist/maven/)\)\. +1. Update board report +1. Announce the fact that the plugin has been retired/moved on the announce@m\.a\.o and users@m\.a\.o mailing lists\. Explain to people what they should do if they would like to continue development of the plugin\. + diff --git a/content/markdown/developers/website/deploy-component-reference-documentation.md b/content/markdown/developers/website/deploy-component-reference-documentation.md new file mode 100644 index 0000000000..c2e9ba11fe --- /dev/null +++ b/content/markdown/developers/website/deploy-component-reference-documentation.md @@ -0,0 +1,129 @@ +--- +title: Deploy Maven Component Reference Documentation +author: + - Barrie Treloar + - Hervé Boutemy +date: 2015-03-30 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +This document gives step\-by\-step instructions for deploying Maven components reference documentation inside the Maven [https://maven\.apache\.org/](/) website\. + +See [Maven website introduction](\./index\.html) for instructions on the whole website publication \(main site content \+ components\)\. + +# Overview + +Since December 2012, the overall website uses svnpubsub mechanism: + +![Components reference documentation mechanisms overview](component\-reference\-documentation\.png) +# How components reference documentation publication works + +Components don't use CMS: components reference documentation are versioned and generated from full sources, with both handwritten content \(like Maven main site\) and content generated from sources \(javadoc, unit\-test results, integration test results\.\.\.\)\. + +## Staging component reference documentation + +Reference documentation of a component is staged in `https://maven.apache.org/xxx-archives/yyy-LATEST/`, where `yyy` is the component name and `xxx` can be: + +- the component type, like `shared`, `plugins`, `skins`, \.\.\. \(see [/shared\-archives/](/shared\-archives/), [/plugins\-archives/](/plugins\-archives/), [/pom\-archives/](/pom\-archives/), [/skins\-archives/](/skins\-archives/)\) +- the component name for standalone components, like `archetype`, `plugin-tools`, `surefire`, `wagon`, \.\.\. \(see [/archetype\-archives/](/archetype\-archives/), [/archetypes\-archives/](/archetypes\-archives/), [/plugin\-tools\-archives/](/plugin\-tools\-archives/), [/scm\-archives/](/scm\-archives/), [/surefire\-archives/](/surefire\-archives/), [/wagon\-archives/](/wagon\-archives/)\) + +To publish component reference documentation: + +1. prerequisite: eventually build the component if it has not been done previously, or some reports may miss build or integration information: + + Notice: In cases where you have prepared a release you can simple change into `target/checkout` directory and continue with 2\. + + ``` + mvn -Prun-its install + ``` + +1. build the reference documentation: + + ``` + mvn -Preporting site site:stage + ``` + + Notice: `site:stage` is really necessary only for multi\-modules components, but added unconditionally in these instructions to keep them as straightforward as possible\. + +1. stage the reference documentation to website production svn area, using [maven\-scm\-publish\-plugin](/plugins/maven\-scm\-publish\-plugin): \(TODO: explanations on configuration in pom to yyy\-LATEST\) + + ``` + mvn scm-publish:publish-scm + ``` + + svnpubsub mechanism transfers svn production content to live production site + +**Notice**: content is in fact published to [/components/](/components/) directory, and symbolic links declared in `resources/**/components.links` in main site source are used by Ant to create a reference from `/xxx` \(= what we want to be user\-visible\) to `/components/xxx` \(what what is checked out\)\. + +## Publishing versioned component reference documentation + +When doing a release, `yyy-LATEST` content staged in previous section needs: + +1. to be archived to versioned directory before a newer revision is published into \-LATEST, +1. to replace the actual component reference documentation\. + +This is done with operations on website production svn area: you can use [Component Reference Documentation Helper](\./component\-reference\-documentation\-helper\.html) to easily prepare svnmucc command line\. + +If you prefer to do everything by hand from command templates, you can do either with `svn` command: + +- Unix: + + ``` + SVNPUBSUB=https://svn.apache.org/repos/asf/maven/website/components + + svn cp $SVNPUBSUB/xxx-archives/yyy-LATEST $SVNPUBSUB/xxx-archives/yyy-$version -m "Archive versioned site." + + svn rm $SVNPUBSUB/xxx/yyy -m "Remove old site." + svn cp $SVNPUBSUB/xxx-archives/yyy-$version $SVNPUBSUB/xxx/yyy -m "Publish new site." + ``` + +- Windows: + + ``` + set SVNPUBSUB=https://svn.apache.org/repos/asf/maven/website/components + + svn cp %SVNPUBSUB%/xxx-archives/yyy-LATEST %SVNPUBSUB%/xxx-archives/yyy-$version -m "Archive versioned site." + + svn rm %SVNPUBSUB%/xxx/yyy -m "Remove old site." + svn cp %SVNPUBSUB%/xxx-archives/yyy-$version %SVNPUBSUB%/xxx/yyy -m "Publish new site." + ``` + +or with [`svnmucc` command](http://svnbook\.red\-bean\.com/en/1\.8/svn\.ref\.svnmucc\.re\.html): + +``` +svnmucc -m "Publish yyy $version documentation" \ + -U https://svn.apache.org/repos/asf/maven/website/components \ + cp HEAD xxx-archives/yyy-LATEST xxx-archives/yyy-$version \ + rm xxx/yyy \ + cp HEAD xxx-archives/yyy-LATEST xxx/yyy +``` + +## Updating index page in the Maven site + +Some component types have an index page refering to each components of the same type\. This is the case for plugins \(see [index](/plugins/)\), shared \(see [index](/shared/)\), poms \(see [index](/pom/)\) and skins \(see [index](/skins/)\)\. + +Update the version number and release date for the component in the `content/apt/xxx/index.apt` page\. + +See [Deploy Maven website](\.\./website/deploy\-maven\-website\.html) for more in\-depth instructions on main site content editing\. + +**Notice**: if you forget about updating the index page, dist\-tool has a [report run daily](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/) that will gently send a failure notification on notifications@maven\.a\.o when "Check Errors" report is not empty\. + diff --git a/content/markdown/developers/website/deploy-maven-website.md b/content/markdown/developers/website/deploy-maven-website.md new file mode 100644 index 0000000000..c88bec0e88 --- /dev/null +++ b/content/markdown/developers/website/deploy-maven-website.md @@ -0,0 +1,77 @@ +--- +title: Deploy Maven Main Website +author: + - Barrie Treloar + - Hervé Boutemy +date: 2015-03-30 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +This document gives step\-by\-step instructions for deploying the main Maven [https://maven\.apache\.org](/) website\. + +**Obsolete** this documentation is obsolete: with the migration of site source to Git, Apache CMS is not used any more\. It is replaced by Git edit \(eventually through GitHub with the "edit" link accessible from breadcrumb\) followed by Jenkins job to build and commit to svnpubsub\. + +See [Maven website introduction](\./index\.html) for instructions on the whole website publication\. + +# Overview + +Since December 2012, the overall website uses svnpubsub mechanism and the main website uses Apache CMS: + +![Main website mechanisms overview](main\-website\.png) +# How main website publication works + +Maven main website \([https://maven\.apache\.org](https://maven\.apache\.org)\) is generated with [maven\-site\-plugin](/plugins/maven\-site\-plugin) from a source tree stored in svn: [https://svn\.apache\.org/repos/asf/maven/site/trunk](https://svn\.apache\.org/repos/asf/maven/site/trunk)\. + +## Edit source content + +You can edit source content in 2 ways: + +1. use [the CMS UI](https://cms\.apache\.org/maven/) through your web browser: + - Go to [https://cms\.apache\.org/maven/](https://cms\.apache\.org/maven/)\. + - Click link "Get Maven Working Copy"\. + - Navigate to the content you want to modify\. + - Once you have modified the content, commit with the button "Submit"\. +1. checkout the source content locally, modify it with your favorite text editor, eventually test the result \(`mvn site`\), then check\-in source modifications\. + +After source tree is modified in svn, [a Buildbot job](http://ci\.apache\.org/builders/maven\-site\-staging) is triggered: + +1. it builds the HTML site using [maven\-site\-plugin](/plugins/maven\-site\-plugin): `mvn site`, +1. it publishes generated HTML content to [CMS staging svn area](https://svn\.apache\.org/repos/infra/websites/staging/maven/trunk/content/), +1. svnpubsub mecanism transfers svn CMS staging content to live CMS staging site: [http://maven\.staging\.apache\.org](http://maven\.staging\.apache\.org), +## Publish site content + +If everything is good, **publish modifications** using [CMS publish](https://cms\.apache\.org/maven/publish) action\. + +Under the hood: + +1. CMS copies CMS staging svn area content to [website production svn area](https://svn\.apache\.org/repos/infra/websites/production/maven/content/), +1. svnpubsub mecanism transfers svn production content to live production site: [http://maven\.apache\.org](http://maven\.apache\.org)\. +# How Doxia website publication works + +Doxia uses the exact same mecanisms: + +- you can edit [svn source tree](https://svn\.apache\.org/repos/asf/maven/doxia/site/trunk) either locally or through [CMS UI](https://cms\.apache\.org/maven\-doxia/), +- [a Buildbot job](http://ci\.apache\.org/builders/maven\-doxia\-site\-staging) builds the site and updates [website staging svn area](https://svn\.apache\.org/repos/infra/websites/staging/maven\-doxia/trunk/content/), +- svnpubsub published to [live staging site](http://maven\-doxia\.staging\.apache\.org), +- if everything is good, **publish modifications** using [CMS publish](https://cms\.apache\.org/maven\-doxia/publish) action, +- CMS copies CMS staging svn area content to [website production svn area](https://svn\.apache\.org/repos/infra/websites/production/maven\-doxia/content/), +- svnpubsub mecanism transfers svn production content to live production site: [http://maven\.apache\.org/doxia](http://maven\.apache\.org/doxia), with its [`extpaths.txt`](/doxia/extpaths\.txt) diff --git a/content/markdown/developers/website/index.md b/content/markdown/developers/website/index.md new file mode 100644 index 0000000000..2b3799098d --- /dev/null +++ b/content/markdown/developers/website/index.md @@ -0,0 +1,54 @@ +--- +title: Deploy Maven Website +author: + - Barrie Treloar + - Hervé Boutemy +date: 2013-09-23 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +The Maven [https://maven\.apache\.org](https://maven\.apache\.org) website is composed from: + +- a main content, +- multiple components reference documentation, published for each component release\. + +And [Doxia](https://maven\.apache\.org/doxia/) website has the same dual structure\. + +These contents are stored in svn, and svnpubsub/svnwcsub maintains a working copy on the webservers in `/www/maven.apache.org/content` \(see [`svnwcsub` configured in infra Puppet](https://github\.com/apache/infrastructure\-puppet/blob/deployment/modules/svnwcsub/files/svnwcsub\.conf\#L123)\): + +- `/` comes from [https://svn\.apache\.org/repos/asf/maven/website/content/](https://svn\.apache\.org/viewvc/maven/website/content/) +- [`/components`](https://maven\.apache\.org/components) comes from [https://svn\.apache\.org/repos/asf/maven/website/components/](https://svn\.apache\.org/repos/asf/maven/website/components/) +- `/doxia` comes from [https://svn\.apache\.org/repos/asf/maven/doxia/website/content/](https://svn\.apache\.org/viewvc/maven/doxia/website/content/) +- [`/doxia/components`](https://maven\.apache\.org/doxia/components) comes from [https://svn\.apache\.org/repos/asf/maven/doxia/website/components/](https://svn\.apache\.org/repos/asf/maven/doxia/website/components/) + +and the link between main content and components reference documentation \(for example from `/plugins/maven-xxx-plugin` to internal `/components/plugins/maven-xxx-plugin`\) is done with symbolic links\. These links are configured in `components.links` files in `content/resources/` and subdirectories, for example [plugins/components\.links](https://github\.com/apache/maven\-site/blob/master/content/resources/plugins/components\.links)\. + +# How website publication works + +Instructions on how to publish website content are split in separate documents: + +- on every main content source commit \([maven\-site\.git](https://github\.com/apache/maven\-site) and [maven\-doxia\-site\.git](https://github\.com/apache/maven\-doxia\-site)\), main content rebuild and publish is triggered through Jenkins jobs \( [maven\-site job](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-site/) and [doxia\-site job](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-doxia\-site/)\), which basically run `mvn site-deploy` \(it can be run locally if CI is off\.\.\.\), +- on every Maven component release, release manager follows "[deploying Maven components reference documentation](\./deploy\-component\-reference\-documentation\.html)", eventually using [Component Reference Documentation Helper](\./component\-reference\-documentation\-helper\.html) to easily prepare `svnmucc` command line\. +# Analytics + +As part of Privacy enhancements, the whole Maven site is moving to [Apache's Analytics infrastructure](https://privacy\.apache\.org/matomo/): see [Maven statistics](https://analytics\.apache\.org/index\.php?module=CoreHome&action=index&date=yesterday&period=day&idSite=3)\. + diff --git a/content/markdown/developers/website/website-overview.md b/content/markdown/developers/website/website-overview.md new file mode 100644 index 0000000000..b6404428a7 --- /dev/null +++ b/content/markdown/developers/website/website-overview.md @@ -0,0 +1,36 @@ +--- +title: Deploy Maven Website +author: + - Barrie Treloar + - Hervé Boutemy +date: 2013-09-23 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +The Maven [https://maven\.apache\.org](/) website is composed from: + +- a main content +- multiple components reference documentation +![Website mechanisms overview](website\-overview\.png) + +See [Maven website introduction](\./index\.html) for instructions on website publication\. + diff --git a/content/markdown/developers/welcome-to-new-committers.md b/content/markdown/developers/welcome-to-new-committers.md new file mode 100644 index 0000000000..f8b8d08e20 --- /dev/null +++ b/content/markdown/developers/welcome-to-new-committers.md @@ -0,0 +1,51 @@ +--- +title: Guide for new Maven committers +author: + - The Maven Team +date: 2006-04-03 +--- + + + + + + + + + + + + + + + + + + + +# Guide for new Maven committers + +First of all congratulations, thank you, and welcome to the fold\! If you are reading this you've recently been voted in as committer on an Apache Maven project and there are a few things that need to be sorted out before you can participate fully\. + +The first thing to get out of the way is sending in your contributor's license agreement \(CLA\)\. You can't participate at Apache until we have received your signed CLA, so go to the [Apache website](http://www\.apache\.org/licenses/\#clas), print out the CLA, sign it, and send it in ASAP\. + +Once you've dealt with your CLA, there are a some documents that pertain to Apache as a whole you should read: + +- [How the ASF works](http://www\.apache\.org/foundation/how\-it\-works\.html) +- [Guide for new committers](http://www\.apache\.org/dev/new\-committers\-guide\.html) +- [The committers FAQ](http://www\.apache\.org/dev/committers\.html) +- [How voting works](http://www\.apache\.org/foundation/voting\.html) + +Here are the documents that pertain to Maven specifically: + +- [Guide to Maven development](/guides/development/guide\-maven\-development\.html) +- [Setup your committer environment](/developers/committer\-environment\.html) + +And here are the specifics on setting up your Git access: + +- [Apache's Source Code Repository](http://www\.apache\.org/dev/version\-control\.html) + +If you have any questions just ask\! We're here to help, and looking forward to working with you\! + +The Maven Team\! + diff --git a/content/markdown/examples/index.md b/content/markdown/examples/index.md new file mode 100644 index 0000000000..d3d5a75301 --- /dev/null +++ b/content/markdown/examples/index.md @@ -0,0 +1,29 @@ +--- +title: Summary of Maven Examples +author: + - John Casey +date: 2009-08-02 +--- + + + + + + + + + + + + + + + + + + + +# Examples + +- [Injecting POM Properties via settings\.xml](\./injecting\-properties\-via\-settings\.html) +- [Maven 3 lifecycle extensions](\./maven\-3\-lifecycle\-extensions\.html) diff --git a/content/markdown/examples/injecting-properties-via-settings.md b/content/markdown/examples/injecting-properties-via-settings.md new file mode 100644 index 0000000000..2551e88b4c --- /dev/null +++ b/content/markdown/examples/injecting-properties-via-settings.md @@ -0,0 +1,74 @@ +--- +title: Example: Injecting POM Properties via Settings.xml +author: + - John Casey +date: 2006-04-20 +--- + + + + + + + + + + + + + + + + + + + +# Example: Injecting POM Properties via Settings\.xml + +## Impetus + +You have a plugin parameter that should contain a user\-specific value\. This parameter has a common format \(relative directory structure\), but depends on knowing the directory of the installed application or something\. + +## Plugin Configuration + +``` + + [...] + + + + org.myproject.plugins + my-cool-maven-plugin + 1.0 + + ${application-home}/deploy + + + + +``` + +## `settings.xml` + +``` + + [...] + + + inject-application-home + + /path/to/application + + + + + + inject-application-home + + +``` + +## Explanation + +When Maven loads the project's POM, it will pickup the activated profiles from the `activeProfiles` section of the `settings.xml` file, and inject the properties declared within the profile\. When the POM is interpolated, the `application-home` property will already have been injected, so will allow the plugin's parameter value to be resolved\. + diff --git a/content/markdown/guides/development/guide-building-maven.md b/content/markdown/guides/development/guide-building-maven.md new file mode 100644 index 0000000000..5f27d6ab76 --- /dev/null +++ b/content/markdown/guides/development/guide-building-maven.md @@ -0,0 +1,84 @@ +--- +title: Guide to Building Maven +author: + - Brett Porter + - Jason van Zyl +date: 2015-01-04 +--- + + + + + + + + + + + + + + + + + + + +# Building Maven + +## Why would I want to build Maven? + +Building Maven \(or a plugin, or any component\) yourself is for one of two reasons: + +- to try out a bleeding edge feature or bugfix \(issues can be found in [ JIRA](/issue\-management\.html)\), +- to fix a problem you are having and submit a patch to the developers team\. +## Checking out the sources + +All of the source code for Maven and its related libraries is in managed in the ASF source code repositories: for details, see [https://maven\.apache\.org/scm\.html](/scm\.html)\. + +## Building Maven + +### Building a Maven Plugin or Component + +Building a Maven plugin or component is like any Maven build: + +``` +mvn install +``` + +#### Running Integration Tests + +Before submitting a patch, it is advised to run the integration tests, which are available in the `run-its` profile: + +``` +mvn -Prun-its install +``` + +### Building Maven core + +Until Maven 3\.3, Maven core build could be boostrapped with an Ant build\. This bootstrap has been removed in Maven 3\.5: you need a pre\-built Maven to build Maven from source\. + +To do this, run from the source directory: + +``` +mvn install +``` + +The assemblies will be created in `apache-maven`, and can be manually unzipped to the location where you'd like the resulting Maven installed\. + +If you want to have the resulting Maven directly copied to a directory, you can use the `distributionTargetDir` property: + +``` +mvn -DdistributionTargetDir="$HOME/app/maven/apache-maven-SNAPSHOT" install +``` + +#### Running the full Maven core integration tests + +Before checking in a change or submitting a patch to Maven core, it is required to run the core integration tests\. Using your local build of Maven, run: + +``` +mvn test -Prun-its +``` + +Consult [Core ITs documentation](/core\-its/) for more options\. + diff --git a/content/markdown/guides/development/guide-committer-school.md b/content/markdown/guides/development/guide-committer-school.md new file mode 100644 index 0000000000..7f48c2fe37 --- /dev/null +++ b/content/markdown/guides/development/guide-committer-school.md @@ -0,0 +1,80 @@ +--- +title: Do you want to become a Maven Committer? +author: + - Stephen Connolly + - Robert Scholte +date: 2012-07-11 +2017-07-21 +--- + + + + + + + + + + + + + + + + + + + + +# Do you want to become a Maven Committer? + +The Apache Software Foundation is a meritocracy\. By this we mean that you gain status based on the merit of your work and actions\. In fact the status that you gain is a recognition of the merit of your work and actions\. + +Maven is an Apache project, that means that we have to follow the Apache rules and way\. One of those rules is that we cannot hand out commit access to anyone who asks for it\. + +To gain commit access you must establish your merit by submitting patches that get picked up by existing committers\. + +After you have contributed enough patches to establish merit, the project management committee decides whether you can be trusted with commit access\. + +_The reality is that "It is what it is"TL;DR To become a Maven committer write good patches and get them applied\._ + +# What makes a good patch? + +A good patch is a patch that applies cleanly and includes tests that cover both the positive and negative case and has documentation where relevant\. + +For example, if you were implementing a patch to fix [MNG\-4612](http://issues\.apache\.org/jira/browse/MNG\-4612) you would first need to write a test case that is failing when trying to encrypt + +``` +{DESede}y+qq...== +``` + +and a second test case that is passing when trying to encrypt + +``` +password +``` + +This is in order to be sure that you have written an effective test case that can pass for good data\. Then you implement the fix and all the tests should pass\. You then take a Subversion compatible† diff of the source code and attach that to the issue in question\. + +To understand how your patch gets evaluated, here is how I apply patches: + +1. I look at the actual diff, if there is a whole lot of formatting changes irrelevant to the issue being fixed => **Patch is no good, ask on JIRA for a clean patch** +1. I look at the list of files in the diff, if there are no tests => **Patch is no good, ask on JIRA for test cases** +1. I look at the issue and if the issue requires documentation be updated and there is no documentation changes in the patch => **Patch is no good, ask on JIRA for documentation changes in the patch** +1. I take a clean checkout of the source that the patch applies to and try to apply the patch\.\.\. if it does not apply clean => **Patch is no good, ask on JIRA for an updated patch** +1. I revert the src/main and run the tests\. If the tests all pass, then there are no test cases to catch the bug => **Patch is no good, ask on JIRA for proper tests** +1. I revert src and run the tests\. If any tests fail, then there is something wrong with the existing code => **If I have time I might try and fix the issue, otherwise I just move on** +1. I apply the patch a second time and run the tests\. If the tests all pass => **Patch is good, I commit the patch and mark the JIRA as resolved** + +So there you have it, my guide to writing good patches\.\.\. now the next step is getting your patches noticed\.\.\. + +# How to get your patches noticed + +The simplest way to get your patches noticed is to submit them to the JIRA issue that they fix\. + +Remember that the Maven project is run by volunteers in their spare time, so very often we may not notice your patch for a few days\. + +If you are certain that your patch is a good patch, and a week has passed with no comments on JIRA, then you should send _one and only one_ email to the [dev@maven\.apache\.org](mailto:dev@maven\.apache\.org) mailing list to see if your patch can get noticed\. + +**Note:** you need to be fairly confident that your patch is a good patch, because if you keep on pestering the Maven developers looking to have non\-good patches applied, your merit will become negative and people will be less inclined to help you get your patches applied\.\.\. also this is why you should send one and _only one_ email about your patch on any specific JIRA issue\. + diff --git a/content/markdown/guides/development/guide-documentation-style.md b/content/markdown/guides/development/guide-documentation-style.md new file mode 100644 index 0000000000..8394ee6c50 --- /dev/null +++ b/content/markdown/guides/development/guide-documentation-style.md @@ -0,0 +1,105 @@ +--- +title: Guide To Maven Documentation Style +author: + - Dennis Lundberg +date: 2008-07-12 +--- + + + + + + + + + + + + + + + + + + + +# Guide To Maven Documentation Style + +## Where did the style came from? + +The documentation style guide was created to make our documentation more consistent and also to apply best practices to the documentation as well\. The standard has just been started and will expand over time based on the suggestions made on the Maven dev mailing list\. It is a community consensus of how we should write our documentation\. + +Each rule in this guide should come with a motivation as to why it exists\. References to external sources are encouraged\. + +## Date format + +How people format a date varies around the world, sometimes making it hard for people to understand each other\. The solution to this problem comes in the form of the ISO\-8601 standard\. + +A date in our documentation must follow this standard: + +**YYYY\-MM\-DD** + +where **YYYY** is the year in the Gregorian calendar, **MM** is the month of the year between 01 \(January\) and 12 \(December\), and **DD** is the day of the month between 01 and 31\. + +**Note**: All documentation meta\-data should respect this convention, for instance for this given APT document: + +``` + ------ + Guide To Maven Documentation Style + ------ + Dennis Lundberg + ------ + 2008-07-03 + ------ +``` + +### References + +- [W3C Quality Web Tips](http://www\.w3\.org/QA/Tips/iso\-date) +- [ISO\-8601](http://www\.iso\.org/iso/iso\_catalogue/catalogue\_tc/catalogue\_detail\.htm?csnumber=26780) +- [Wikipedia](http://en\.wikipedia\.org/wiki/ISO\_8601) + +## POM Snippet + +A POM file must use 2 spaces for each indentation\. Because POM snippets are often used in documentation to show the user how to configure something, it is important that these snippets aren't too wide\. If they are too wide, the page is difficult to read on a smaller screen\. + +When you use a snippet of XML from the POM as an example in documentation, make sure that the example is properly indented\. A user should be able to copy and paste the example into their own POM without changing the indentation\. + +Also, you should declare all parent POM elements to improve the comprehension\. You could use ellipsis \(i\.e\. \.\.\.\) if you don't want to specify elements\. + +### Example + +The following is an example of how the distribution management of the Maven site is configured\. + +``` + + ... + + + apache.website + scp://people.apache.org/www/maven.apache.org/ + + + ... + +``` + +As you can see above the `` element is indented once \(=2 spaces\), the `` element is indented twice \(=4 spaces\), and the `` is indented three times \(=6 spaces\)\. + +## Naming Documentation Files + +All file names should replace space by a hyphen \(\-\), for instance for this given APT document: + +``` + guide-documentation-style.apt +``` + +## Updating Documentation Files + +A good practice is to update the date \(with the correct date format\) when you are updating documentation files\. + +## Write Thinking + +Here are some pointers about English rules when typing material: + +- [Wikipedia:Manual of Style](https://en\.wikipedia\.org/wiki/Wikipedia:Manual\_of\_Style), specifically [Punctuation Part](https://en\.wikipedia\.org/wiki/Wikipedia:Manual\_of\_Style\#Punctuation) diff --git a/content/markdown/guides/development/guide-helping.md b/content/markdown/guides/development/guide-helping.md new file mode 100644 index 0000000000..f1176dd744 --- /dev/null +++ b/content/markdown/guides/development/guide-helping.md @@ -0,0 +1,70 @@ +--- +title: Guide to helping with Maven +author: + - Brett Porter + - Jason van Zyl +date: 2008-07-03 +2015-06-16 +--- + + + + + + + + + + + + + + + + + + + +# Guide to helping with Maven + +As with any open source project, there are several ways you can help: + +- Join the [mailing lists](\.\./\.\./mailing\-lists\.html) and answer other user's questions\. +- Report bugs, feature requests and other issues in the [issue management system](\.\./\.\./issue\-management\.html)\. +- [ Build Maven](\./guide\-building\-maven\.html) for yourself, in order to fix bugs\. +- [Submit patches](\./guide\-maven\-development\.html\#Creating\_and\_submitting\_a\_patch) to reported issues \(both those you find, or that others have filed\) + To ease your first contribution, we have a [list of "up for grabs" issues](https://s\.apache\.org/for\-the\-grabs\_maven), meaning that they should be easy to work on\. If you consider picking up larger chunks of work, please reach out on the [dev@maven\.apache\.org list](\.\./\.\./mailing\-lists\.html) to discuss if the idea and solution strategy are still relevant\. +- [ Test releases](\./guide\-testing\-releases\.html) help test releases that are being voted on \(see the [dev@maven\.apache\.org list](\.\./\.\./mailing\-lists\.html) for release votes\) +- [ Test snapshot plugins](\./guide\-testing\-development\-plugins\.html) help test the latest development versions of plugins and report issues +- Help with the documentation by pointing out areas that are lacking or unclear, and if you can, submitting Pull Requests to correct it: use the "edit" button in the breadcrumb, just after the page title\. You can also create appropriate issues [by using the issue management system](https://issues\.apache\.org/jira/browse/MNGSITE)\. + +Your participation in the community is much appreciated\! + +# Why Would I Want to Help? + +There are several reasons these are good things\. + +- By answering other people's questions, you can learn more for yourself +- By submitting your own fixes, they get incorporated faster +- By reporting issues, you ensure that bugs don't get missed, or forgotten +- You are giving back to a community that has given you software for free +# How do I Join the Project? + +Projects at Apache operate under a meritocracy, meaning those that the developers notice participating to a high extent will be invited to join the project as a committer\. + +This is as much based on personality and ability to work with other developers and the community as it is with proven technical ability\. Being unhelpful to other users, or obviously looking to become a committer for bragging rights and nothing else is frowned upon, as is asking to be made a committer without having contributed sufficiently to be invited\. + +# Developers Conventions + +There are a number of conventions used in the project, which contributors and developers alike should follow for consistency's sake\. + +- [Maven Code Style And Convention](\.\./\.\./developers/conventions/code\.html) +- [Maven Jira Convention](\.\./\.\./developers/conventions/jira\.html) +- [Maven Git Convention](\.\./\.\./developers/conventions/git\.html) +- [Releasing a Maven project](\.\./\.\./developers/release/index\.html) +- [Apache Maven Wiki](https://cwiki\.apache\.org/confluence/display/MAVEN/Index) +# Resources for committers + +- [ Developer Resources](http://www\.apache\.org/dev/) +- [ About the Apache Software Foundation](http://www\.apache\.org/foundation/) +- [ Committer FAQ](http://www\.apache\.org/dev/committers\.html) diff --git a/content/markdown/guides/development/guide-maven-development.md b/content/markdown/guides/development/guide-maven-development.md new file mode 100644 index 0000000000..6931b712c8 --- /dev/null +++ b/content/markdown/guides/development/guide-maven-development.md @@ -0,0 +1,131 @@ +--- +title: Guide to Developing Maven +author: + - Emmanuel Venisse + - Trygve Laugstol + - Brett Porter + - Maarten Mulders +date: 2019-06-04 +--- + + + + + + + + + + + + + + + + + + + +# Developing Maven + +This document describes how to get started developing Maven itself\. There is a separate page describing how to [build Maven](\./guide\-building\-maven\.html)\. + +## Finding some work to do + +First of all you need something to work on\! Issues can be found in [several JIRA projects](/issue\-management\.html)\. + +Another good place to look for work is the [ Up for grabs](https://s\.apache\.org/up\-for\-grabs\_maven) list\. This list contains relatively simple issues that can be worked on without a lot of prerequisite knowledge\. + +When you find a issue you would like to work on, add a comment in the issue log so the core developers and other people looking for work know that someone is already working on it\. + +## Where's the source? + +See [https://maven\.apache\.org/scm\.html](/scm\.html) for information\. The Maven project uses the Apache GitBox Repositories, and all of them are dual\-mirrored to [ GitHub](https://github\.com/apache/)\. + +## Don't forget tests\! + + + +You will find many unit tests\. If at all possible, create or modify a unit test to demonstrate the problem, and then validate your fix\. + +If you need to mock a class to write a test, use the Mockito framework\. Parts of the Maven codebase predate Mockito so you will encounter existing tests that use EasyMock, PowerMock, and JMock\. However, all newly written mocks should use Mockito, even if this means a module or a single class uses multiple mocking frameworks\. If an existing test class has complicated legacy mock setup, you can add new Mockito based tests in a new test class\. There is no requirement that all tests for a single model class must be in the same test class\. It is OK to have multiple test classes per model class\. + +If the problem case can't be set up in the unit tests, add an integration test\. Before submitting a patch, in any case, you should run all of the integration tests\. The tests require an empty local repository\. See [Core IT Suite documentation](/core\-its/core\-it\-suite/) for more details\. + +## Creating and submitting a patch + +The most convenient way is to create a GitHub fork from the Git repository you are working with\. When you have either completed an issue or just want some feedback on the work you have done, create a pull request\. We have a couple of guidelines when submitting contributions: + +- Verify the status of the `master` branch on [Maven CI](https://ci\-maven\.apache\.org/job/Maven/job/maven\-box/job/maven\-dist\-tool/job/master/site/dist\-tool\-master\-jobs\.html)\. If it is not SUCCESS, then first try to figure out the problem\. Don't start with your own issue yet\! You can use `git bisect` to figure out the problematic commit and help with that committer to solve the problem\. +- Create your branch from `master`, not from a tag\. Otherwise, your patch is outdated the moment you create it and might not be applicable to the development head\. +- If this was a new piece of work without a JIRA issue, create a JIRA issue for it now\. +- Name the branch after the issue number; the branch name would start with `-`\. +- Push your branch with the commit\(s\) to your fork\. +- Create a [ pull request](https://help\.github\.com/en/articles/about\-pull\-requests) to submit your contribution\. Shortly after, someone will review the pull request and give you feedback on it\. + +A short note: + +- Make sure that you follow our code style, see [Further Links](Further\_Links)\. +## Pull request acceptance criteria + +There are a number of criteria that a pull request will be judged on: + +- Whether it works and does what is intended\. This one is probably obvious\! +- Whether it fits the spirit of the project\. Some pull requests may be rejected as they take the project in a different direction than the current development community has chosen\. This is usually discussed on an issue well before a pull request is contributed, so if you are unsure, discuss it there or on the mailing lists first\. Feel free to continue discussing it \(with new justification\) if you disagree, or appeal to a wider audience on the mailing lists\. +- Whether it contains tests\. It is expected that any pull request relating to functionality will be accompanied by unit tests and/or integration tests\. It is strongly desired \(and will be requested\) for bug fixes too, but will not be the basis for not applying it\. At a bare minimum, the change should not decrease the amount of automated test coverage\. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing\. +- Whether it contains documentation\. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later\. While rough is acceptable, incomplete is not\. As with automated testing, as a community we are striving to increase the current coverage of documentation\. + +Above all, don't be discouraged\. These are the same requirements the current committers should hold each other to as well\. And remember, your contributions are always welcome\! + +## Related Projects + +Maven has a few dependencies on other projects: + +- **Plexus** + + Plexus is a full\-fledged container supporting different kinds of component lifecycles\. Its native lifecycle is like any other modern IoC container, using field injection of both requirements and configuration\. All core Maven functionality are Plexus components\. + + You can [read more about Plexus](https://codehaus\-plexus\.github\.io/)\. + +- **Modello** + + Modello is a simple tool for representing an object model and generating code and resources from the model\. Maven uses Modello to generate all Java objects, XML readers and writers, XML Schema, and HTML documentation\. + + You can [read more about Modello](https://codehaus\-plexus\.github\.io/modello/)\. + +- **Mojo** + + "Mojo" is really two things when it comes to Maven: it is both [Maven's plug\-in API](/ref/current/maven\-plugin\-api/) and also [a separate Mojohaus project](http://www\.mojohaus\.org) hosting a lot of plugins\. + + [The MojoHaus Project](http://www\.mojohaus\.org) is a plugin forge for non\-core Maven plugins\. There is also a lower bar for becoming a part of the project\. + +## Sub Projects + +- **Maven Surefire** + + Surefire is a testing framework\. It can run regular JUnit tests so you won't have to change anything in your code to use it\. It supports scripting tests in BeanShell and Jython and has special "batteries" for writing acceptance and functional tests for the web and for testing XML\-RPC code\. + + You can [read more about Surefire](/surefire/)\. + +- **Maven Doxia** + + Doxia is Maven's documentation engine\. It has a sink and parser API that can be used to plug in support for input and output documents\. + + You can read more about [Doxia](/doxia/) and the currently supported [document formats](/doxia/references/index\.html)\. + +- **Maven SCM** + + Maven SCM \(Source Control Management\) is a reusable API which is independent of Maven itself\. It is used by the SCM related Maven Plugins\. The core part of Maven doesn't depend on Maven SCM\. + + You can [read more about Scm](/scm/)\. + +- **Maven Wagon** + + Maven Wagon is a standalone API that dealt with transporting files and directories in Maven 2\.x\. Maven Core today uses the Resolver Transport API, that among other implementations, contains a wrapper for Wagon as well\. Also, the site plug\-in uses it to publish the site\. + + You can [read more about Wagon](/wagon/)\. + +## Further Links + +- [Maven Code Style And Code Convention](\.\./\.\./developers/conventions/code\.html) +- [Maven JIRA Convention](\.\./\.\./developers/conventions/jira\.html) diff --git a/content/markdown/guides/development/guide-testing-development-plugins.md b/content/markdown/guides/development/guide-testing-development-plugins.md new file mode 100644 index 0000000000..062f7cedab --- /dev/null +++ b/content/markdown/guides/development/guide-testing-development-plugins.md @@ -0,0 +1,126 @@ +--- +title: Guide to Testing Development Versions of Plugins +author: + - Brett Porter +date: 2009-08-02 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Testing Development Versions of Plugins + +## Why would I want to do this? + +If a bug you are encountering has been reported as fixed but not yet released, you can confirm that it has been fixed for you\. Or perhaps you just like to live on the bleeding edge\. + +You are highly encouraged to join the development list for the project and provide your feedback, or help promote release of the plugin in question\. + +_Note:_ This is **not** recommended as an everyday or in production practice\! Snapshots are for testing purposes only and are not official releases\. For more information, see [ the Releases FAQ](http://www\.apache\.org/dev/release\.html\#what)\. + +## How do I do this? + +Development versions of Maven plugins are periodically published to the repository: [https://repository\.apache\.org/snapshots/](https://repository\.apache\.org/snapshots/)\. + +_Note:_ Currently, this is not done automatically by our continuous integration setup\. This is coming soon\. + +Other sites may publish there own \- for example, the MojoHaus project hosts theirs at [https://oss\.sonatype\.org/content/repositories/snapshots/](https://oss\.sonatype\.org/content/repositories/snapshots/) + +The first step is to include this in your project: + +``` + + ... + + + apache.snapshots + https://repository.apache.org/snapshots/ + + + ... + +``` + +After this is included, there are three ways to use the updated versions: + +- Set the appropriate version in the plugin, eg `2.0.1-SNAPSHOT` +- If you have not specified a version, use the `-U` switch to update plugins for the given Maven run +- You can have Maven automatically check for updates on a given interval, for example: + + ``` + + ... + + + apache.snapshots + https://repository.apache.org/snapshots/ + + + ... + + ``` + +_Note:_ These last two techniques mean that _every_ plugin will be updated to the latest snapshot version\. + +The development version will stop being used if the `` element is removed from your POM and the version is set back to the release version\. If you are using the command line or an unspecified version, you will also need to remove the version from the local repository\. + +## Using Settings without Modifying the Project + +If you are using the goals from the command line on a number of projects, you should include this in your `settings.xml` file instead\. + +You need to modify your `${user.home}/.m2/settings.xml` file to include two new profiles and then when you need access to the plugin snapshots use `-Papache`\. The profile only needs to be enabled once so that the plugins can be downloaded into you local repository\. Once in your local repository Maven can successfully resolve the dependencies and the profile no longer needs to be activated\. + +``` + + ... + + + apache + + + apache.snapshots + Maven Plugin Snapshots + https://repository.apache.org/snapshots/ + + false + + + true + + + + + + ... + +``` + +When invoking Maven for Apache profile, do it like this: + +``` +mvn -Papache +``` + +## Using a Repository Manager + +In addition to the above you may want to use a repository manager so that you can retain the builds you have been using\. For information on this technique, see the [ Guide to Testing Staged Releases](\./guide\-testing\-releases\.html)\. + +## How do I make changes to the source and test development versions of the plugins? + +For information on this, see the [Guide to Maven Development](\./guide\-maven\-development\.html)\. + diff --git a/content/markdown/guides/development/guide-testing-releases.md b/content/markdown/guides/development/guide-testing-releases.md new file mode 100644 index 0000000000..0e11b6b7f0 --- /dev/null +++ b/content/markdown/guides/development/guide-testing-releases.md @@ -0,0 +1,131 @@ +--- +title: Guide to Testing Staged Releases +author: + - Maven Team +date: 2007-12-21 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Testing Staged Releases + +As part of the release process, the artifacts are staged in a temporary repository for testing and evaluation before voting\. Such repositories are not available by default, so to use them your project must be configured appropriately\. + +The steps are as follows: + +- add the repository or plugin repository to your POM or settings \(see below\) +- ensure you are using the version being released of the artifacts in your project, e\.g\. by setting the `` in the `` tag\. +- test the release +- remove the repository from your POM if it was specified there +- remove the artifacts from your local repository when you have completed testing + +The repository configuration for testing a plugin will typically look something like this \(it will be provided in the vote email\): + +``` + ... + + + staged-releases + https://repository.apache.org/content/groups/staging/ + + + ... +``` + +The important thing is that the staged release does not pollute your eventual environment as it may change if the vote fails and the release is made again\. This is why clearing the local repository is necessary, but if you are using a repository manager this is also important to clear\. The following provides instructions for setting Archiva up in such a way that the artifacts are isolated already\. + +# Checking Reproducible Builds + +Checking binary output, ideally to control that the build is reproducible, can be done by running `verify` \(NOT `install`\) followed by `artifact:compare` against the staged content: + +``` +mvn -Papache-release -Dgpg.skip clean verify \ + artifact:compare -Dreference.repo=https://repository.apache.org/content/groups/staging/ +``` + +## Setting up Archiva to Test Staged Releases + +These steps will be similar for any repository manager \- please refer to their individual documentation for instructions on how to configure remote proxies\. + +For Archiva, the first step is to create a new managed repository for the staged releases\. This will ensure they remain isolated from your environment\. On the repositories tab, add a new managed repository with the settings: + +- Identifier = `staged-releases` +- Name = Staged Releases +- Directory = `/path/to/repositories/staged-releases` +- Uncheck 'Scannable' + +Next add a remote repository with settings similar to the following: + +- Identifier = `dfabulich.staged.releases` +- Name = dfabulich Staged Releases +- URL = `http://people.apache.org/~dfabulich/staging-repo/` + +Finally, add a proxy connector to connect the two repositories: + +- Managed repository = `staged-releases` +- Remote repository = `dfabulich.staged` +- Release policy = `once` +- Snapshot policy = `never` +- White list = `org/apache/maven/**` + +You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of `http://localhost:8080/archiva/repository/staged-releases/`\. + +The advantage of this approach is that you can usually remove your entire local repository afterwards and after removing the staged repository from your POM the artifacts will no longer be used\. There is no need to remove the repository or artifacts from Archiva itself \- unless a staged release is updated for further testing\. + +It is also quite easy to test another staged release at a later date by reusing the repository, or adding a proxy connector and remote repository for a different staging repository\. + +If you are using the repository mirroring technique to lock down to the repository manager in your environment, you would add an additional mirror to correspond to the additional repository in the POM, such as: + +``` + ... + + staged-releases-mirror + http://localhost:8080/archiva/repository/staged-releases/ + staged-releases + + ... +``` + +## Using a Settings Profile + +If you regularly test staged releases and want to have a more convenient way to add the repository to a build without modifying your POM, you may add a profile to your `~/.m2/settings.xml`: + +``` + ... + + + staged-releases + + + staged-releases + https://repository.apache.org/content/groups/staging/ + + + + ... +``` + +With this in place, you can activate it by simply changing the plugin version to the one you are testing in the POM as above, then run the build with the following command: + +``` +mvn verify -Pstaged-releases +``` + +Note that the same conditions apply as above about cleaning out the local repository to prevent pollution of your local build environment\. + diff --git a/content/markdown/guides/getting-started/index.md b/content/markdown/guides/getting-started/index.md new file mode 100644 index 0000000000..9520541d53 --- /dev/null +++ b/content/markdown/guides/getting-started/index.md @@ -0,0 +1,1031 @@ +--- +title: Maven Getting Started Guide +author: + - Jason van Zyl + - Vincent Siveton +date: 2006-11-01 +--- + +# Maven Getting Started Guide + +This guide is intended as a reference for those working with Maven for the first time, but is also intended to serve as a cookbook with self\-contained references and solutions for common use cases\. For first time users, it is recommended that you step through the material in a sequential fashion\. For users more familiar with Maven, this guide endeavours to provide a quick solution for the need at hand\. It is assumed at this point that you have downloaded Maven and installed Maven on your local machine\. If you have not done so please refer to the [Download and Installation](\.\./\.\./download\.html) instructions\. + +Ok, so you now have Maven installed and we're ready to go\. Before we jump into our examples we'll very briefly go over what Maven is and how it can help you with your daily work and collaborative efforts with team members\. Maven will, of course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members to focus on what the stakeholders of a project require\. You can leave the build infrastructure to Maven\! + +# Sections + +- [What is Maven?](\./index\.html\#what\-is\-maven) +- [How can Maven benefit my development process?](\./index\.html\#how\-can\-maven\-benefit\-my\-development\-process) +- [How do I setup Maven?](\./index\.html\#how\-do\-i\-setup\-maven) +- [How do I make my first Maven project?](\./index\.html\#how\-do\-i\-make\-my\-first\-maven\-project) +- [How do I compile my application sources?](\./index\.html\#how\-do\-i\-compile\-my\-application\-sources) +- [How do I compile my test sources and run my unit tests?](\./index\.html\#how\-do\-i\-compile\-my\-test\-sources\-and\-run\-my\-unit\-tests) +- [How do I create a JAR and install it in my local repository?](\./index\.html\#how\-do\-i\-create\-a\-jar\-and\-install\-it\-in\-my\-local\-repository) +- [What is a SNAPSHOT version?](\./index\.html\#what\-is\-a\-snapshot\-version) +- [How do I use plugins?](\./index\.html\#how\-do\-i\-use\-plugins) +- [How do I add resources to my JAR?](\./index\.html\#how\-do\-i\-add\-resources\-to\-my\-jar) +- [How do I filter resource files?](\./index\.html\#how\-do\-i\-filter\-resource\-files) +- [How do I use external dependencies?](\./index\.html\#how\-do\-i\-use\-external\-dependencies) +- [How do I deploy my jar in my remote repository?](\./index\.html\#how\-do\-i\-deploy\-my\-jar\-in\-my\-remote\-repository) +- [How do I create documentation?](\./index\.html\#how\-do\-i\-create\-documentation) +- [How do I build other types of projects?](\./index\.html\#how\-do\-i\-build\-other\-types\-of\-projects) +- [How do I build more than one project at once?](\./index\.html\#how\-do\-i\-build\-more\-than\-one\-project\-at\-once) +## What is Maven? + +At first glance Maven can appear to be many things, but in a nutshell Maven is an attempt _to apply patterns to a project's build infrastructure in order to promote comprehension and productivity by providing a clear path in the use of best practices_\. Maven is essentially a project management and comprehension tool and as such provides a way to help with managing: + +- Builds +- Documentation +- Reporting +- Dependencies +- SCMs +- Releases +- Distribution + +If you want more background information on Maven you can check out [The Philosophy of Maven](\.\./\.\./background/philosophy\-of\-maven\.html) and [The History of Maven](\.\./\.\./background/history\-of\-maven\.html)\. Now let's move on to how you, the user, can benefit from using Maven\. + +## How can Maven benefit my development process? + +Maven can provide benefits for your build process by employing standard conventions and practices to accelerate your development cycle while at the same time helping you achieve a higher rate of success\. + +Now that we have covered a little bit of the history and purpose of Maven let's get into some real examples to get you up and running with Maven\! + +## How do I setup Maven? + +The defaults for Maven are often sufficient, but if you need to change the cache location or are behind a HTTP proxy, you will need to create configuration\. See the [ Guide to Configuring Maven](\.\./mini/guide\-configuring\-maven\.html) for more information\. + +## How do I make my first Maven project? + +We are going to jump headlong into creating your first Maven project\! To create our first Maven project we are going to use Maven's archetype mechanism\. An archetype is defined as _an original pattern or model from which all other things of the same kind are made_\. In Maven, an archetype is a template of a project which is combined with some user input to produce a working Maven project that has been tailored to the user's requirements\. We are going to show you how the archetype mechanism works now, but if you would like to know more about archetypes please refer to our [Introduction to Archetypes](\.\./introduction/introduction\-to\-archetypes\.html)\. + +On to creating your first project\! In order to create the simplest of Maven projects, execute the following from the command line: + +``` +mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false +``` + +Once you have executed this command, you will notice a few things have happened\. First, you will notice that a directory named `my-app` has been created for the new project, and this directory contains a file named `pom.xml` that should look like this: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + + my-app + + http://www.example.com + + + UTF-8 + 17 + + + + + + org.junit + junit-bom + 5.11.0 + pom + import + + + + + + + org.junit.jupiter + junit-jupiter-api + test + + + + org.junit.jupiter + junit-jupiter-params + test + + + + + + ... lots of helpful plugins + + + +``` + +`pom.xml` contains the Project Object Model \(POM\) for this project\. The POM is the basic unit of work in Maven\. This is important to remember because Maven is inherently project\-centric in that everything revolves around the notion of a project\. In short, the POM contains every important piece of information about your project and is essentially one\-stop\-shopping for finding anything related to your project\. Understanding the POM is important and new users are encouraged to refer to the [Introduction to the POM](\.\./introduction/introduction\-to\-the\-pom\.html)\. + +This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them to familiarize you with the POM essentials: + +- **project** This is the top\-level element in all Maven `pom.xml` files\. +- **modelVersion** This element indicates what version of the object model this POM is using\. The version of the model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when the Maven developers deem it necessary to change the model\. +- **groupId** This element indicates the unique identifier of the organization or group that created the project\. The groupId is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization\. For example `org.apache.maven.plugins` is the designated groupId for all Maven plugins\. +- **artifactId** This element indicates the unique base name of the primary artifact being generated by this project\. The primary artifact for a project is typically a JAR file\. Secondary artifacts like source bundles also use the artifactId as part of their final name\. A typical artifact produced by Maven would have the form <artifactId>\-<version>\.<extension> \(for example, `myapp-1.0.jar`\)\. +- **version** This element indicates the version of the artifact generated by the project\. Maven goes a long way to help you with version management and you will often see the `SNAPSHOT` designator in a version, which indicates that a project is in a state of development\. We will discuss the use of [snapshots](\./index\.html\#what\-is\-a\-snapshot\-version) and how they work further on in this guide\. +- **name** This element indicates the display name used for the project\. This is often used in Maven's generated documentation\. +- **url** This element indicates where the project's site can be found\. This is often used in Maven's generated documentation\. +- **properties** This element contains value placeholders accessible anywhere within a POM\. +- **dependencies** This element's children list [dependencies](/pom\.html\#dependencies)\. The cornerstone of the POM\. +- **build** This element handles things like declaring your project's directory structure and managing plugins\. + +For a complete reference of what elements are available for use in the POM please refer to our [POM Reference](/ref/current/maven\-model/maven\.html)\. Now let's get back to the project at hand\. + +After the archetype generation of your first project you will also notice that the following directory structure has been created: + +``` +my-app +|-- pom.xml +`-- src + |-- main + | `-- java + | `-- com + | `-- mycompany + | `-- app + | `-- App.java + `-- test + `-- java + `-- com + `-- mycompany + `-- app + `-- AppTest.java +``` + +As you can see, the project created from the archetype has a POM, a source tree for your application's sources and a source tree for your test sources\. This is the standard layout for Maven projects \(the application sources reside in `${project.basedir}/src/main/java` and test sources reside in `${project.basedir}/src/test/java`, where `${project.basedir}` represents the directory containing `pom.xml`\)\. + +If you were to create a Maven project by hand this is the directory structure that we recommend using\. This is a Maven convention and to learn more about it you can read our [Introduction to the Standard Directory Layout](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html)\. + +Now that we have a POM, some application sources, and some test sources you are probably asking\.\.\. + +## How do I compile my application sources? + +Change to the directory where `pom.xml` is created by archetype:generate and execute the following command to compile your application sources: + +``` +mvn compile +``` + +Upon executing this command you should see output like the following: + +``` +[INFO] Scanning for projects... +[INFO] +[INFO] ----------------------< com.mycompany.app:my-app >---------------------- +[INFO] Building my-app 1.0-SNAPSHOT +[INFO] --------------------------------[ jar ]--------------------------------- +[INFO] +[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- +[INFO] Using 'UTF-8' encoding to copy filtered resources. +[INFO] skip non existing resourceDirectory /my-app/src/main/resources +[INFO] +[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- +[INFO] Changes detected - recompiling the module! +[INFO] Compiling 1 source file to /my-app/target/classes +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 0.899 s +[INFO] Finished at: 2020-07-12T11:31:54+01:00 +[INFO] ------------------------------------------------------------------------ +``` + +The first time you execute this \(or any other\) command, Maven will need to download all the plugins and related dependencies it needs to fulfill the command\. From a clean installation of Maven, this can take quite a while \(in the output above, it took almost 4 minutes\)\. If you execute the command again, Maven will now have what it needs, so it won't need to download anything new and will be able to execute the command much more quickly\. + +As you can see from the output, the compiled classes were placed in `${project.basedir}/target/classes`, which is another standard convention employed by Maven\. So, if you're a keen observer, you'll notice that by using the standard conventions, the POM above is very small and you haven't had to tell Maven explicitly where any of your sources are or where the output should go\. By following the standard Maven conventions, you can get a lot done with very little effort\! Just as a casual comparison, let's take a look at what you might have had to do in [Ant](http://ant\.apache\.org) to accomplish the same [thing](\.\./\.\./ant/build\-a1\.xml)\. + +Now, this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same size as the POM shown above\. But we'll see how much more we can do with just that simple POM\! + +## How do I compile my test sources and run my unit tests? + +Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile and execute \(because every programmer always writes and executes their unit tests \*nudge nudge wink wink\*\)\. + +Execute the following command: + +``` +mvn test +``` + +Upon executing this command you should see output like the following: + +``` +[INFO] Scanning for projects... +[INFO] +[INFO] ----------------------< com.mycompany.app:my-app >---------------------- +[INFO] Building my-app 1.0-SNAPSHOT +[INFO] --------------------------------[ jar ]--------------------------------- +[INFO] +[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- +[INFO] Using 'UTF-8' encoding to copy filtered resources. +[INFO] skip non existing resourceDirectory /my-app/src/main/resources +[INFO] +[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- +[INFO] Nothing to compile - all classes are up to date +[INFO] +[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app --- +[INFO] Using 'UTF-8' encoding to copy filtered resources. +[INFO] skip non existing resourceDirectory /my-app/src/test/resources +[INFO] +[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app --- +[INFO] Changes detected - recompiling the module! +[INFO] Compiling 1 source file to /my-app/target/test-classes +[INFO] +[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app --- +[INFO] +[INFO] ------------------------------------------------------- +[INFO] T E S T S +[INFO] ------------------------------------------------------- +[INFO] Running com.mycompany.app.AppTest +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest +[INFO] +[INFO] Results: +[INFO] +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 1.881 s +[INFO] Finished at: 2020-07-12T12:00:33+01:00 +[INFO] ------------------------------------------------------------------------ +``` + +Some things to notice about the output: + +- Maven downloads more dependencies this time\. These are the dependencies and plugins necessary for executing the tests \(it already has the dependencies it needs for compiling and won't download them again\)\. +- Before compiling and executing the tests Maven compiles the main code \(all these classes are up to date because we haven't changed anything since we compiled last\)\. + +If you simply want to compile your test sources \(but not execute the tests\), you can execute the following: + +``` + mvn test-compile +``` + +Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move on to the next logical step so you'll be asking \.\.\. + +## How do I create a JAR and install it in my local repository? + +Making a JAR file is straight forward enough and can be accomplished by executing the following command: + + + +``` +mvn package +``` + +You can now take a look in the `${project.basedir}/target` directory and you will see the generated JAR file\. + +Now you'll want to install the artifact you've generated \(the JAR file\) in your local repository \(`${user.home}/.m2/repository` is the default location\)\. For more information on repositories you can refer to our [Introduction to Repositories](\.\./introduction/introduction\-to\-repositories\.html) but let's move on to installing our artifact\! To do so execute the following command: + +``` +mvn install +``` + +Upon executing this command you should see the following output: + +``` +[INFO] Scanning for projects... +[INFO] +[INFO] ----------------------< com.mycompany.app:my-app >---------------------- +[INFO] Building my-app 1.0-SNAPSHOT +[INFO] --------------------------------[ jar ]--------------------------------- +[INFO] +[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app --- +... +[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app --- +[INFO] Nothing to compile - all classes are up to date +[INFO] +[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app --- +... +[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app --- +[INFO] Nothing to compile - all classes are up to date +[INFO] +[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app --- +[INFO] +[INFO] ------------------------------------------------------- +[INFO] T E S T S +[INFO] ------------------------------------------------------- +[INFO] Running com.mycompany.app.AppTest +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest +[INFO] +[INFO] Results: +[INFO] +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +[INFO] +[INFO] +[INFO] --- maven-jar-plugin:3.0.2:jar (default-jar) @ my-app --- +[INFO] Building jar: /my-app/target/my-app-1.0-SNAPSHOT.jar +[INFO] +[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ my-app --- +[INFO] Installing /my-app/target/my-app-1.0-SNAPSHOT.jar to /com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar +[INFO] Installing /my-app/pom.xml to /com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.pom +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 1.678 s +[INFO] Finished at: 2020-07-12T12:04:45+01:00 +[INFO] ------------------------------------------------------------------------ +``` + +Note that the surefire plugin \(which executes the test\) looks for tests contained in files with a particular naming convention\. By default the tests included are: + +- `**/*Test.java` +- `**/Test*.java` +- `**/*TestCase.java` + +And the default excludes are: + +- `**/Abstract*Test.java` +- `**/Abstract*TestCase.java` + +You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project\. This is likely the vast majority of what projects will be doing with Maven and if you've noticed, everything you've been able to do up to this point has been driven by an 18\-line file, namely the project's model or POM\. If you look at a typical Ant [build file](\.\./\.\./ant/build\-a1\.xml) that provides the same functionality that we've achieved thus far you'll notice it's already twice the size of the POM and we're just getting started\! There is far more functionality available to you from Maven without requiring any additions to our POM as it currently stands\. To get any more functionality out of our example Ant build file you must keep making error\-prone additions\. + +So what else can you get for free? There are a great number of Maven plugins that work out of the box with even a simple POM like we have above\. We'll mention one here specifically as it is one of the highly prized features of Maven: without any work on your part this POM has enough information to generate a web site for your project\! You will most likely want to customize your Maven site but if you're pressed for time all you need to do to provide basic information about your project is execute the following command: + +``` +mvn site +``` + +There are plenty of other standalone goals that can be executed as well, for example: + +``` +mvn clean +``` + +This will remove the `target` directory with all the build data before starting so that it is fresh\. + +## What is a SNAPSHOT version? + +Notice the value of the **version** tag in the `pom.xml` file shown below has the suffix: `-SNAPSHOT`\. + +``` +... + my-app + ... + 1.0-SNAPSHOT + Maven Quick Start Archetype + ... +``` + +The `SNAPSHOT` value refers to the 'latest' code along a development branch, and provides no guarantee the code is stable or unchanging\. Conversely, the code in a 'release' version \(any version value without the suffix `SNAPSHOT`\) is unchanging\. + +In other words, a SNAPSHOT version is the 'development' version before the final 'release' version\. The SNAPSHOT is "older" than its release\. + +During the [release](\.\./\.\./plugins/maven\-release\-plugin/) process, a version of **x\.y\-SNAPSHOT** changes to **x\.y**\. The release process also increments the development version to **x\.\(y\+1\)\-SNAPSHOT**\. For example, version **1\.0\-SNAPSHOT** is released as version **1\.0**, and the new development version is version **1\.1\-SNAPSHOT**\. + +## How do I use plugins? + +Whenever you want to customise the build for a Maven project, this is done by adding or reconfiguring plugins\. + +For this example, we will configure the Java compiler to allow JDK 5\.0 sources\. This is as simple as adding this to your POM: + +``` +... + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.3 + + 1.5 + 1.5 + + + + +... +``` + +You'll notice that all plugins in Maven look much like a dependency \- and in some ways they are\. This plugin will be automatically downloaded and used \- including a specific version if you request it \(the default is to use the latest available\)\. + +The `configuration` element applies the given parameters to every goal from the compiler plugin\. In the above case, the compiler plugin is already used as part of the build process and this just changes the configuration\. It is also possible to add new goals to the process, and configure specific goals\. For information on this, see the [ Introduction to the Build Lifecycle](\.\./introduction/introduction\-to\-the\-lifecycle\.html)\. + +To find out what configuration is available for a plugin, you can see the [ Plugins List](\.\./\.\./plugins/) and navigate to the plugin and goal you are using\. For general information about how to configure the available parameters of a plugin, have a look at the [Guide to Configuring Plugins](\.\./mini/guide\-configuring\-plugins\.html)\. + +## How do I add resources to my JAR? + +Another common use case that can be satisfied which requires no changes to the POM that we have above is packaging resources in the JAR file\. For this common task, Maven again relies on the [Standard Directory Layout](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html), which means by using standard Maven conventions you can package resources within JARs simply by placing those resources in a standard directory structure\. + +You see below in our example we have added the directory `${project.basedir}/src/main/resources` into which we place any resources we wish to package in our JAR\. The simple rule employed by Maven is this: any directories or files placed within the `${project.basedir}/src/main/resources` directory are packaged in your JAR with the exact same structure starting at the base of the JAR\. + +``` +my-app +|-- pom.xml +`-- src + |-- main + | |-- java + | | `-- com + | | `-- mycompany + | | `-- app + | | `-- App.java + | `-- resources + | `-- META-INF + | `-- application.properties + `-- test + `-- java + `-- com + `-- mycompany + `-- app + `-- AppTest.java +``` + +So you can see in our example that we have a `META-INF` directory with an `application.properties` file within that directory\. If you unpacked the JAR that Maven created for you and took a look at it you would see the following: + +``` +|-- META-INF +| |-- MANIFEST.MF +| `-- application.properties +| `-- maven +| `-- com.mycompany.app +| `-- my-app +| |-- pom.properties +| `-- pom.xml +`-- com + `-- mycompany + `-- app + `-- App.class +``` + +As you can see, the contents of `${project.basedir}/src/main/resources` can be found starting at the base of the JAR and our `application.properties` file is there in the `META-INF` directory\. You will also notice some other files there like `META-INF/MANIFEST.MF` as well as a `pom.xml` and `pom.properties` file\. These come standard with generation of a JAR in Maven\. You can create your own manifest if you choose, but Maven will generate one by default if you don't\. \(You can also modify the entries in the default manifest\. We will touch on this later\.\) The `pom.xml` and `pom.properties` files are packaged up in the JAR so that each artifact produced by Maven is self\-describing and also allows you to utilize the metadata in your own application if the need arises\. One simple use might be to retrieve the version of your application\. Operating on the POM file would require you to use some Maven utilities but the properties can be utilized using the standard Java API and look like the following: + +``` +#Generated by Maven +#Tue Oct 04 15:43:21 GMT-05:00 2005 +version=1.0-SNAPSHOT +groupId=com.mycompany.app +artifactId=my-app +``` + +To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR except the directory you place resources in is `${project.basedir}/src/test/resources`\. At this point you would have a project directory structure that would look like the following: + +``` +my-app +|-- pom.xml +`-- src + |-- main + | |-- java + | | `-- com + | | `-- mycompany + | | `-- app + | | `-- App.java + | `-- resources + | `-- META-INF + | |-- application.properties + `-- test + |-- java + | `-- com + | `-- mycompany + | `-- app + | `-- AppTest.java + `-- resources + `-- test.properties +``` + +In a unit test you could use a simple snippet of code like the following to access the resource required for testing: + +``` +... + +// Retrieve resource +InputStream is = getClass().getResourceAsStream( "/test.properties" ); + +// Do something with the resource + +... +``` + +## How do I filter resource files? + +Sometimes a resource file will need to contain a value that can only be supplied at build time\. To accomplish this in Maven, put a reference to the property that will contain the value into your resource file using the syntax `${}`\. The property can be one of the values defined in your `pom.xml`, a value defined in the user's `settings.xml`, a property defined in an external properties file, or a system property\. + +To have Maven filter resources when copying, simply set `filtering` to true for the resource directory in your `pom.xml`: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + + + + + src/main/resources + true + + + + +``` + +You'll notice that we had to add the `build`, `resources`, and `resource` elements which weren't there before\. In addition, we had to explicitly state that the resources are located in the `src/main/resources` directory\. All of this information was provided as default values previously, but because the default value for `filtering` is false, we had to add this to our `pom.xml` in order to override that default value and set `filtering` to true\. + +To reference a property defined in your `pom.xml`, the property name uses the names of the XML elements that define the value, with "pom" being allowed as an alias for the project \(root\) element\. So `${project.name}` refers to the name of the project, `${project.version}` refers to the version of the project, `${project.build.finalName}` refers to the final name of the file created when the built project is packaged, etc\. Note that some elements of the POM have default values, so don't need to be explicitly defined in your `pom.xml` for the values to be available here\. Similarly, values in the user's `settings.xml` can be referenced using property names beginning with "settings" \(for example, `${settings.localRepository}` refers to the path of the user's local repository\)\. + +To continue our example, let's add a couple of properties to the `application.properties` file \(which we put in the `src/main/resources` directory\) whose values will be supplied when the resource is filtered: + +``` +# application.properties +application.name=${project.name} +application.version=${project.version} +``` + +With that in place, you can execute the following command \(process\-resources is the build lifecycle phase where the resources are copied and filtered\): + +``` +mvn process-resources +``` + +and the `application.properties` file under `target/classes` \(and will eventually go into the jar\) looks like this: + +``` +# application.properties +application.name=Maven Quick Start Archetype +application.version=1.0-SNAPSHOT +``` + +To reference a property defined in an external file, all you need to do is add a reference to this external file in your `pom.xml`\. First, let's create our external properties file and call it `src/main/filters/filter.properties`: + +``` +# filter.properties +my.filter.value=hello! +``` + +Next, we'll add a reference to this new file in the `pom.xml`: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + + + + src/main/filters/filter.properties + + + + src/main/resources + true + + + + +``` + +Then, if we add a reference to this property in the `application.properties` file: + +``` +# application.properties +application.name=${project.name} +application.version=${project.version} +message=${my.filter.value} +``` + +the next execution of the `mvn process-resources` command will put our new property value into `application.properties`\. As an alternative to defining the my\.filter\.value property in an external file, you could also have defined it in the `properties` section of your `pom.xml` and you'd get the same effect \(notice I don't need the references to `src/main/filters/filter.properties` either\): + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + + + + + src/main/resources + true + + + + + + hello + + +``` + +Filtering resources can also get values from system properties; either the system properties built into Java \(like `java.version` or `user.home`\) or properties defined on the command line using the standard Java \-D parameter\. To continue the example, let's change our `application.properties` file to look like this: + +``` +# application.properties +java.version=${java.version} +command.line.prop=${command.line.prop} +``` + +Now, when you execute the following command \(note the definition of the command\.line\.prop property on the command line\), the `application.properties` file will contain the values from the system properties\. + +``` +mvn process-resources "-Dcommand.line.prop=hello again" +``` + +## How do I use external dependencies? + +You've probably already noticed a `dependencies` element in the POM we've been using as an example\. You have, in fact, been using an external dependency all this time, but here we'll talk about how this works in a bit more detail\. For a more thorough introduction, please refer to our [Introduction to Dependency Mechanism](\.\./introduction/introduction\-to\-dependency\-mechanism\.html)\. + +The `dependencies` section of the `pom.xml` lists all of the external dependencies that our project needs in order to build \(whether it needs that dependency at compile time, test time, run time, or whatever\)\. Right now, our project is depending on JUnit only \(I took out all of the resource filtering stuff for clarity\): + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + +``` + +For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope\. The groupId, artifactId, and version are the same as those given in the `pom.xml` for the project that built that dependency\. The scope element indicates how your project uses that dependency, and can be values like `compile`, `test`, and `runtime`\. For more information on everything you can specify for a dependency, see the [Project Descriptor Reference](/ref/current/maven\-model/maven\.html)\. + + + +For more information about the dependency mechanism as a whole, see [Introduction to Dependency Mechanism](\.\./introduction/introduction\-to\-dependency\-mechanism\.html)\. + +With this information about a dependency, Maven will be able to reference the dependency when it builds the project\. Where does Maven reference the dependency from? Maven looks in your local repository \(`${user.home}/.m2/repository` is the default location\) to find all dependencies\. In a [previous section](How\_do\_I\_create\_a\_JAR\_and\_install\_it\_in\_my\_local\_repository), we installed the artifact from our project \(my\-app\-1\.0\-SNAPSHOT\.jar\) into the local repository\. Once it's installed there, another project can reference that jar as a dependency simply by adding the dependency information to its `pom.xml`: + +``` + + com.mycompany.app + my-other-app + ... + + ... + + com.mycompany.app + my-app + 1.0-SNAPSHOT + compile + + + +``` + +What about dependencies built somewhere else? How do they get into my local repository? Whenever a project references a dependency that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository\. You probably noticed Maven downloading a lot of things when you built your very first project \(these downloads were dependencies for the various plugins used to build the project\)\. By default, the remote repository Maven uses can be found \(and browsed\) at [https://repo\.maven\.apache\.org/maven2/](https://repo\.maven\.apache\.org/maven2/)\. You can also set up your own remote repository \(maybe a central repository for your company\) to use instead of or in addition to the default remote repository\. For more information on repositories you can refer to the [Introduction to Repositories](\.\./introduction/introduction\-to\-repositories\.html)\. + +Let's add another dependency to our project\. Let's say we've added some logging to the code and need to add log4j as a dependency\. First, we need to know what the groupId, artifactId, and version are for log4j\. The appropriate directory on Maven Central is called [/maven2/log4j/log4j](https://repo\.maven\.apache\.org/maven2/log4j/log4j/)\. In that directory is a file called maven\-metadata\.xml\. Here's what the maven\-metadata\.xml for log4j looks like: + +``` + + log4j + log4j + 1.1.3 + + + 1.1.3 + 1.2.4 + 1.2.5 + 1.2.6 + 1.2.7 + 1.2.8 + 1.2.11 + 1.2.9 + 1.2.12 + + + +``` + +From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j"\. We see lots of different version values to choose from; for now, we'll just use the latest version, 1\.2\.12 \(some maven\-metadata\.xml files may also specify which version is the current release version: see [repository metadata reference](/ref/current/maven\-repository\-metadata/repository\-metadata\.html)\)\. Alongside the maven\-metadata\.xml file, we can see a directory corresponding to each version of the log4j library\. Inside each of these, we'll find the actual jar file \(e\.g\. log4j\-1\.2\.12\.jar\) as well as a pom file \(this is the `pom.xml` for the dependency, indicating any further dependencies it might have and other information\) and another maven\-metadata\.xml file\. There's also an md5 file corresponding to each of these, which contains an MD5 hash for these files\. You can use this to authenticate the library or to figure out which version of a particular library you may be using already\. + +Now that we know the information we need, we can add the dependency to our pom\.xml: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + log4j + log4j + 1.2.12 + compile + + + +``` + +Now, when we compile the project \(`mvn compile`\), we'll see Maven download the log4j dependency for us\. + + +## How do I deploy my jar in my remote repository? + +For deploying jars to an external repository, you have to configure the repository url in the `pom.xml` and the authentication information for connecting to the repository in the `settings.xml`\. + +Here is an example using scp and username/password authentication: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + jar + + Maven Quick Start Archetype + http://maven.apache.org + + + + junit + junit + 4.11 + test + + + org.apache.codehaus.plexus + plexus-utils + 1.0.4 + + + + + + src/main/filters/filters.properties + + + + src/main/resources + true + + + + + + + mycompany-repository + MyCompany Repository + scp://repository.mycompany.com/repository/maven2 + + + +``` + +``` + + ... + + + mycompany-repository + jvanzyl + + /path/to/identity (default is ~/.ssh/id_dsa) + my_key_passphrase + + + ... + +``` + +Note that if you are connecting to an openssh ssh server which has the parameter "PasswordAuthentication" set to "no" in the sshd\_config, you will have to type your password each time for username/password authentication \(although you can log in using another ssh client by typing in the username and password\)\. You might want to switch to public key authentication in this case\. + +Care should be taken if using passwords in `settings.xml`\. For more information, see [ Password Encryption](\.\./mini/guide\-encryption\.html)\. + +## How do I create documentation? + +To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site for your existing project using the following command: + +``` +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-site \ + -DgroupId=com.mycompany.app \ + -DartifactId=my-app-site +``` + +Now head on over to the [Guide to creating a site](\.\./mini/guide\-site\.html) to learn how to create the documentation for your project\. + +## How do I build other types of projects? + +Note that the lifecycle applies to any project type\. For example, back in the base directory we can create a simple web application: + +``` +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp \ + -DgroupId=com.mycompany.app \ + -DartifactId=my-webapp +``` + +Note that these must all be on a single line\. This will create a directory called `my-webapp` containing the following project descriptor: + +``` + + 4.0.0 + + com.mycompany.app + my-webapp + 1.0-SNAPSHOT + war + + + + junit + junit + 4.11 + test + + + + + my-webapp + + +``` + +Note the `` element \- this tells Maven to build as a WAR\. Change into the webapp project's directory and try: + +``` +mvn package +``` + +You'll see `target/my-webapp.war` is built, and that all the normal steps were executed\. + +## How do I build more than one project at once? + +The concept of dealing with multiple modules is built in to Maven\. In this section, we will show how to build the WAR above, and include the previous JAR as well in one step\. + +Firstly, we need to add a parent `pom.xml` file in the directory above the other two, so it should look like this: + +``` ++- pom.xml ++- my-app +| +- pom.xml +| +- src +| +- main +| +- java ++- my-webapp +| +- pom.xml +| +- src +| +- main +| +- webapp +``` + +The POM file you'll create should contain the following: + +``` + + 4.0.0 + + com.mycompany.app + app + 1.0-SNAPSHOT + pom + + + my-app + my-webapp + + +``` + +We'll need a dependency on the JAR from the webapp, so add this to `my-webapp/pom.xml`: + +``` + ... + + + com.mycompany.app + my-app + 1.0-SNAPSHOT + + ... + +``` + +Finally, add the following `` element to both of the other `pom.xml` files in the subdirectories: + +``` + + + com.mycompany.app + app + 1.0-SNAPSHOT + + ... +``` + +Now, try it\.\.\. from the top level directory, run: + +``` +mvn verify +``` + +The WAR has now been created in `my-webapp/target/my-webapp.war`, and the JAR is included: + +``` +$ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war + 0 Fri Jun 24 10:59:56 EST 2005 META-INF/ + 222 Fri Jun 24 10:59:54 EST 2005 META-INF/MANIFEST.MF + 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/ + 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/ + 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/ +3239 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.xml + 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/ + 215 Fri Jun 24 10:59:56 EST 2005 WEB-INF/web.xml + 123 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.properties + 52 Fri Jun 24 10:59:56 EST 2005 index.jsp + 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/ +2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar +``` + +How does this work? Firstly, the parent POM created \(called `app`\), has a packaging of `pom` and a list of modules defined\. This tells Maven to run all operations over the set of projects instead of just the current one \(to override this behaviour, you can use the `--non-recursive` command line option\)\. + +Next, we tell the WAR that it requires the `my-app` JAR\. This does a few things: it makes it available on the classpath to any code in the WAR \(none in this case\), it makes sure the JAR is always built before the WAR, and it indicates to the WAR plugin to include the JAR in its library directory\. + +You may have noticed that `junit-4.11.jar` was a dependency, but didn't end up in the WAR\. The reason for this is the `test` element \- it is only required for testing, and so is not included in the web application as the compile time dependency `my-app` is\. + +The final step was to include a parent definition\. This ensures that the POM can always be located even if the project is distributed separately from its parent by looking it up in the repository\. + diff --git a/content/markdown/guides/getting-started/maven-in-five-minutes.md b/content/markdown/guides/getting-started/maven-in-five-minutes.md new file mode 100644 index 0000000000..f0d3b88f57 --- /dev/null +++ b/content/markdown/guides/getting-started/maven-in-five-minutes.md @@ -0,0 +1,260 @@ +--- +title: Maven in 5 Minutes +author: + - Eric Redmond +date: 2008-01-01 +--- + + + + + + + + + + + + + + + + + + + +# Maven in 5 Minutes + +## Prerequisites + +You must understand how to install software on your computer\. If you do not know how to do this, please ask someone at your office, school, etc\. or pay someone to explain this to you\. The Maven mailing lists are not the best place to ask for this advice\. + +## Installation + +_Maven is a Java tool, so you must have [Java](https://www\.oracle\.com/technetwork/java/javase/downloads/index\.html) installed in order to proceed\._ + +First, [download Maven](\.\./\.\./download\.html) and follow the [installation instructions](\.\./\.\./install\.html)\. After that, type the following in a terminal or in a command prompt: + +``` +mvn --version +``` + +It should print out your installed version of Maven, for example: + +``` +Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f) +Maven home: D:\apache-maven-3.6.3\apache-maven\bin\.. +Java version: 1.8.0_232, vendor: AdoptOpenJDK, runtime: C:\Program Files\AdoptOpenJDK\jdk-8.0.232.09-hotspot\jre +Default locale: en_US, platform encoding: Cp1250 +OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows" +``` + +Depending upon your network setup, you may require extra configuration\. Check out the [Guide to Configuring Maven](\.\./mini/guide\-configuring\-maven\.html) if necessary\. + +**If you are using Windows, you should look at** [Windows Prerequisites](\./windows\-prerequisites\.html) **to ensure that you are prepared to use Maven on Windows\.** + +## Creating a Project + +You need somewhere for your project to reside\. Create a directory somewhere and start a shell in that directory\. On your command line, execute the following Maven goal: + +``` +mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false +``` + +_If you have just installed Maven, it may take a while on the first run\. This is because Maven is downloading the most recent artifacts \(plugin jars and other files\) into your local repository\. You may also need to execute the command a couple of times before it succeeds\. This is because the remote server may time out before your downloads are complete\. Don't worry, there are ways to fix that\._ + +You will notice that the _generate_ goal created a directory with the same name given as the artifactId\. Change into that directory\. + +``` +cd my-app +``` + +Under this directory you will notice the following [standard project structure](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html)\. + +``` +my-app +|-- pom.xml +`-- src + |-- main + | `-- java + | `-- com + | `-- mycompany + | `-- app + | `-- App.java + `-- test + `-- java + `-- com + `-- mycompany + `-- app + `-- AppTest.java +``` + +The `src/main/java` directory contains the project source code, the `src/test/java` directory contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM\. + +### The POM + +The `pom.xml` file is the core of a project's configuration in Maven\. It is a single configuration file that contains the majority of information required to build a project in just the way you want\. The POM is huge and can be daunting in its complexity, but it is not necessary to understand all of the intricacies just yet to use it effectively\. This project's POM should look like this: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1.0-SNAPSHOT + + my-app + + http://www.example.com + + + UTF-8 + 17 + + + + + + org.junit + junit-bom + 5.11.0 + pom + import + + + + + + + org.junit.jupiter + junit-jupiter-api + test + + + + org.junit.jupiter + junit-jupiter-params + test + + + + + + ... lots of helpful plugins + + + +``` + +### What did I just do? + +You executed the Maven goal _archetype:generate_, and passed in various parameters to that goal\. The prefix _archetype_ is the [plugin](\.\./\.\./plugins/index\.html) that provides the goal\. If you are familiar with [Ant](http://ant\.apache\.org), you may conceive of this as similar to a task\. This _archetype:generate_ goal created a simple project based upon a [maven\-archetype\-quickstart](/archetypes/maven\-archetype\-quickstart/) archetype\. Suffice it to say for now that a _plugin_ is a collection of _goals_ with a general common purpose\. For example the jboss\-maven\-plugin, whose purpose is "deal with various jboss items"\. + +### Build the Project + +``` +mvn package +``` + +The command line will print out various actions, and end with the following: + +``` + ... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 2.953 s +[INFO] Finished at: 2019-11-24T13:05:10+01:00 +[INFO] ------------------------------------------------------------------------ +``` + +Unlike the first command executed \(_archetype:generate_\), the second is simply a single word \- _package_\. Rather than a _goal_, this is a _phase_\. A phase is a step in the [build lifecycle](\.\./introduction/introduction\-to\-the\-lifecycle\.html), which is an ordered sequence of phases\. When a phase is given, Maven executes every phase in the sequence up to and including the one defined\. For example, if you execute the _compile_ phase, the phases that actually get executed are: + +1. validate +1. generate\-sources +1. process\-sources +1. generate\-resources +1. process\-resources +1. compile + +You may test the newly compiled and packaged JAR with the following command: + +``` +java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App +``` + +Which will print the quintessential: + +``` +Hello World! +``` + +## Java 9 or later + +By default your version of Maven might use an old version of the `maven-compiler-plugin` that is not compatible with Java 9 or later versions\. To target Java 9 or later, you should at least use version 3\.6\.0 of the `maven-compiler-plugin` and set the `maven.compiler.release` property to the Java release you are targetting \(e\.g\. 9, 10, 11, 12, etc\.\)\. + +In the following example, we have configured our Maven project to use version 3\.8\.1 of `maven-compiler-plugin` and target Java 11: + +``` + + 11 + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.1 + + + + +``` + +To learn more about `javac`'s `--release` option, see [JEP 247](https://openjdk\.java\.net/jeps/247)\. + +## Running Maven Tools + +### Maven Phases + +Although hardly a comprehensive list, these are the most common _default_ lifecycle phases executed\. + +- **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\. + +There are two other Maven lifecycles of note beyond the _default_ list above\. They are + +- **clean**: cleans up artifacts created by prior builds +- **site**: generates site documentation for this project + +Phases are actually mapped to underlying goals\. The specific goals executed per phase is dependant upon the packaging type of the project\. For example, _package_ executes _jar:jar_ if the project type is a JAR, and _war:war_ if the project type is \- you guessed it \- a WAR\. + +An interesting thing to note is that phases and goals may be executed in sequence\. + +``` +mvn clean dependency:copy-dependencies package +``` + +This command will clean the project, copy dependencies, and package the project \(executing all phases up to _package_, of course\)\. + +### Generating the Site + +``` +mvn site +``` + +This phase generates a site based upon information on the project's pom\. You can look at the documentation generated under `target/site`\. + +## Conclusion + +We hope this quick overview has piqued your interest in the versatility of Maven\. Note that this is a very truncated quick\-start guide\. Now you are ready for more comprehensive details concerning the actions you have just performed\. Check out the [Maven Getting Started Guide](\./index\.html)\. + diff --git a/content/markdown/guides/getting-started/windows-prerequisites.md b/content/markdown/guides/getting-started/windows-prerequisites.md new file mode 100644 index 0000000000..733a634c96 --- /dev/null +++ b/content/markdown/guides/getting-started/windows-prerequisites.md @@ -0,0 +1,53 @@ +--- +title: Maven on Windows +author: + - Benson Margulies +date: 2012-07-01 +--- + + + + + + + + + + + + + + + + + + + +# Maven on Windows + +Maven is a command\-line tool for building Java \(and other\) programs\. The Maven project provides a simple ZIP file containing a precompiled version of Maven for your convenience\. There is no installer\. It's up to you to set up your prerequisites and environment to run Maven on Windows\. + +## Prerequisites + +Maven is written in Java \(and primarily used to build Java programs\)\. Thus, the major prerequisite is the Java SDK\. You need to install the Java SDK \(e\.g\. from [Oracle's download site](https://www\.oracle\.com/technetwork/java/javase/downloads/index\.html)\)\. + +Once Java is installed, you must ensure that the commands from the Java SDK are in your PATH environment variable\. Running, for example, + +``` +java -version +``` + +must show the right version number\. + +## Maven Unpacked + +You need to unpack the Maven distribution\. Don't unpack it in the middle of your source code; pick some location and unpack it there\. Let's assume that the path is `${maven.home}`\. + +## Maven in PATH + +You run Maven by invoking a command\-line tool: `mvn.cmd` from the `bin` directory of the Maven\. To do this conveniently, `${maven.home}\bin` must be in your PATH, just like the Java SDK commands\. You can add directories to your `PATH` in the control panel; the details vary by Windows version\. + +## Firewalls and Anti\-virus + +Firewall and Anti\-virus sometimes prevent Java from running properly, or Windows Firewall \(and various other Firewalls\) actively prevent Java\.exe from reaching out to the Internet to "download stuff" which is a key part of Maven\. You may need to configure the Firewall or Anti\-virus to add exceptions to allow such actions\. + diff --git a/content/markdown/guides/introduction/introduction-to-archetypes.md b/content/markdown/guides/introduction/introduction-to-archetypes.md new file mode 100644 index 0000000000..c51c0a15ae --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-archetypes.md @@ -0,0 +1,69 @@ +--- +title: Introduction to Archetypes +author: + - Jason van Zyl +date: 2009-08-26 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to Archetypes + +# What is Archetype? + +In short, Archetype is a Maven project templating toolkit\. An archetype is defined as _an original pattern or model from which all other things of the same kind are made_\. The name fits as we are trying to provide a system that provides a consistent means of generating Maven projects\. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates\. + +Using archetypes provides a great way to enable developers work quickly in a way consistent with best practices employed by your project or organization\. Within the Maven project, we use archetypes to try and get our users up and running as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing new users to the best practices employed by Maven\. In a matter of seconds, a new user can have a working Maven project to use as a jumping board for investigating more of the features in Maven\. We have also tried to make the Archetype mechanism additive, and by that we mean allowing portions of a project to be captured in an archetype so that pieces or aspects of a project can be added to existing projects\. A good example of this is the Maven site archetype\. If, for example, you have used the quick start archetype to generate a working project, you can then quickly create a site for that project by using the site archetype within that existing project\. You can do anything like this with archetypes\. + +You may want to standardize J2EE development within your organization, so you may want to provide archetypes for EJBs, or WARs, or for your web services\. Once these archetypes are created and deployed in your organization's repository, they are available for use by all developers within your organization\. + +## Using an Archetype + +To create a new project based on an Archetype, you need to call `mvn archetype:generate` goal, like the following: + +``` +mvn archetype:generate +``` + +Please refer to [Archetype Plugin page](/archetype/maven\-archetype\-plugin/)\. + +## Provided Archetypes + +Maven provides several Archetype artifacts: + +|Archetype ArtifactIds|Description| +|---|---| +|maven\-archetype\-archetype|An archetype to generate a sample archetype project\.| +|maven\-archetype\-j2ee\-simple|An archetype to generate a simplifed sample J2EE application\.| +|maven\-archetype\-mojo|An archetype to generate a sample a sample Maven plugin\.| +|maven\-archetype\-plugin|An archetype to generate a sample Maven plugin\.| +|maven\-archetype\-plugin\-site|An archetype to generate a sample Maven plugin site\.| +|maven\-archetype\-portlet|An archetype to generate a sample JSR\-268 Portlet\.| +|maven\-archetype\-quickstart|An archetype to generate a sample Maven project\.| +|maven\-archetype\-simple|An archetype to generate a simple Maven project\.| +|maven\-archetype\-site|An archetype to generate a sample Maven site which demonstrates some of the supported document types like APT, XDoc, and FML and demonstrates how to i18n your site\.| +|maven\-archetype\-site\-simple|An archetype to generate a sample Maven site\.| +|maven\-archetype\-webapp|An archetype to generate a sample Maven Webapp project\.| + +For more information on these archetypes, please refer to the [Maven Archetype Bundles page](/archetypes/index\.html)\. + +## What makes up an Archetype? + +Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of archetype, and a set of [Velocity](http://velocity\.apache\.org/) templates which make up the prototype project\. If you would like to know how to make your own archetypes, please refer to our [Guide to creating archetypes](\.\./mini/guide\-creating\-archetypes\.html)\. + diff --git a/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md new file mode 100644 index 0000000000..8150bffb8c --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md @@ -0,0 +1,756 @@ +--- +title: Introduction to the Dependency Mechanism +author: + - Brett Porter + - Trygve Laugstol + - Karl Heinz Marbaise +date: 2005-10-12 +2016-06-17 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to the Dependency Mechanism + +Dependency management is a core feature of Maven\. Managing dependencies for a single project is easy\. Managing dependencies for multi\-module projects and applications that consist of hundreds of modules is possible\. Maven helps a great deal in defining, creating, and maintaining reproducible builds with well\-defined classpaths and library versions\. + +Learn more about: + +- [Transitive Dependencies](Transitive\_Dependencies) + - Excluded/Optional Dependencies +- [Dependency Scope](Dependency\_Scope) +- [Dependency Management](Dependency\_Management) + - [Importing Dependencies](Importing\_Dependencies) + - [Bill of Materials \(BOM\) POMs](bill\-of\-materials\-bom\-poms) +- [System Dependencies](System\_Dependencies) +## Transitive Dependencies + +Maven avoids the need to discover and specify the libraries that your own dependencies require by including transitive dependencies automatically\. + +This feature is facilitated by reading the project files of your dependencies from the remote repositories specified\. In general, all dependencies of those projects are used in your project, as are any that the project inherits from its parents, or from its dependencies, and so on\. + +There is no limit to the number of levels that dependencies can be gathered from\. A problem arises only if a cyclic dependency is discovered\. + +With transitive dependencies, the graph of included libraries can quickly grow quite large\. For this reason, there are additional features that limit which dependencies are included: + +- _Dependency mediation_ \- this determines what version of an artifact will be chosen when multiple versions are encountered as dependencies\. Maven picks the "nearest definition"\. That is, it uses the version of the closest dependency to your project in the tree of dependencies\. You can always guarantee a version by declaring it explicitly in your project's POM\. Note that if two dependency versions are at the same depth in the dependency tree, the first declaration wins\. + - "nearest definition" means that the version used will be the closest one to your project in the tree of dependencies\. Consider this tree of dependencies: + + ``` + A + ├── B + │ └── C + │ └── D 2.0 + └── E + └── D 1.0 + ``` + + In text, dependencies for A, B, and C are defined as A \-> B \-> C \-> D 2\.0 and A \-> E \-> D 1\.0, then D 1\.0 will be used when building A because the path from A to D through E is shorter\. You could explicitly add a dependency to D 2\.0 in A to force the use of D 2\.0, as shown here: + + ``` + A + ├── B + │ └── C + │ └── D 2.0 + ├── E + │ └── D 1.0 + │ + └── D 2.0 + ``` + +- _Dependency management_ \- this allows project authors to directly specify the versions of artifacts to be used when they are encountered in transitive dependencies or in dependencies where no version has been specified\. In the example in the preceding section a dependency was directly added to A even though it is not directly used by A\. Instead, A can include D as a dependency in its dependencyManagement section and directly control which version of D is used when, or if, it is ever referenced\. +- _Dependency scope_ \- this allows you to only include dependencies appropriate for the current stage of the build\. This is described in more detail below\. +- _Excluded dependencies_ \- If project X depends on project Y, and project Y depends on project Z, the owner of project X can explicitly exclude project Z as a dependency, using the "exclusion" element\. +- _Optional dependencies_ \- If project Y depends on project Z, the owner of project Y can mark project Z as an optional dependency, using the "optional" element\. When project X depends on project Y, X will depend only on Y and not on Y's optional dependency Z\. The owner of project X may then explicitly add a dependency on Z, at her option\. \(It may be helpful to think of optional dependencies as "excluded by default\."\) + +Although transitive dependencies can implicitly include desired dependencies, it is a good practice to explicitly specify the dependencies your source code uses directly\. This best practice proves its value especially when the dependencies of your project change their dependencies\. + +For example, assume that your project A specifies a dependency on another project B, and project B specifies a dependency on project C\. If you are directly using components in project C, and you don't specify project C in your project A, it may cause build failure when project B suddenly updates/removes its dependency on project C\. + +Another reason to directly specify dependencies is that it provides better documentation for your project: one can learn more information by just reading the POM file in your project, or by executing **mvn dependency:tree**\. + +Maven also provides [dependency:analyze](/plugins/maven\-dependency\-plugin/analyze\-mojo\.html) plugin goal for analyzing the dependencies: it helps making this best practice more achievable\. + +## Dependency Scope + +Dependency scope is used to limit the transitivity of a dependency and to determine when a dependency is included in a classpath\. + +There are 6 scopes: + +- **compile** + This is the default scope, used if none is specified\. Compile dependencies are available in all classpaths of a project\. Furthermore, those dependencies are propagated to dependent projects\. +- **provided** + This is much like `compile`, but indicates you expect the JDK or a container to provide the dependency at runtime\. For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the Servlet API and related Java EE APIs to scope `provided` because the web container provides those classes\. A dependency with this scope is added to the classpath used for compilation and test, but not the runtime classpath\. It is not transitive\. +- **runtime** + This scope indicates that the dependency is not required for compilation, but is for execution\. Maven includes a dependency with this scope in the runtime and test classpaths, but not the compile classpath\. +- **test** + This scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases\. This scope is not transitive\. Typically this scope is used for test libraries such as JUnit and Mockito\. It is also used for non\-test libraries such as Apache Commons IO if those libraries are used in unit tests \(src/test/java\) but not in the model code \(src/main/java\)\. +- **system** + This scope is similar to `provided` except that you have to provide the JAR which contains it explicitly\. The artifact is always available and is not looked up in a repository\. +- **import** + This scope is only supported on a dependency of type `pom` in the `` section\. It indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's `` section\. Since they are replaced, dependencies with a scope of `import` do not actually participate in limiting the transitivity of a dependency\. + +Each of the scopes \(except for `import`\) affects transitive dependencies in different ways, as is demonstrated in the table below\. If a dependency is set to the scope in the left column, a transitive dependency of that dependency with the scope across the top row results in a dependency in the main project with the scope listed at the intersection\. If no scope is listed, it means the dependency is omitted\. + +| | | | | | +|---|---|---|---|---| +||compile|provided|runtime|test| +|compile|compile\(\*\)|\-|runtime|\-| +|provided|provided|\-|provided|\-| +|runtime|runtime|\-|runtime|\-| +|test|test|\-|test|\-| + +**\(\*\) Note:** it is intended that this should be runtime scope instead, so that all compile dependencies must be explicitly listed\. However, if a library you depend on extends a class from another library, both must be available at compile time\. For this reason, compile time dependencies remain as compile scope even when they are transitive\. + +## Dependency Management + +The dependency management section is a mechanism for centralizing dependency information\. When you have a set of projects that inherit from a common parent, it's possible to put all information about the dependency in the common POM and have simpler references to the artifacts in the child POMs\. The mechanism is best illustrated through some examples\. Given these two POMs which extend the same parent: + +Project A: + +``` + + + ... + + + group-a + artifact-a + 1.0 + + + group-c + excluded-artifact + + + + + group-a + artifact-b + 1.0 + bar + runtime + + + +``` + +Project B: + +``` + + + ... + + + group-c + artifact-b + 1.0 + war + runtime + + + group-a + artifact-b + 1.0 + bar + runtime + + + +``` + +These two example POMs share a common dependency and each has one non\-trivial dependency\. This information can be put in the parent POM like this: + +``` + + + ... + + + + group-a + artifact-a + 1.0 + + + + group-c + excluded-artifact + + + + + + + group-c + artifact-b + 1.0 + war + runtime + + + + group-a + artifact-b + 1.0 + bar + runtime + + + + +``` + +Then the two child POMs become much simpler: + +``` + + + ... + + + group-a + artifact-a + + + + group-a + artifact-b + + bar + + + +``` + +``` + + + ... + + + group-c + artifact-b + + war + + + + group-a + artifact-b + + bar + + + +``` + +**NOTE:** In two of these dependency references, we had to specify the <type/> element\. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually **\{groupId, artifactId, type, classifier\}**\. In many cases, these dependencies will refer to jar artifacts with no classifier\. This allows us to shorthand the identity set to **\{groupId, artifactId\}**, since the default for the type field is `jar`, and the default classifier is null\. + +A second, and very important use of the dependency management section is to control the versions of artifacts used in transitive dependencies\. As an example consider these projects: + +Project A: + +``` + + + 4.0.0 + maven + A + pom + A + 1.0 + + + + test + a + 1.2 + + + test + b + 1.0 + compile + + + test + c + 1.0 + compile + + + test + d + 1.2 + + + + +``` + +Project B: + +``` + + + + A + maven + 1.0 + + 4.0.0 + maven + B + pom + B + 1.0 + + + + + test + d + 1.0 + + + + + + + test + a + 1.0 + runtime + + + test + c + runtime + + + +``` + +When maven is run on project B, version 1\.0 of artifacts a, b, c, and d will be used regardless of the version specified in their POM\. + +- a and c both are declared as dependencies of the project so version 1\.0 is used due to dependency mediation\. Both also have runtime scope since it is directly specified\. +- b is defined in B's parent's dependency management section and since dependency management takes precedence over dependency mediation for transitive dependencies, version 1\.0 will be selected should it be referenced in a or c's POM\. b will also have compile scope\. +- Finally, since d is specified in B's dependency management section, should d be a dependency \(or transitive dependency\) of a or c, version 1\.0 will be chosen \- again because dependency management takes precedence over dependency mediation and also because the current POM's declaration takes precedence over its parent's declaration\. + +**NOTE:** The dependency management won't affect the \(transitive\) dependencies of any _plugins_ used in the same effective POM but only the \(transitive\) project dependencies\. + +The reference information about the dependency management tags is available from the [project descriptor reference](\.\./\.\./ref/current/maven\-model/maven\.html\#class\_DependencyManagement)\. + +### Importing Dependencies + +The examples in the previous section describe how to specify managed dependencies through inheritance\. However, in larger projects it may be impossible to accomplish this since a project can only inherit from a single parent\. To accommodate this, projects can import managed dependencies from other projects\. This is accomplished by declaring a POM artifact as a dependency with a scope of "import"\. + +Project B: + +``` + + + 4.0.0 + maven + B + pom + B + 1.0 + + + + + maven + A + 1.0 + pom + import + + + test + d + 1.0 + + + + + + + test + a + 1.0 + runtime + + + test + c + runtime + + + +``` + +Assuming A is the POM defined in the preceding example, the end result would be the same\. All of A's managed dependencies would be incorporated into B except for d since it is defined in this POM\. + +Project X: + +``` + + + 4.0.0 + maven + X + pom + X + 1.0 + + + + + test + a + 1.1 + + + test + b + 1.0 + compile + + + + +``` + +Project Y: + +``` + + + 4.0.0 + maven + Y + pom + Y + 1.0 + + + + + test + a + 1.2 + + + test + c + 1.0 + compile + + + + +``` + +Project Z: + +``` + + + 4.0.0 + maven + Z + pom + Z + 1.0 + + + + + maven + X + 1.0 + pom + import + + + maven + Y + 1.0 + pom + import + + + + +``` + +In the example above Z imports the managed dependencies from both X and Y\. However, both X and Y contain dependency a\. Here, version 1\.1 of a would be used since X is declared first and a is not declared in Z's dependencyManagement\. + +This process is recursive\. For example, if X imports another POM, Q, when Z is processed it will simply appear that all of Q's managed dependencies are defined in X\. + +### Bill of Materials \(BOM\) POMs + +Imports are most effective when used for defining a "library" of related artifacts that are generally part of a multiproject build\. It is fairly common for one project to use one or more artifacts from these libraries\. However, it has sometimes been difficult to keep the versions in the project using the artifacts in synch with the versions distributed in the library\. The pattern below illustrates how a "bill of materials" \(BOM\) can be created for use by other projects\. + +The root of the project is the BOM POM\. It defines the versions of all the artifacts that will be created in the library\. Other projects that wish to use the library should import this POM into the dependencyManagement section of their POM\. + +``` + + + 4.0.0 + com.test + bom + 1.0.0 + pom + + 1.0.0 + 1.0.0 + + + + + + com.test + project1 + ${project1Version} + + + com.test + project2 + ${project2Version} + + + + + + parent + + +``` + +The parent subproject has the BOM POM as its parent\. It is a normal multiproject pom\. + +``` + + + 4.0.0 + + com.test + 1.0.0 + bom + + + com.test + parent + 1.0.0 + pom + + + + + log4j + log4j + 1.2.12 + + + commons-logging + commons-logging + 1.1.1 + + + + + project1 + project2 + + +``` + +Next are the actual project POMs\. + +``` + + + 4.0.0 + + com.test + 1.0.0 + parent + + com.test + project1 + ${project1Version} + jar + + + + log4j + log4j + + + + + + 4.0.0 + + com.test + 1.0.0 + parent + + com.test + project2 + ${project2Version} + jar + + + + commons-logging + commons-logging + + + +``` + +The project that follows shows how the library can now be used in another project without having to specify the dependent project's versions\. + +``` + + 4.0.0 + com.test + use + 1.0.0 + jar + + + + + com.test + bom + 1.0.0 + pom + import + + + + + + com.test + project1 + + + com.test + project2 + + + +``` + +Finally, when creating projects that import dependencies, beware of the following: + +- Do not attempt to import a POM that is defined in a submodule of the current POM\. Attempting to do that will result in the build failing since it won't be able to locate the POM\. +- Never declare the POM importing a POM as the parent \(or grandparent, etc\) of the target POM\. There is no way to resolve the circularity and an exception will be thrown\. +- When referring to artifacts whose POMs have transitive dependencies, the project needs to specify versions of those artifacts as managed dependencies\. Not doing so results in a build failure since the artifact may not have a version specified\. \(This should be considered a best practice in any case as it keeps the versions of artifacts from changing from one build to the next\)\. + +Starting from Maven 4\.0, a new specific BOM packaging has been introduced\. It allows defining a BOMs which are not used as parent in a project leveraging the newer 4\.1\.0 model, while still providing full compatibility with Maven 3\.X clients and projects\. This BOM packaging is translated into a more usual POM packaging at installation / deployment time, leveraging the build/consumer POM feature from Maven 4\. This thus provides full compatibility with Maven 3\.x\. + +``` + + + + com.test + 1.0.0 + parent + + com.test + bom + 1.0.0 + bom + + 1.0.0 + 1.0.0 + + + + + com.test + project1 + ${project1Version} + + + com.test + project2 + ${project2Version} + + + + +``` + +## System Dependencies + +`Important note: This is deprecated.` + +Dependencies with the scope _system_ are always available and are not looked up in repository\. They are usually used to tell Maven about dependencies which are provided by the JDK or the VM\. Thus, system dependencies are especially useful for resolving dependencies on artifacts which are now provided by the JDK, but were available as separate downloads earlier\. Typical examples are the JDBC standard extensions or the Java Authentication and Authorization Service \(JAAS\)\. + +A simple example would be: + +``` + + + ... + + + javax.sql + jdbc-stdext + 2.0 + system + ${java.home}/lib/rt.jar + + + ... + +``` + +If your artifact is provided by the JDK's `tools.jar`, the system path would be defined as follows: + +``` + + ... + + + sun.jdk + tools + 1.5.0 + system + ${java.home}/../lib/tools.jar + + + ... + +``` + diff --git a/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md new file mode 100644 index 0000000000..8e28899608 --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md @@ -0,0 +1,231 @@ +--- +title: Optional Dependencies and Dependency Exclusions +author: + - Allan Ramirez +date: 2006-01-23 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +This section discusses optional dependencies and dependency exclusions\. This will help users to understand what they are and when and how to use them\. It also explains why exclusions are made on a per dependency basis instead of at the POM level\. + +## Optional Dependencies + +Optional dependencies are used when it's not possible \(for whatever reason\) to split a project into sub\-modules\. The idea is that some of the dependencies are only used for certain features in the project and will not be needed if that feature isn't used\. Ideally, such a feature would be split into a sub\-module that depends on the core functionality project\. This new subproject would have only non\-optional dependencies, since you'd need them all if you decided to use the subproject's functionality\. + +However, since the project cannot be split up \(again, for whatever reason\), these dependencies are declared optional\. If a user wants to use functionality related to an optional dependency, they have to redeclare that optional dependency in their own project\. This is not the clearest way to handle this situation, but both optional dependencies and dependency exclusions are stop\-gap solutions\. + +### Why use optional dependencies? + +Optional dependencies save space and memory\. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like\. + +### How do I use the optional tag? + +A dependency is declared optional by setting the `` element to true in its dependency declaration: + +``` + + + ... + + + + sample.ProjectA + Project-A + 1.0 + compile + true + + + +``` + +### How do optional dependencies work? + +``` + +Project-A -> Project-B +``` + +The diagram above says that Project\-A depends on Project\-B\. When A declares B as an optional dependency in its POM, this relationship remains unchanged\. It's just like a normal build where Project\-B will be added in Project\-A's classpath\. + +``` + +Project-X -> Project-A +``` + +When another project \(Project\-X\) declares Project\-A as a dependency in its POM, the optional nature of the dependency takes effect\. Project\-B is not included in the classpath of Project\-X\. You need to declare it directly in the POM of Project X for B to be included in X's classpath\. + +### Example + +Suppose there is a project named _X2_ that has similar functionality to _Hibernate_\. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle\. Each supported database requires an additional dependency on a driver jar\. All of these dependencies are needed at compile time to build X2\. However your project only uses one specific database and doesn't need drivers for the others\. X2 can declare these dependencies as optional, so that when your project declares X2 as a direct dependency in its POM, all the drivers supported by the X2 are not automatically included in your project's classpath\. Your project will have to include an explicit dependency on the specific driver for the one database it does use\. + +## Dependency Exclusions + +Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath\. For example, a certain older jar may have security issues or be incompatible with the Java version you're using\. To address this, Maven allows you to exclude specific dependencies\. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId\. When you build your project, that artifact will not be added to your project's classpath _by way of the dependency in which the exclusion was declared_\. + +### How to use dependency exclusions + +Add an `` element in the `` element by which the problematic jar is included\. + +``` + + + ... + + + sample.ProjectA + Project-A + 1.0 + compile + + + sample.ProjectB + Project-B + + + + + +``` + +### How dependency exclusion works and when to use it **\( as a last resort\! \)** + +``` + +Project-A + -> Project-B + -> Project-D + -> Project-E + -> Project-F + -> Project C +``` + +The diagram shows that Project\-A depends on both Project\-B and C\. Project\-B depends on Project\-D\. Project\-D depends on both Project\-E and F\. By default, Project A's classpath will include: + +``` +B, C, D, E, F +``` + +Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project\-D's dependencies are missing from the repository, and you don't need the functionality in Project\-B that depends on Project\-D anyway\. Project\-B's developers could have marked the dependency on Project\-D `true`: + +``` + + sample.ProjectD + ProjectD + 1.0-SNAPSHOT + true + +``` + +Unfortunately, they didn't\. As a last resort, you can exclude it on your own POM for Project\-A like this: + +``` + + + 4.0.0 + sample.ProjectA + Project-A + 1.0-SNAPSHOT + jar + ... + + + sample.ProjectB + Project-B + 1.0-SNAPSHOT + + + sample.ProjectD + Project-D + + + + + +``` + +If you deploy Project\-A to a repository, and Project\-X declares a normal dependency on Project\-A, will Project\-D still be excluded from the classpath? + +``` + +Project-X -> Project-A +``` + +The answer is **Yes**\. Project\-A has declared that it doesn't need Project\-D to run, so it won't be brought in as a transitive dependency of Project\-A\. + +Now, consider that Project\-X depends on Project\-Y, as in the diagram below: + +``` + +Project-X -> Project-Y + -> Project-B + -> Project-D + ... +``` + +Project\-Y also has a dependency on Project\-B, and it does need the features supported by Project\-D\. Therefore, it will NOT place an exclusion on Project\-D in its dependency list\. It may also supply an additional repository, from which it can resolve Project\-E\. In this case, it's important that Project\-D **is not** excluded globally, since it is a legitimate dependency of Project\-Y\. + +As another scenario, suppose the dependency you don't want is Project\-E instead of Project\-D\. How do you exclude it? See the diagram below: + +``` + +Project-A + -> Project-B + -> Project-D + -> Project-E + -> Project-F + -> Project C +``` + +Exclusions work on the entire dependency graph below the point where they are declared\. If you want to exclude Project\-E instead of Project\-D, simply change the exclusion to point at Project\-E, but you don't move the exclusion down to Project\-D\. You cannot change Project\-D's POM\. If you could, you would use optional dependencies instead of exclusions, or split Project\-D up into multiple subprojects, each with nothing but normal dependencies\. + +``` + + + 4.0.0 + sample.ProjectA + Project-A + 1.0-SNAPSHOT + jar + ... + + + sample.ProjectB + Project-B + 1.0-SNAPSHOT + + + sample.ProjectE + Project-E + + + + + +``` + +### Why exclusions are made on a per\-dependency basis, rather than at the POM level + +This is mainly to be sure the dependency graph is predictable, and to keep inheritance effects from excluding a dependency that should not be excluded\. If you get to the method of last resort and have to put in an exclusion, you should be absolutely certain which of your dependencies is bringing in that unwanted transitive dependency\. + +If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the [banned dependencies rule](/enforcer/enforcer\-rules/bannedDependencies\.html) can be configured to fail the build if a problematic dependency is found\. When the build fails, you'll need to add specific exclusions on each path the enforcer finds\. + diff --git a/content/markdown/guides/introduction/introduction-to-plugins.md b/content/markdown/guides/introduction/introduction-to-plugins.md new file mode 100644 index 0000000000..22fc951ef1 --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-plugins.md @@ -0,0 +1,51 @@ +--- +title: Introduction to Maven Plugin Development +author: + - John Casey +date: 2005-06-24 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to Maven Plugin Development + +Maven consists of a core engine which provides basic project\-processing capabilities and build\-process management, and a host of plugins which are used to execute the actual build tasks\. + +## What is a Plugin? + +"Maven" is really just a core framework for a collection of Maven Plugins\. In other words, plugins are where much of the real action is performed, plugins are used to: create jar files, create war files, compile code, unit test code, create project documentation, and on and on\. Almost any action that you can think of performing on a project is implemented as a Maven plugin\. + +Plugins are the central feature of Maven that allow for the reuse of common build logic across multiple projects\. They do this by executing an "action" \(i\.e\. creating a WAR file or compiling unit tests\) in the context of a project's description \- the Project Object Model \(POM\)\. Plugin behavior can be customized through a set of unique parameters which are exposed by a description of each plugin goal \(or Mojo\)\. + +One of the simplest plugins in Maven is the Clean Plugin\. The [Maven Clean plugin](\.\./\.\./plugins/maven\-clean\-plugin/) \(maven\-clean\-plugin\) is responsible for removing the target directory of a Maven project\. When you run "mvn clean", Maven executes the "clean" goal as defined in the Clean plug\-in, and the target directory is removed\. The Clean plugin [defines a parameter](\.\./\.\./plugins/maven\-clean\-plugin/clean\-mojo\.html) which can be used to customize plugin behavior, this parameter is called outputDirectory and it defaults to $\{project\.build\.directory\}\. + +## What is a Mojo \(_And Why the H\-\-\- is it Named 'Mojo'_\)? + +A Mojo is really just a **goal** in Maven, and plug\-ins consist of any number of goals \(Mojos\)\. Mojos can be defined as annotated Java classes or Beanshell script\. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting\. + +MOJO is a play on POJO \(Plain\-old\-Java\-object\), substituting "Maven" for "Plain"\. Mojo is also an interesting word \(see [definition](http://www\.answers\.com/mojo&r=67)\)\. From [Wikipedia](http://www\.wikipedia\.org), a "mojo" is defined as: "\.\.\.a small bag worn by a person under the clothes \(also known as a mojo hand\)\. Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc\." + +## What is the Build Lifecycle? \(Overview\) + +The build lifecycle is a series of common **stage**s through which all project builds naturally progress\. Plugin goals are bound to specific stages in the lifecycle\. + +# Resources + +1. [Plugin Development Center](/plugin\-developers/index\.html) +1. [Configuring plugins](\.\./mini/guide\-configuring\-plugins\.html) diff --git a/content/markdown/guides/introduction/introduction-to-profiles.md b/content/markdown/guides/introduction/introduction-to-profiles.md new file mode 100644 index 0000000000..aeb239f08f --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-profiles.md @@ -0,0 +1,638 @@ +--- +title: Introduction to build profiles +author: + - John Casey/Allan Ramirez +date: 2008-01-01 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to Build Profiles + +- [What are the different types of profile? Where is each defined?](What\_are\_the\_different\_types\_of\_profile\.3F\_Where\_is\_each\_defined\.3F) +- [Profile Inheritance](Profile\_Inheritance) +- [How can a profile be triggered? How does this vary according to the type of profile being used?](How\_can\_a\_profile\_be\_triggered\.3F\_How\_does\_this\_vary\_according\_to\_the\_type\_of\_profile\_being\_used\.3F) + - [Details on profile activation](Details\_on\_profile\_activation) + - [Explicit profile activation](Explicit\_profile\_activation) + - [Implicit profile activation](Implicit\_profile\_activation) + - [JDK](JDK) + - [OS](OS) + - [Property](Property) + - [Files](Files) + - [Multiple conditions](Multiple\_conditions) + - [Deactivating a profile](Deactivating\_a\_profile) +- [Which areas of a POM can be customized by each type of profile? Why?](Which\_areas\_of\_a\_POM\_can\_be\_customized\_by\_each\_type\_of\_profile\.3F\_Why\.3F) + - [Profiles in external files](Profiles\_in\_external\_files) + - [Profiles in POMs](Profiles\_in\_POMs) + - [POM elements outside <profiles>](POM\_elements\_outside\_\.3Cprofiles\.3E) +- [Profile Order](Profile\_Order) +- [Profile Pitfalls](Profile\_Pitfalls) + - [External Properties](External\_Properties) + - [Incomplete Specification of a Natural Profile Set](Incomplete\_Specification\_of\_a\_Natural\_Profile\_Set) +- [How can I tell which profiles are in effect during a build?](How\_can\_I\_tell\_which\_profiles\_are\_in\_effect\_during\_a\_build\.3F) +- [Naming Conventions](Naming\_Conventions) + +Apache Maven goes to great lengths to ensure that builds are portable\. Among other things, this means allowing build configuration inside the POM, avoiding **all** filesystem references \(in inheritance, dependencies, and other places\), and leaning much more heavily on the local repository to store the metadata needed to make this possible\. + +However, sometimes portability is not entirely possible\. Under certain conditions, plugins may need to be configured with local filesystem paths\. Under other circumstances, a slightly different dependency set will be required, and the project's artifact name may need to be adjusted slightly\. And at still other times, you may even need to include a whole plugin in the build lifecycle depending on the detected build environment\. + +To address these circumstances, Maven supports build profiles\. Profiles are specified using a subset of the elements available in the POM itself \(plus one extra section\), and are triggered in any of a variety of ways\. They modify the POM at build time, and are meant to be used in complementary sets to give equivalent\-but\-different parameters for a set of target environments \(providing, for example, the path of the appserver root in the development, testing, and production environments\)\. As such, profiles can easily lead to differing build results from different members of your team\. However, used properly, profiles can be used while still preserving project portability\. This will also minimize the use of `-f` option of maven which allows user to create another POM with different parameters or configuration to build which makes it more maintainable since it is running with one POM only\. + +## What are the different types of profile? Where is each defined? + +- Per Project + + \- Defined in the POM itself `(pom.xml)`\. + +- Per User + + \- Defined in the [ Maven\-settings](/ref/current/maven\-settings/settings\.html) `(%USER_HOME%/.m2/settings.xml)`\. + +- Global + + \- Defined in the [ global Maven\-settings](/ref/current/maven\-settings/settings\.html) `(${maven.home}/conf/settings.xml)`\. + +## Profile Inheritance + +The profiles are not inherited as other POM elements by child POMs\. Instead they are resolved very early by the [Maven Model Builder](/ref/current/maven\-model\-builder/) and only the effects of active profiles are inherited \(e\.g\. the plugins defined in the profile\)\. That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile \(even if it has the same id\)\. + +## How can a profile be triggered? How does this vary according to the type of profile being used? + +A profile can be activated in several ways: + +- Explicitly +- Implicitly + - Based on OS + - Based on system properties + - Based on presence of files + +Refer to the sections below for details\. + +### Details on profile activation + +#### Explicit profile activation + +Profiles can be explicitly specified using the `-P` command line flag\. + +This flag is followed by a comma\-delimited list of profile IDs to use\. The profile\(s\) specified in the option are activated in addition to any profiles which are activated by their activation configuration or the `` section in `settings.xml`\. From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved\. To prevent this, prefix the profile identifier with an `?`, marking it as optional: + +``` +mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3 +``` + +Profiles can be activated in the Maven settings, via the `` section\. This section takes a list of `` elements, each containing a profile\-id inside\. + +``` + + ... + + profile-1 + + ... + +``` + +Profiles listed in the `` tag would be activated by default every time a project use it\. + +Profiles can also be active by default using a configuration like the following in a POM: + +``` + + + profile-1 + + true + + ... + + +``` + +This profile will automatically be active for all builds unless another profile in the same POM is activated using one of the previously described methods\. All profiles that are active by default are automatically deactivated when a profile in the POM is activated on the command line or through its activation config\. + +#### Implicit profile activation + +Profiles can be automatically triggered based on the detected state of the build environment\. These triggers are specified via an `` section in the profile itself\. Currently, this detection is limited to JDK version matching, operating system matching or the presence/the value of a system property\. The implicit profile activation always only refers to the container profile \(and not to profiles in other modules with the same id\)\. Here are some examples\. + +##### JDK + +The following configuration will trigger the profile when the JDK's version _starts with_ "1\.4" \(eg\. "1\.4\.0\_08", "1\.4\.2\_07", "1\.4"\), in particular it _won't be active_ for **newer** versions like "1\.8" or "11": + +``` + + + + 1.4 + + ... + + +``` + +[ Ranges](/enforcer/enforcer\-rules/versionRanges\.html) can also be used\. Range values must start with either `[` or `(`\. Otherwise, the value is interpreted as a prefix\. The following honours versions 1\.3, 1\.4 and 1\.5\. + +``` + + + + [1.3,1.6) + + ... + + +``` + +_Note:_ an upper bound such as `,1.5]` is likely not to include most releases of 1\.5, since they will have an additional "patch" release such as `_05` that is not taken into consideration in the above range\. + +##### OS + +This next one will activate based on the detected operating system\. See the [Maven Enforcer Plugin](/enforcer/enforcer\-rules/requireOS\.html) for more details about OS values\. + +``` + + + + + Windows XP + Windows + x86 + 5.1.2600 + + + ... + + +``` + +The values are interpreted as Strings and are matched against the [Java System properties](https://docs\.oracle\.com/javase/tutorial/essential/environment/sysprop\.html) `os.name`, `os.arch`, `os.version` and the family being derived from those\. + +Each value can be prefixed with `!` to negate the matching\. The values match if they are \(not\) equal to the actual String value \(**case insensitive**\)\. All given OS conditions must match for the profile to be considered for activation\. + +Since [Maven 3\.9\.7](https://issues\.apache\.org/jira/browse/MNG\-5726) the value for `version` may be prefixed with `regex:`\. In that case [regular pattern matching](https://docs\.oracle\.com/javase/tutorial/essential/regex/) is applied for the version matching and applied against the **lower case** `os.version` value\. + +The actual OS values which need to match the given values are emitted when executing `mvn --version`\. + +##### Property + +The profile below will be activated when the system property "debug" is specified with any value: + +``` + + + + + debug + + + ... + + +``` + +The following profile will be activated when the system property "debug" is not defined at all: + +``` + + + + + !debug + + + ... + + +``` + +The following profile will be activated when the system property "debug" is not defined, or is defined with a value which is not "true"\. + +``` + + + + + debug + !true + + + ... + + +``` + +To activate this you would type one of those on the command line: + +``` +mvn groupId:artifactId:goal +mvn groupId:artifactId:goal -Ddebug=false +``` + +The next example will trigger the profile when the system property "environment" is specified with the value "test": + +``` + + + + + environment + test + + + ... + + +``` + +To activate this you would type this on the command line: + +``` +mvn groupId:artifactId:goal -Denvironment=test +``` + +Profiles in the POM can also be activated based on properties from active profiles from the `settings.xml`\. + +**Note**: Environment variables like `FOO` are available as properties of the form `env.FOO`\. Further note that environment variable names are normalized to all upper\-case on Windows\. + +Since Maven 3\.9\.0 one can also evaluate the POM's packaging value by referencing property `packaging`\. This is only useful where the profile activation is defined in a common parent POM which is reused among multiple Maven projects\. The next example will trigger the profile when a project with packaging `war` is built: + +``` + + + + + packaging + war + + + ... + + +``` + +##### Files + +This example will trigger the profile when the generated file `target/generated-sources/axistools/wsdl2java/org/apache/maven` is missing\. + +``` + + + + + target/generated-sources/axistools/wsdl2java/org/apache/maven + + + ... + + +``` + +The tags `` and `` can be interpolated\. Supported variables are system properties like `${user.home}` and environment variables like `${env.HOME}`\. Please note that properties and values defined in the POM itself are not available for interpolation here, e\.g\. the above example activator cannot use `${project.build.directory}` but needs to hard\-code the path `target`\. + +#### Multiple conditions + +Different implicit activation types can be combined in one profile\. The profile is then only active if all conditions are met \(since Maven 3\.2\.2, [MNG\-4565](https://issues\.apache\.org/jira/browse/MNG\-4565)\)\. Using the same type more than once in the same profile is not supported \([MNG\-5909](https://issues\.apache\.org/jira/browse/MNG\-5909), [MNG\-3328](https://issues\.apache\.org/jira/browse/MNG\-3328)\)\. + +### Deactivating a profile + +One or more profiles can be deactivated using the command line by prefixing their identifier with either the character '\!' or '\-' as shown below\. + +**Note** that `!` needs to be escaped with `\` or quoted in Bash, ZSH and other shells as it has [a special meaning](https://www\.gnu\.org/software/bash/manual/html\_node/Event\-Designators\.html)\. Also there is a known bug with command line option values starting with `-` \([CLI\-309](https://issues\.apache\.org/jira/browse/CLI\-309)\), therefore it is recommended to use it with the syntax `-P=-profilename`\. + +``` +mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3 +``` + +or + +``` +mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3 +``` + +This can be used to deactivate profiles marked as activeByDefault or profiles that would otherwise be activated through their activation config\. + +## Which areas of a POM can be customized by each type of profile? Why? + +Now that we've talked about where to specify profiles, and how to activate them, it will be useful to talk about _what_ you can specify in a profile\. As with the other aspects of profile configuration, this answer is not straightforward\. + +Depending on where you choose to configure your profile, you will have access to varying POM configuration options\. + +### Profiles in external files + +Profiles specified in external files \(i\.e in `settings.xml` or `profiles.xml`\) are not portable in the strictest sense\. Anything that seems to stand a high chance of changing the result of the build is restricted to the inline profiles in the POM\. Things like repository lists could simply be a proprietary repository of approved artifacts, and won't change the outcome of the build\. Therefore, you will only be able to modify the `` and `` sections, plus an extra `` section\. + +The `` section allows you to specify free\-form key\-value pairs which will be included in the interpolation process for the POM\. This allows you to specify a plugin configuration in the form of `${profile.provided.path}`\. + +### Profiles in POMs + +On the other hand, if your profiles can be reasonably specified _inside_ the POM, you have many more options\. The trade\-off, of course, is that you can only modify _that_ project and its sub\-modules\. Since these profiles are specified inline, and therefore have a better chance of preserving portability, it's reasonable to say you can add more information to them without the risk of that information being unavailable to other users\. + +Profiles specified in the POM can modify [the following POM elements](/ref/current/maven\-model/maven\.html): + +- `` +- `` +- `` +- `` +- `` \(not actually available in the main POM, but used behind the scenes\) +- `` +- `` +- `` +- `` +- `` +- a subset of the `` element, which consists of: + - `` + - `` + - `` + - `` + - `` + - `` + - `` + - `` +### POM elements outside <profiles> + +We don't allow modification of some POM elements outside of POM\-profiles because these runtime modifications will not be distributed when the POM is deployed to the repository system, making that person's build of that project completely unique from others\. While you can do this to some extent with the options given for external profiles, the danger is limited\. Another reason is that this POM info is sometimes being reused from the parent POM\. + +External files such as `settings.xml` and `profiles.xml` also do not support elements outside the POM\-profiles\. Let us take this scenario for elaboration\. When the effective POM is deployed to a remote repository, any person can pickup its info out of the repository and use it to build a Maven project directly\. Now, imagine that if we can set profiles in dependencies, which is very important to a build, or in any other elements outside POM\-profiles in `settings.xml` then most probably we cannot expect someone else to use that POM from the repository and be able to build it\. And we have to also think about how to share the `settings.xml` with others\. Note that too many files to configure are very confusing and very hard to maintain\. Bottom line is that since this is build data, it should be in the POM\. + +## Profile Order + +All profile elements in a POM from active profiles overwrite the global elements with the same name of the POM or extend those in case of collections\. In case multiple profiles are active in the same POM or external file, the ones which are defined **later** take precedence over the ones defined **earlier** \(independent of their profile id and activation order\)\. + +Example: + +``` + + ... + + + global-repo + ... + + + ... + + + profile-1 + + true + + + + profile-1-repo + ... + + + + + profile-2 + + true + + + + profile-2-repo + ... + + + + ... + + ... + +``` + +This leads to the repository list: `profile-2-repo, profile-1-repo, global-repo`\. + +## Profile Pitfalls + +We've already mentioned the fact that adding profiles to your build has the potential to break portability for your project\. We've even gone so far as to highlight circumstances where profiles are likely to break project portability\. However, it's worth reiterating those points as part of a more coherent discussion about some pitfalls to avoid when using profiles\. + +There are two main problem areas to keep in mind when using profiles\. First are external properties, usually used in plugin configurations\. These pose the risk of breaking portability in your project\. The other, more subtle area is the incomplete specification of a natural set of profiles\. + +### External Properties + +External property definition concerns any property value defined outside the `pom.xml` but not defined in a corresponding profile inside it\. The most obvious usage of properties in the POM is in plugin configuration\. While it is certainly possible to break project portability without properties, these critters can have subtle effects that cause builds to fail\. For example, specifying appserver paths in a profile that is specified in the `settings.xml` may cause your integration test plugin to fail when another user on the team attempts to build without a similar `settings.xml`\. Consider the following `pom.xml` snippet for a web application project: + +``` + + ... + + + + org.myco.plugins + spiffy-integrationTest-plugin + 1.0 + + ${appserver.home} + + + ... + + + ... + +``` + +Now, in your local `${user.home}/.m2/settings.xml`, you have: + +``` + + ... + + + appserverConfig + + /path/to/appserver + + + + + + appserverConfig + + ... + +``` + +When you build the **integration\-test** lifecycle phase, your integration tests pass, since the path you've provided allows the test plugin to install and test this web application\. + +_However_, when your colleague attempts to build to **integration\-test**, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter ``, or worse, that the value of that parameter \- literally `${appserver.home}` \- is invalid \(if it warns you at all\)\. + +Congratulations, your project is now non\-portable\. Inlining this profile in your `pom.xml` can help alleviate this, with the obvious drawback that each project hierarchy \(allowing for the effects of inheritance\) now have to specify this information\. Since Maven provides good support for project inheritance, it's possible to stick this sort of configuration in the `` section of a team\-level POM or similar, and simply inherit the paths\. + +Another, less attractive answer might be standardization of development environments\. However, this will tend to compromise the productivity gain that Maven is capable of providing\. + +### Incomplete Specification of a Natural Profile Set + +In addition to the above portability\-breaker, it's easy to fail to cover all cases with your profiles\. When you do this, you're usually leaving one of your target environments high and dry\. Let's take the example `pom.xml` snippet from above one more time: + +``` + + ... + + + + org.myco.plugins + spiffy-integrationTest-plugin + 1.0 + + ${appserver.home} + + + ... + + + ... + +``` + +Now, consider the following profile, which would be specified inline in the `pom.xml`: + +``` + + ... + + + appserverConfig-dev + + + env + dev + + + + /path/to/dev/appserver + + + + + appserverConfig-dev-2 + + + env + dev-2 + + + + /path/to/another/dev/appserver2 + + + + .. + +``` + +This profile looks quite similar to the one from the last example, with a few important exceptions: it's plainly geared toward a development environment, a new profile named `appserverConfig-dev-2` is added and it has an activation section that will trigger its inclusion when the system properties contain "env=dev" for a profile named `appserverConfig-dev` and "env=dev\-2" for a profile named `appserverConfig-dev-2`\. So, executing: + +``` +mvn -Denv=dev-2 integration-test +``` + +will result in a successful build, applying the properties given by profile named `appserverConfig-dev-2`\. And when we execute + +``` +mvn -Denv=dev integration-test +``` + +it will result in a successful build applying the properties given by the profile named `appserverConfig-dev`\. However, executing: + +``` +mvn -Denv=production integration-test +``` + +will not do a successful build\. Why? Because, the resulting non\-interpolated literal value of `${appserver.home}` will not be a valid path for deploying and testing your web application\. We haven't considered the case for the production environment when writing our profiles\. The "production" environment \(env=production\), along with "test" and possibly even "local" constitute a natural set of target environments for which we may want to build the integration\-test lifecycle phase\. The incomplete specification of this natural set means we have effectively limited our valid target environments to the development environment\. Your teammates \- and probably your manager \- will not see the humor in this\. When you construct profiles to handle cases such as these, be sure to address the entire set of target permutations\. + +As a quick aside, it's possible for user\-specific profiles to act in a similar way\. This means that profiles for handling different environments which are keyed to the user can act up when the team adds a new developer\. While I suppose this _could_ act as useful training for the newbie, it just wouldn't be nice to throw them to the wolves in this way\. Again, be sure to think of the _whole_ set of profiles\. + +## How can I tell which profiles are in effect during a build? + +Determining active profiles will help the user to know what particular profiles has been executed during a build\. We can use the [Maven Help Plugin](/plugins/maven\-help\-plugin/) to tell what profiles are in effect during a build\. + +``` + mvn help:active-profiles +``` + +Let us have some small samples that will help us to understand more on the _active\-profiles_ goal of that plugin\. + +From the last example of profiles in the `pom.xml`, you'll notice that there are two profiles named `appserverConfig-dev` and `appserverConfig-dev-2` which has been given different values for properties\. If we go ahead and execute: + +``` + mvn help:active-profiles -Denv=dev +``` + +The result will be a bulleted list of the id of the profile with an activation property of "env=dev" together with the source where it was declared\. See sample below\. + +``` +The following profiles are active: + + - appserverConfig-dev (source: pom) +``` + +Now if we have a profile declared in `settings.xml` \(refer to the sample of profile in `settings.xml`\) and that have been set to be an active profile and execute: + +``` + mvn help:active-profiles +``` + +The result should be something like this + +``` +The following profiles are active: + + - appserverConfig (source: settings.xml) +``` + +Even though we don't have an activation property, a profile has been listed as active\. Why? Like we mentioned before, a profile that has been set as an active profile in the `settings.xml` is automatically activated\. + +Now if we have something like a profile in the `settings.xml` that has been set as an active profile and also triggered a profile in the POM\. Which profile do you think will have an effect on the build? + +``` + mvn help:active-profiles -P appserverConfig-dev +``` + +This will list the activated profiles: + +``` +The following profiles are active: + + - appserverConfig-dev (source: pom) + - appserverConfig (source: settings.xml) +``` + +Even though it listed the two active profiles, we are not sure which one of them has been applied\. To see the effect on the build execute: + +``` + mvn help:effective-pom -P appserverConfig-dev +``` + +This will print the effective POM for this build configuration out to the console\. Take note that profiles in the `settings.xml` takes higher priority than profiles in the POM\. So the profile that has been applied here is `appserverConfig` not `appserverConfig-dev`\. + +If you want to redirect the output from the plugin to a file called `effective-pom.xml`, use the command\-line option `-Doutput=effective-pom.xml`\. + +## Naming Conventions + +By now you've noticed that profiles are a natural way of addressing the problem of different build configuration requirements for different target environments\. Above, we discussed the concept of a "natural set" of profiles to address this situation, and the importance of considering the whole set of profiles that will be required\. + +However, the question of how to organize and manage the evolution of that set is non\-trivial as well\. Just as a good developer strives to write self\-documenting code, it's important that your profile id's give a hint to their intended use\. One good way to do this is to use the common system property trigger as part of the name for the profile\. This might result in names like **env\-dev**, **env\-test**, and **env\-prod** for profiles that are triggered by the system property **env**\. Such a system leaves a highly intuitive hint on how to activate a build targeted at a particular environment\. Thus, to activate a build for the test environment, you need to activate **env\-test** by issuing: + +``` +mvn -Denv=test +``` + +The right command\-line option can be had by simply substituting "=" for "\-" in the profile id\. + diff --git a/content/markdown/guides/introduction/introduction-to-repositories.md b/content/markdown/guides/introduction/introduction-to-repositories.md new file mode 100644 index 0000000000..e643c159b0 --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-repositories.md @@ -0,0 +1,121 @@ +--- +title: Introduction to Repositories +author: + - Jason van Zyl + - Brian Fox +date: 2008-05-13 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to Repositories + +## Artifact Repositories + +A repository in Maven holds build artifacts and dependencies of varying types\. + +There are exactly two types of repositories: **local** and **remote**: + +1. the **local** repository is a directory on the computer where Maven runs\. It caches remote downloads and contains temporary build artifacts that you have not yet released\. +1. **remote** repositories refer to any other type of repository, accessed by a variety of protocols such as `file://` and `https://`\. These repositories might be a truly remote repository set up by a third party to provide their artifacts for downloading \(for example, [repo\.maven\.apache\.org](https://repo\.maven\.apache\.org/maven2/)\)\. Other "remote" repositories may be internal repositories set up on a file or HTTP server within your company, used to share private artifacts between development teams and for releases\. + +Local and remote repositories are structured the same way so that scripts can run on either side, or they can be synced for offline use\. The layout of the repositories is completely transparent to the Maven user, however\. + +## Using Repositories + +In general, you should not need to do anything with the local repository on a regular basis, except clean it out if you are short on disk space \(or erase it completely if you are willing to download everything again\)\. + +For the remote repositories, they are used for both downloading and uploading \(if you have the permission to do so\)\. + +### Downloading from a Remote Repository + +Downloading in Maven is triggered by a project declaring a dependency that is not present in the local repository \(or for a `SNAPSHOT`, when the remote repository contains one that is newer\)\. By default, Maven will download from the [central](https://repo\.maven\.apache\.org/maven2/) repository\. + +To override this, you need to specify a `mirror` as shown in [Using Mirrors for Repositories](\.\./mini/guide\-mirror\-settings\.html)\. + +You can set this in your `settings.xml` file to globally use a certain mirror\. However, it is common for a project to [customise the repository in its `pom.xml`](\.\./mini/guide\-multiple\-repositories\.html) and that your setting will take precedence\. If dependencies are not being found, check that you have not overridden the remote repository\. + +For more information on dependencies, see [Dependency Mechanism](\./introduction\-to\-dependency\-mechanism\.html)\. + +### Using Mirrors for the Central Repository + +There are [several official Central repositories](/repository/) geographically distributed\. You can make changes to your `settings.xml` file to use one or more mirrors\. Instructions for this can be found in the guide [Using Mirrors for Repositories](\.\./mini/guide\-mirror\-settings\.html)\. + +## Building Offline + +If you are temporarily disconnected from the internet and you need to build your projects offline, you can use the offline switch on the CLI: + +``` + mvn -o package +``` + +Many plugins honor the offline setting and do not perform any operations that connect to the internet\. Some examples are resolving Javadoc links and link checking the site\. + +## Uploading to a Remote Repository + +While this is possible for any type of remote repository, you must have the permission to do so\. To have someone upload to the Central Maven repository, see [Repository Center](\.\./\.\./repository/index\.html)\. + +## Internal Repositories + +When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies is not acceptable for security, speed or bandwidth reasons\. For that reason, it is desirable to set up an internal repository to house a copy of artifacts, and to publish private artifacts to\. + +Such an internal repository can be downloaded using HTTP or the file system \(with a `file://` URL\), and uploaded to using SCP, FTP, or a file copy\. + +As far as Maven is concerned, there is nothing special about this repository: it is another **remote repository** that contains artifacts to download to a user's local cache, and is a publish destination for artifact releases\. + +Additionally, you may want to share the repository server with your generated project sites\. For more information on creating and deploying sites, see [Creating a Site](\.\./mini/guide\-site\.html)\. + +## Setting up the Internal Repository + +To set up an internal repository just requires that you have a place to put it, and then copy required artifacts there using the same layout as in a remote repository such as [repo\.maven\.apache\.org](https://repo\.maven\.apache\.org/maven2/)\. + +It is _not_ recommended that you scrape or `rsync://` a full copy of central as there is a large amount of data there and doing so will get you banned\. You can use a program such as those described on the [Repository Management](\.\./\.\./repository\-management\.html) page to run your internal repository's server, download from the internet as required, and then hold the artifacts in your internal repository for faster downloading later\. + +The other options available are to manually download and vet releases, then copy them to the internal repository, or to have Maven download them for a user, and manually upload the vetted artifacts to the internal repository which is used for releases\. This step is the only one available for artifacts where the license forbids their distribution automatically, such as several J2EE JARs provided by Sun\. Refer to the [Guide to coping with SUN JARs](\.\./mini/guide\-coping\-with\-sun\-jars\.html) document for more information\. + +It should be noted that Maven intends to include enhanced support for such features in the future, including click through licenses on downloading, and verification of signatures\. + +## Using the Internal Repository + +Using the internal repository is quite simple\. Simply make a change to add a `repositories` element: + +``` + + + ... + + + my-internal-site + https://myserver/repo + + + ... + +``` + +If your internal repository requires authentication, the `id` element can be used in your [settings](\.\./\.\./settings\.html\#Servers) file to specify login information\. + +## Deploying to the Internal Repository + +One of the most important reasons to have one or more internal repositories is to be able to publish your own private releases\. + +To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, WebDAV, or the filesystem\. Connectivity is accomplished with the various [wagons](/wagon/wagon\-providers/index\.html)\. Some wagons may need to be added as [extension](/ref/current/maven\-model/maven\.html\#class\_extension) to your build\. + + + diff --git a/content/markdown/guides/introduction/introduction-to-the-lifecycle.md b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md new file mode 100644 index 0000000000..7a0085c114 --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md @@ -0,0 +1,312 @@ +--- +title: Introduction to the Build Lifecycle +author: + - Brett Porter +date: 2006-06-16 +2015-04-04 +--- + + + + + + + + + + + + + + + + +# 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 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 [POM](\./introduction\-to\-the\-pom\.html) 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 web site\. + +### 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 comprises of the following phases \(for a complete list of the lifecycle 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\. +- `verify` \- run any checks on results of integration tests to ensure quality criteria are met +- `install` \- install the package into the local repository, for use as a dependency in other projects locally +- `deploy` \- done in the build environment, copies the final package to the remote repository for sharing with other developers and projects\. + +These lifecycle phases \(plus the other lifecycle phases not shown here\) are executed sequentially to complete the `default` lifecycle\. Given the lifecycle 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 integration tests, install the verified package to the local repository, then deploy the installed package to a remote repository\. + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +### Usual Command Line Calls + +You should select the phase that matches your outcome\. If you want your jar, run `package`\. If you want to run the unit tests, run `test`\. + +If you are uncertain what you want, the preferred phase to call is + +``` +mvn verify +``` + +This command executes each default lifecycle phase in order \(`validate`, `compile`, `package`, etc\.\), before executing `verify`\. You only need to call the last build phase to be executed, in this case, `verify`\. In most cases the effect is the same as `package`\. However, in case there are integration tests, these will be executed as well\. And during the `verify` phase additional checks can be done, e\.g\. if your code is written according to predefined checkstyle rules\. + +In a build environment, use the following call to cleanly build and deploy artifacts into the shared repository\. + +``` +mvn clean deploy +``` + +The same command can be used in a multi\-module scenario \(i\.e\. a project with one or more subprojects\)\. Maven traverses into every subproject and executes `clean`, then executes `deploy` \(including all of the prior build phase steps\)\. + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +### 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 preceding 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 preceding 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\. + + + +Multiple goals bound to a phase are executed in the same order as they are declared in the POM\. Multiple instances of the same plugin are grouped to execute together\. + + + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +### Some Phases Are Not Usually Called From the Command Line + +The phases named with hyphenated\-words \(`pre-*`, `post-*`, or `process-*`\) are not usually directly called from the command line\. These phases sequence the build, producing intermediate results that are not useful outside the build\. In the case of invoking `integration-test`, the environment may be left in a hanging state\. + +Code coverage tools such as Jacoco and execution container plugins such as Tomcat, Cargo, and Docker bind goals to the `pre-integration-test` phase to prepare the integration test container environment\. These plugins also bind goals to the `post-integration-test` phase to collect coverage statistics or decommission the integration test container\. + +Failsafe and code coverage plugins bind goals to `integration-test` and `verify` phases\. The net result is test and coverage reports are available after the `verify` phase\. If `integration-test` were to be called from the command line, no reports are generated\. Worse is that the integration test container environment is left in a hanging state; the Tomcat webserver or Docker instance is left running, and Maven may not even terminate by itself\. + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +## 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 ``\. 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\. + +|Phase|plugin:goal for the `jar` packaging| +|---|---| +|`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](/ref/current/maven\-core/default\-bindings\.html); 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 `` section of your POM and specify `true` for that plugin\. One example of a plugin that requires this is the Plexus plugin, which provides a `plexus-application` and `plexus-service` packaging\. + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +### 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 `` 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 `` section of ``: + +``` + + org.codehaus.modello + modello-maven-plugin + 1.8.1 + + + + + src/main/mdo/maven.mdo + + 4.0.0 + + + java + + + + +``` + +You might be wondering why that `` 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: + +``` + + com.mycompany.example + display-maven-plugin + 1.0 + + + process-test-resources + + time + + + + +``` + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +## Lifecycle Reference + +The following lists all build phases of the `default`, `clean` and `site` lifecycles, which are executed in the order given up to the point of the one specified\. + +### Clean Lifecycle + +|Phase|Description| +|---|---| +|`pre-clean`|execute processes needed prior to the actual project cleaning| +|`clean`|remove all files generated by the previous build| +|`post-clean`|execute processes needed to finalize the project cleaning| +### Default Lifecycle + +|Phase|Description| +|---|---| +|`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\.| +|`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\.| +|`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 + +|Phase|Description| +|---|---| +|`pre-site`|execute processes needed prior to the actual project site generation| +|`site`|generate the project's site documentation| +|`post-site`|execute processes needed to finalize the site generation, and to prepare for site deployment| +|`site-deploy`|deploy the generated site documentation to the specified web server| + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + +## 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 + +|Phase|plugin:goal| +|---|---| +|`clean`|`clean:clean`| +### Default Lifecycle Bindings \- Packaging `ejb` / `ejb3` / `jar` / `par` / `rar` / `war` + +|Phase|plugin:goal| +|---|---| +|`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` + +|Phase|plugin:goal| +|---|---| +|`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` + +|Phase|plugin:goal| +|---|---| +|`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` + +|Phase|plugin:goal| +|---|---| +|`package`|| +|`install`|`install:install`| +|`deploy`|`deploy:deploy`| +### Site Lifecycle Bindings + +|Phase|plugin:goal| +|---|---| +|`site`|`site:site`| +|`site-deploy`|`site:deploy`| +### References + +The full Maven lifecycle is defined by the `components.xml` file in the `maven-core` module, with [associated documentation](/ref/current/maven\-core/lifecycles\.html) for reference\. + +Default lifecycle bindings are defined in a separate [`default-bindings.xml`](https://github\.com/apache/maven/blob/master/maven\-core/src/main/resources/META\-INF/plexus/default\-bindings\.xml) descriptor\. + +See [Lifecycles Reference](/ref/current/maven\-core/lifecycles\.html) and [Plugin Bindings for default Lifecycle Reference](/ref/current/maven\-core/default\-bindings\.html) for latest documentation taken directly from source code\. + +_[\[top\]](\./introduction\-to\-the\-lifecycle\.html)\._ + diff --git a/content/markdown/guides/introduction/introduction-to-the-pom.md b/content/markdown/guides/introduction/introduction-to-the-pom.md new file mode 100644 index 0000000000..4c797357f1 --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-the-pom.md @@ -0,0 +1,484 @@ +--- +title: Introduction to the POM +author: + - Jason van Zyl + - Franz Allan Valencia See + - Brett Porter +date: 2009-02-04 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to the POM + +- [What is a POM](\./introduction\-to\-the\-pom\.html\#What\_is\_a\_POM)? +- [Super POM](\./introduction\-to\-the\-pom\.html\#Super\_POM) +- [Minimal POM](\./introduction\-to\-the\-pom\.html\#Minimal\_POM) +- [Project Inheritance](\./introduction\-to\-the\-pom\.html\#Project\_Inheritance) + - [Example 1](\./introduction\-to\-the\-pom\.html\#Example\_1) + - [Example 2](\./introduction\-to\-the\-pom\.html\#Example\_2) +- [Project Aggregation](\./introduction\-to\-the\-pom\.html\#Project\_Aggregation) + - [Example 3](\./introduction\-to\-the\-pom\.html\#Example\_3) + - [Example 4](\./introduction\-to\-the\-pom\.html\#Example\_4) +- [Project Inheritance vs Project Aggregation](\./introduction\-to\-the\-pom\.html\#Project\_Inheritance\_vs\_Project\_Aggregation) + - [Example 5](\./introduction\-to\-the\-pom\.html\#Example\_5) +- [Project Interpolation and Variables](\./introduction\-to\-the\-pom\.html\#Project\_Interpolation) + - [Available Variables](\./introduction\-to\-the\-pom\.html\#Available\_Variables) +## What is a POM? + +A Project Object Model or POM is the fundamental unit of work in Maven\. It is an XML file that contains information about the project and configuration details used by Maven to build the project\. It contains default values for most projects\. Examples for this is the build directory, which is `target`; the source directory, which is `src/main/java`; the test source directory, which is `src/test/java`; and so on\. When executing a task or goal, Maven looks for the POM in the current directory\. It reads the POM, gets the needed configuration information, then executes the goal\. + +Some of the configuration that can be specified in the POM are the project dependencies, the plugins or goals that can be executed, the build profiles, and so on\. Other information such as the project version, description, developers, mailing lists and such can also be specified\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +## Super POM + +The Super POM is Maven's default POM\. All POMs extend the Super POM unless explicitly set, meaning the configuration specified in the Super POM is inherited by the POMs you created for your projects\. + +You can see the [Super POM for the latest Maven 3 release](/maven\-model\-builder/super\-pom\.html) in Maven Core reference documentation\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +## Minimal POM + +The minimum requirement for a POM are the following: + +- `project` root +- `modelVersion` \- should be set to 4\.0\.0 +- `groupId` \- the id of the project's group\. +- `artifactId` \- the id of the artifact \(project\) +- `version` \- the version of the artifact under the specified group + +Here's an example: + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + +``` + +A POM requires that its groupId, artifactId, and version be configured\. These three values form the project's fully qualified artifact name\. This is in the form of <groupId>:<artifactId>:<version>\. As for the example above, its fully qualified artifact name is "com\.mycompany\.app:my\-app:1"\. + +Also, as mentioned in the [first section](What\_is\_a\_POM), if the configuration details are not specified, Maven will use their defaults\. One of these default values is the packaging type\. Every Maven project has a packaging type\. If it is not specified in the POM, then the default value "jar" would be used\. + +Furthermore, you can see that in the minimal POM the _repositories_ were not specified\. If you build your project using the minimal POM, it would inherit the _repositories_ configuration in the Super POM\. Therefore when Maven sees the dependencies in the minimal POM, it would know that these dependencies will be downloaded from `https://repo.maven.apache.org/maven2` which was specified in the Super POM\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +## Project Inheritance + +Elements in the POM that are merged are the following: + +- dependencies +- developers and contributors +- plugin lists \(including reports\) +- plugin executions with matching ids +- plugin configuration +- resources + +The Super POM is one example of project inheritance, however you can also introduce your own parent POMs by specifying the parent element in the POM, as demonstrated in the following examples\. + +### Example 1 + +#### The Scenario + +As an example, let us reuse our previous artifact, com\.mycompany\.app:my\-app:1\. And let us introduce another artifact, com\.mycompany\.app:my\-module:1\. + +``` + + 4.0.0 + + com.mycompany.app + my-module + 1 + +``` + +And let us specify their directory structure as the following: + +``` +. + |-- my-module + | `-- pom.xml + `-- pom.xml +``` + +**Note:** `my-module/pom.xml` is the POM of com\.mycompany\.app:my\-module:1 while `pom.xml` is the POM of com\.mycompany\.app:my\-app:1 + +#### The Solution + +Now, if we were to turn com\.mycompany\.app:my\-app:1 into a parent artifact of com\.mycompany\.app:my\-module:1,we will have to modify com\.mycompany\.app:my\-module:1's POM to the following configuration: + +**com\.mycompany\.app:my\-module:1's POM** + +``` + + 4.0.0 + + + com.mycompany.app + my-app + 1 + + + com.mycompany.app + my-module + 1 + +``` + +Notice that we now have an added section, the parent section\. This section allows us to specify which artifact is the parent of our POM\. And we do so by specifying the fully qualified artifact name of the parent POM\. With this setup, our module can now inherit some of the properties of our parent POM\. + +Alternatively, if you want the groupId or the version of your modules to be the same as their parents, you can remove the groupId or the version identity of your module in its POM\. + +``` + + 4.0.0 + + + com.mycompany.app + my-app + 1 + + + my-module + +``` + +This allows the module to inherit the groupId or the version of its parent POM\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +### Example 2 + +#### The Scenario + +However, that would work if the parent project was already installed in our local repository or was in that specific directory structure \(parent `pom.xml` is one directory higher than that of the module's `pom.xml`\)\. + +But what if the parent is not yet installed and if the directory structure is as in the following example? + +``` +. + |-- my-module + | `-- pom.xml + `-- parent + `-- pom.xml +``` + +#### The Solution + +To address this directory structure \(or any other directory structure\), we would have to add the `` element to our parent section\. + +``` + + 4.0.0 + + + com.mycompany.app + my-app + 1 + ../parent/pom.xml + + + my-module + +``` + +As the name suggests, it's the relative path from the module's `pom.xml` to the parent's `pom.xml`\. + +## Project Aggregation + +Project Aggregation is similar to [Project Inheritance](Project\_Inheritance)\. But instead of specifying the parent POM from the module, it specifies the modules from the parent POM\. By doing so, the parent project now knows its modules, and if a Maven command is invoked against the parent project, that Maven command will then be executed to the parent's modules as well\. To do Project Aggregation, you must do the following: + +- Change the parent POMs packaging to the value "pom"\. +- Specify in the parent POM the directories of its modules \(children POMs\)\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +### Example 3 + +#### The Scenario + +Given the previous original artifact POMs and directory structure: + +**com\.mycompany\.app:my\-app:1's POM** + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + +``` + +**com\.mycompany\.app:my\-module:1's POM** + +``` + + 4.0.0 + + com.mycompany.app + my-module + 1 + +``` + +**directory structure** + +``` +. + |-- my-module + | `-- pom.xml + `-- pom.xml +``` + +#### The Solution + +If we are to aggregate my\-module into my\-app, we would only have to modify my\-app\. + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + pom + + + my-module + + +``` + +In the revised com\.mycompany\.app:my\-app:1, the packaging section and the modules sections were added\. For the packaging, its value was set to "pom", and for the modules section, we have the element `my-module`\. The value of `` is the relative path from the com\.mycompany\.app:my\-app:1 to com\.mycompany\.app:my\-module:1's POM \(_by practice, we use the module's artifactId as the module directory's name_\)\. + +Now, whenever a Maven command processes com\.mycompany\.app:my\-app:1, that same Maven command would be ran against com\.mycompany\.app:my\-module:1 as well\. Furthermore, some commands \(goals specifically\) handle project aggregation differently\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +### Example 4 + +#### The Scenario + +But what if we change the directory structure to the following: + +``` +. + |-- my-module + | `-- pom.xml + `-- parent + `-- pom.xml +``` + +How would the parent POM specify its modules? + +#### The Solution + +The answer? \- the same way as Example 3, by specifying the path to the module\. + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + pom + + + ../my-module + + +``` + +## Project Inheritance vs Project Aggregation + +If you have several Maven projects, and they all have similar configurations, you can refactor your projects by pulling out those similar configurations and making a parent project\. Thus, all you have to do is to let your Maven projects inherit that parent project, and those configurations would then be applied to all of them\. + +And if you have a group of projects that are built or processed together, you can create a parent project and have that parent project declare those projects as its modules\. By doing so, you'd only have to build the parent and the rest will follow\. + +But of course, you can have both Project Inheritance and Project Aggregation\. Meaning, you can have your modules specify a parent project, and at the same time, have that parent project specify those Maven projects as its modules\. You'd just have to apply all three rules: + +- Specify in every child POM who their parent POM is\. +- Change the parent POMs packaging to the value "pom" \. +- Specify in the parent POM the directories of its modules \(children POMs\) + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +### Example 5 + +#### The Scenario + +Given the previous original artifact POMs again, + +**com\.mycompany\.app:my\-app:1's POM** + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + +``` + +**com\.mycompany\.app:my\-module:1's POM** + +``` + + 4.0.0 + + com.mycompany.app + my-module + 1 + +``` + +and this **directory structure** + +``` +. + |-- my-module + | `-- pom.xml + `-- parent + `-- pom.xml +``` + +#### The Solution + +To do both project inheritance and aggregation, you only have to apply all three rules\. + +**com\.mycompany\.app:my\-app:1's POM** + +``` + + 4.0.0 + + com.mycompany.app + my-app + 1 + pom + + + ../my-module + + +``` + +**com\.mycompany\.app:my\-module:1's POM** + +``` + + 4.0.0 + + + com.mycompany.app + my-app + 1 + ../parent/pom.xml + + + my-module + +``` + +**NOTE:** Profile inheritance the same inheritance strategy as used for the POM itself\. + +[\[top\]](\./introduction\-to\-the\-pom\.html) + +## Project Interpolation and Variables + +One of the practices that Maven encourages is _don't repeat yourself_\. However, there are circumstances where you will need to use the same value in several different locations\. To assist in ensuring the value is only specified once, Maven allows you to use both your own and pre\-defined variables in the POM\. + +For example, to access the `project.version` variable, you would reference it like so: + +``` + ${project.version} +``` + +One factor to note is that these variables are processed _after_ inheritance as outlined above\. This means that if a parent project uses a variable, then its definition in the child, not the parent, will be the one eventually used\. + +### Available Variables + +#### Project Model Variables + +Any field of the model that is a single value element can be referenced as a variable\. For example, `${project.groupId}`, `${project.version}`, `${project.build.sourceDirectory}` and so on\. Refer to the POM reference to see a full list of properties\. + +These variables are all referenced by the prefix "`project.`"\. You may also see references with `pom.` as the prefix, or the prefix omitted entirely \- these forms are now deprecated and should not be used\. + +#### Special Variables + +| | | +|---|---| +|`project.basedir`|The directory that the current project resides in\.| +|`project.baseUri`|The directory that the current project resides in, represented as an URI\. _Since Maven 2\.1\.0_| +|`maven.build.timestamp`|The timestamp that denotes the start of the build \(UTC\)\. _Since Maven 2\.1\.0\-M1_| + +The format of the build timestamp can be customized by declaring the property `maven.build.timestamp.format` as shown in the example below: + +``` + + ... + + yyyy-MM-dd'T'HH:mm:ss'Z' + + ... + +``` + +The format pattern has to comply with the rules given in the API documentation for [SimpleDateFormat](https://docs\.oracle\.com/javase/7/docs/api/java/text/SimpleDateFormat\.html)\. If the property is not present, the format defaults to the value already given in the example\. + +#### Properties + +You are also able to reference any properties defined in the project as a variable\. Consider the following example: + +``` + + ... + + 3.0 + + + + + org.apache.maven + maven-artifact + ${mavenVersion} + + + org.apache.maven + maven-core + ${mavenVersion} + + + ... + +``` + +[\[top\]](\./introduction\-to\-the\-pom\.html) + diff --git a/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md b/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md new file mode 100644 index 0000000000..7abcf96cac --- /dev/null +++ b/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md @@ -0,0 +1,59 @@ +--- +title: Introduction to the Standard Directory Layout +author: + - Jason van Zyl +date: 2014-03-09 +--- + + + + + + + + + + + + + + + + + + + +# Introduction to the Standard Directory Layout + +Having a common directory layout allows users familiar with one Maven project to immediately feel at home in another Maven project\. The advantages are analogous to adopting a site\-wide look\-and\-feel\. + +The next section documents the directory layout expected by Maven and the directory layout created by Maven\. Try to conform to this structure as much as possible\. However, if you can't, these settings can be overridden via the project descriptor\. + +| | | +|---|---| +|`src/main/java`|Application/Library sources| +|`src/main/resources`|Application/Library resources| +|`src/main/filters`|Resource filter files| +|`src/main/webapp`|Web application sources| +|`src/test/java`|Test sources| +|`src/test/resources`|Test resources| +|`src/test/filters`|Test resource filter files| +|`src/it`|Integration Tests \(primarily for plugins\)| +|`src/assembly`|Assembly descriptors| +|`src/site`|Site| +|`LICENSE.txt`|Project's license| +|`NOTICE.txt`|Notices and attributions required by libraries that the project depends on| +|`README.txt`|Project's readme| + +At the top level, files descriptive of the project: a `pom.xml` file\. In addition, there are textual documents meant for the user to be able to read immediately on receiving the source: `README.txt`, `LICENSE.txt`, etc\. + +There are just two subdirectories of this structure: `src` and `target`\. The only other directories that would be expected here are metadata like `CVS`, `.git` or `.svn`, and any subprojects in a multiproject build \(each of which would be laid out as above\)\. + +The `target` directory is used to house all output of the build\. + +The `src` directory contains all of the source material for building the project, its site and so on\. It contains a subdirectory for each type: `main` for the main build artifact, `test` for the unit test code and resources, `site` and so on\. + +Within artifact producing source directories \(ie\. `main` and `test`\), there is one directory for the language `java` \(under which the normal package hierarchy exists\), and one for `resources` \(the structure which is copied to the target classpath given the default resource definition\)\. + +If there are other contributing sources to the artifact build, they would be under other subdirectories\. For example `src/main/antlr` would contain Antlr grammar definition files\. + diff --git a/content/markdown/guides/mini/guide-3rd-party-jars-local.md b/content/markdown/guides/mini/guide-3rd-party-jars-local.md new file mode 100644 index 0000000000..6f62ae2f01 --- /dev/null +++ b/content/markdown/guides/mini/guide-3rd-party-jars-local.md @@ -0,0 +1,50 @@ +--- +title: Guide to installing 3rd party JARs +author: + - Jason van Zyl + - Robert Scholte +date: 2013-07-13 +--- + + + + + + + + + + + + + + + + + + + +# Guide to installing 3rd party JARs + +Occasionally, you will have 3rd party JARs that you need to put in your local repository for use in your builds, since they don't exist in any public repository like [Maven Central](https://search\.maven\.org)\. The JARs must be placed in the local repository in the correct place in order for it to be correctly picked up by Apache Maven\. + +To make this easier, and less error prone, we have provided an `install-file` goal in the [maven\-install\-plugin](/plugins/maven\-install\-plugin/) which should make this relatively painless\. + +To install a JAR in the local repository use the following command: + +``` +mvn install:install-file -Dfile= -DgroupId= -DartifactId= -Dversion= -Dpackaging= +``` + +If there's a pom\-file as well, you can install it with the following command: + +``` +mvn install:install-file -Dfile= -DpomFile= +``` + +With version 2\.5 of the maven\-install\-plugin, it can get even simpler: if the JAR was built by Apache Maven, it'll contain a pom\.xml in a subdirectory of the META\-INF/ directory, which will be read by default\. In that case, all you need to do is: + +``` +mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile= +``` + diff --git a/content/markdown/guides/mini/guide-3rd-party-jars-remote.md b/content/markdown/guides/mini/guide-3rd-party-jars-remote.md new file mode 100644 index 0000000000..4542e78d78 --- /dev/null +++ b/content/markdown/guides/mini/guide-3rd-party-jars-remote.md @@ -0,0 +1,73 @@ +--- +title: Guide to deploying 3rd party JARs to remote repository +author: + - Allan Ramirez +date: 2006-02-22 +--- + + + + + + + + + + + + + + + + + + + +# Guide to deploying 3rd party JARs to remote repository + +Same concept of the [install:install\-file](\./guide\-3rd\-party\-jars\-local\.html) goal of the maven\-install\-plugin where the 3rd party JAR is installed in the local repository\. But this time instead to local repository the JAR will be install both in the local and remote repository\. + +To deploy a 3rd party JAR use the deploy:deploy\-file goal under maven\-deploy\-plugin\. + +First, the wagon\-provider\(wagon\-ftp, wagon\-file, etc\.\.\) must be placed to your `${maven.home}/lib`\. + +Then execute the command: + +``` +mvn deploy:deploy-file -DgroupId= \ + -DartifactId= \ + -Dversion= \ + -Dpackaging= \ + -Dfile= \ + -DrepositoryId= \ + -Durl= +``` + +## Deploying a 3rd party JAR with a generic POM + +By default, deploy:deploy\-file generates a generic POM\(\.pom\) to be deploy together with the 3rd party JAR\. To disable this feature we should set the `generatePOM` argument to false\. + +``` +-DgeneratePom=false +``` + +## Deploying a 3rd party JAR with a customized POM + +If a POM is already existing for the 3rd Party JAR and you want to deploy it together with the JAR we should use the `pomFile` argument of the deploy\-file goal\. See sample below\. + +``` +mvn deploy:deploy-file -DpomFile= \ + -Dfile= \ + -DrepositoryId= \ + -Durl= +``` + +Note that `groupId`, `artifactId`, `version` and `packaging` arguments are not included here because deploy\-file goal will get these information from the given POM\. + +## Deploying Source Jars + + + + +To deploy a 3rd party source jar, packaging should be set to `java-source`, and generatePom should be set to `false`\. + diff --git a/content/markdown/guides/mini/guide-archive-configuration.md b/content/markdown/guides/mini/guide-archive-configuration.md new file mode 100644 index 0000000000..19c446cb1f --- /dev/null +++ b/content/markdown/guides/mini/guide-archive-configuration.md @@ -0,0 +1,61 @@ +--- +title: Guide to Configuring Archive Plugins +author: + - Brett Porter +date: 2006-06-21 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Configuring Archive Plugins + +Many Java archive generating plugins accept the `archive` configuration element to customize the generation of the archive\. In the standard Maven Plugins, this includes the `jar`, `war`, `ejb`, `ear` and `assembly` plugins\. + +## Disabling Maven Meta Information + +By default, Maven generated archives include the `META-INF/maven` directory, which contains the `pom.xml` file used to build the archive, and a `pom.properties` file that includes some basic properties in a small, easier to read format\. + +To disable the generation of these files, include the following configuration for your plugin \(in this example, the WAR plugin is used\): + +``` + + ... + + + + org.apache.maven.plugins + maven-war-plugin + 2.6 + + + false + + + + + + ... + +``` + + +## Configuring the Manifest + +The archive configuration also accepts manifest configuration\. See [Guide to Working with Manifests](\./guide\-manifest\.html) for more information\. + diff --git a/content/apt/guides/mini/guide-assemblies.apt b/content/markdown/guides/mini/guide-assemblies.md similarity index 61% rename from content/apt/guides/mini/guide-assemblies.apt rename to content/markdown/guides/mini/guide-assemblies.md index f35ba58713..28f49fb893 100644 --- a/content/apt/guides/mini/guide-assemblies.apt +++ b/content/markdown/guides/mini/guide-assemblies.md @@ -1,38 +1,33 @@ - ------ - Guide to Creating Assemblies - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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 - -Guide to creating assemblies - - The assembly mechanism in Maven provides an easy way to create distributions using a assembly descriptor - and dependency information found in you POM. In order to use the assembly plug-in you need to configure the - assembly plug-in in your POM and it might look like the following: - -+----+ +--- +title: Guide to Creating Assemblies +author: + - Jason van Zyl +date: 2005-10-12 +--- + + + + + + + + + + + + + + + + + + + +# Guide to creating assemblies + +The assembly mechanism in Maven provides an easy way to create distributions using a assembly descriptor and dependency information found in you POM\. In order to use the assembly plug\-in you need to configure the assembly plug\-in in your POM and it might look like the following: + +``` maven @@ -68,18 +63,15 @@ Guide to creating assemblies ... -+----+ +``` - You'll notice that the assembly descriptor is located in <<<$\{project.basedir\}/src/assembly>>> which is the - {{{../introduction/introduction-to-the-standard-directory-layout.html}standard}} location for assembly - descriptors. +You'll notice that the assembly descriptor is located in `${project.basedir}/src/assembly` which is the [standard](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html) location for assembly descriptors\. -* Creating a binary assembly +## Creating a binary assembly - This is the most typical usage of the assembly plugin where you are creating a distribution for standard - use. +This is the most typical usage of the assembly plugin where you are creating a distribution for standard use\. -+----+ +``` bin @@ -111,16 +103,13 @@ Guide to creating assemblies -+----+ +``` - You can use a manually defined assembly descriptor as mentioned before but it is simpler to use the - {{{/plugins/maven-assembly-plugin/descriptor-refs.html#bin}pre-defined assembly descriptor bin}} - in such cases. +You can use a manually defined assembly descriptor as mentioned before but it is simpler to use the [pre\-defined assembly descriptor bin](/plugins/maven\-assembly\-plugin/descriptor\-refs\.html\#bin) in such cases\. - How to use such pre-defined assembly descriptors is described in the - {{{/plugins/maven-assembly-plugin/usage.html#Configuration}documentation of maven-assembly-plugin}}. +How to use such pre\-defined assembly descriptors is described in the [documentation of maven\-assembly\-plugin](/plugins/maven\-assembly\-plugin/usage\.html\#Configuration)\. -+----+ +``` src @@ -188,11 +174,11 @@ Guide to creating assemblies -+----+ +``` - You can now create the defined distribution packages via command line like this: +You can now create the defined distribution packages via command line like this: ------- +``` mvn package ------- +``` diff --git a/content/apt/guides/mini/guide-attached-tests.apt b/content/markdown/guides/mini/guide-attached-tests.md similarity index 50% rename from content/apt/guides/mini/guide-attached-tests.apt rename to content/markdown/guides/mini/guide-attached-tests.md index 5af57d4885..369c53e9a4 100644 --- a/content/apt/guides/mini/guide-attached-tests.apt +++ b/content/markdown/guides/mini/guide-attached-tests.md @@ -1,39 +1,33 @@ - ------ - Guide to using attached tests - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ +--- +title: Guide to using attached tests +author: + - Jason van Zyl +date: 2005-10-12 +--- -~~ 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. + + + + + + + + + + + + + + + + + + +# Guide to using attached tests -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html +You can reuse the tests that you have created for one project in another\. For example, suppose `foo-core` contains test code in the `${project.basedir}/src/test/java`\. To package up those compiled tests in a JAR and deploy them for general reuse, configure the `maven-jar-plugin` as follows: -Guide to using attached tests - - You can reuse the tests that you have created for one project in another. For example, suppose - <<>> contains test code in the <<<$\{project.basedir\}/src/test/java>>>. To package - up those compiled tests in a JAR and deploy them for general reuse, configure the - <<>> as follows: - -+----+ +``` @@ -53,15 +47,13 @@ Guide to using attached tests +``` -+----+ +The attached test JAR can be installed and deployed like any other Maven artifact\. - The attached test JAR can be installed and deployed like any other Maven artifact. +To use the attached test JAR, specify a dependency on the main artifact with a specified type of `test-jar` and the `classifier`\. - To use the attached test JAR, specify a dependency on the main - artifact with a specified type of <<>> and the <<>>. - -+----+ +``` ... @@ -105,6 +97,5 @@ Guide to using attached tests ... - -+----+ +``` diff --git a/content/markdown/guides/mini/guide-bash-m2-completion.md b/content/markdown/guides/mini/guide-bash-m2-completion.md new file mode 100644 index 0000000000..0909423ac5 --- /dev/null +++ b/content/markdown/guides/mini/guide-bash-m2-completion.md @@ -0,0 +1,31 @@ +--- +title: Guide to Maven auto completion using BASH +author: + - Trygve Laugstol + - Jason van Zyl + - Karl Heinz Marbaise +date: 2016-01-24 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Maven auto completion using BASH + +If you like having bash completion which i can recommend if you are working with Maven on command line i would suggest to install the following [Maven Bash Auto Completion](https://github\.com/juven/maven\-bash\-completion) to fullfil you needs\. + diff --git a/content/markdown/guides/mini/guide-building-for-different-environments.md b/content/markdown/guides/mini/guide-building-for-different-environments.md new file mode 100644 index 0000000000..ab6c0311ce --- /dev/null +++ b/content/markdown/guides/mini/guide-building-for-different-environments.md @@ -0,0 +1,125 @@ +--- +title: Building For Different Environments +author: + - Trygve Laugstøl +date: 2006-01-01 +--- + + + + + + + + + + + + + + + + + + + +# Building For Different Environments + +Building the same artifact for different environments has always been an annoyance\. You have multiple environments, for instance test and production servers or, maybe a set of servers that run the same application with different configurations\. In this guide I'll explain how you can use profiles to build and package artifacts configured for specific environments\. See [Introduction to Build Profiles](\.\./introduction/introduction\-to\-profiles\.html) for a more in\-depth explanation of the profile concept\. + +Note: + +- This guide assume that you have basic Maven knowledge\. +- It will show a way to configure Maven to solve simple configuration set\-ups only\. By simple configuration set\-up I mean cases where you only have a single file or a small set of files that vary for each environment\. There are other and better ways to handle two and many\-dimensional configuration issues\. + + This example assume the use of the [Standard Directory Layout](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html)\. + + ``` + pom.xml + src/ + main/ + java/ + resources/ + test/ + java/ + ``` + +Under `src/main/resources` there are three files: + +- `environment.properties` \- This is the default configuration and will be packaged in the artifact by default\. +- `environment.test.properties` \- This is the variant for the test environment\. +- `environment.prod.properties` \- This is basically the same as the test variant and will be used in the production environment\. + + In the project descriptor, you need to configure the different profiles\. Only the test profile is showed here\. + + ``` + + + test + + + + maven-antrun-plugin + + + test + + run + + + + + + + + + + + + maven-surefire-plugin + + true + + + + maven-jar-plugin + + + package + + jar + + + test + + + + + + + + + .. Other profiles go here .. + + + ``` + + Three things are configured in this snippet: + + 1. It configures the antrun plugin to execute the run goal in the test phase where it will copy the `environment.test.properties` file to `environment.properties`\. + 1. It will configure the test plugin to skip all tests when building the test and production artifacts\. This is useful as you probably don't want to run tests against the production system + 1. It configures the JAR plugin to create an "attached" JAR with the "test" classifier\. + + To activate this profile execute `mvn -Ptest install` and Maven will execute the steps in the profile in addition to the normal steps\. From this build you will get two artifacts, "foo\-1\.0\.jar" and "foo\-1\.0\-test\.jar"\. These two jars will identical\. + +# Caveats + +- Currently Maven doesn't allow a project build to only produce attached artifacts\. \(i\.e\. it has to produce a "main" artifact as well\) This results in two equal JARs being packaged and installed\. The JAR plugin probably should also get improved support for this use case to that two different output directories will be used as the basis for building the JAR\. +- The usage of the delete task might seem a bit odd but is required to make sure that the copy task actually will copy the file\. The copy task will look at the timestamps of the source and destination files, only when copying the files it won't know that the actually source file might be different than the last time it was executed\. +- After the build the test configuration will be in target/classes and won't be overridden because the resources plugin uses the same timestamp checking, so you should always do a clean after executing Maven with a profile\. +- For the reasons given above it's imperative that you only build an artifact for a single environment in a single execution at a time and that you execute "mvn clean" whenever you change the profile switches\. If not, you might get artifacts with a mixed set of configuration files\. +# Resources + +1. [Introduction to Build Profiles](\.\./introduction/introduction\-to\-profiles\.html) +1. [Standard Directory Layout](\.\./introduction/introduction\-to\-the\-standard\-directory\-layout\.html) diff --git a/content/markdown/guides/mini/guide-configuring-maven.md b/content/markdown/guides/mini/guide-configuring-maven.md new file mode 100644 index 0000000000..89ec2c9cf6 --- /dev/null +++ b/content/markdown/guides/mini/guide-configuring-maven.md @@ -0,0 +1,137 @@ +--- +title: Guide to Configuring Maven +author: + - Brett Porter +date: 2005-04-12 +--- + + + + + + + + + + + + + + + + + + + +# Configuring Maven + +Maven configuration occurs at 3 levels: + +- _Project_ \- most static configuration occurs in `pom.xml` +- _Installation_ \- this is configuration added once for a Maven installation +- _User_ \- this is configuration specific to a particular user + +The separation is quite clear \- the project defines information that applies to the project, no matter who is building it, while the others both define settings for the current environment\. + +**Note:** the installation and user configuration cannot be used to add shared project information \- for example, setting `` or `` company\-wide\. + +For this, you should have your projects inherit from a company\-wide parent `pom.xml`\. + + + +You can specify your user configuration in `${user.home}/.m2/settings.xml`\. A [full reference](\.\./\.\./maven\-settings/settings\.html) to the configuration file is available\. This section will show how to make some common configurations\. Note that the file is not required \- defaults will be used if it is not found\. + +## Configuring your Local Repository + +The location of your local repository can be changed in your user configuration\. The default value is `${user.home}/.m2/repository/`\. + +``` + + ... + /path/to/local/repo/ + ... + +``` + +**Note:** The local repository must be an absolute path\. + +## Configuring a Proxy + +Proxy configuration can also be specified in the settings file\. + +For more information, see the [ Guide to using a Proxy](\./guide\-proxies\.html)\. + +## Configuring Parallel Artifact Resolution + +By default, Maven 2\.1\.0\+ will download up to 5 artifacts \(from different groups\) at once\. To change the size of the thread pool, start Maven using `-Dmaven.artifact.threads`\. For example, to only download single artifacts at a time: + +``` +mvn -Dmaven.artifact.threads=1 verify +``` + +You may wish to set this option permanently, in which case you can use the `MAVEN_OPTS` environment variable\. For example: + +``` +export MAVEN_OPTS=-Dmaven.artifact.threads=3 +``` + +## Security and Deployment Settings + +Repositories to deploy to are defined in a project in the `` section\. However, you cannot put your username, password, or other security settings in that project\. For that reason, you should add a server definition to your own settings with an `id` that matches that of the deployment repository in the project\. + +In addition, some repositories may require authorization to download from, so the corresponding settings can be specified in a `server` element in the same way\. + +Which settings are required will depend on the type of repository you are deploying to\. As of the first release, only SCP deployments and file deployments are supported by default, so only the following SCP configuration is needed: + +``` + + ... + + + repo1 + repouser + + + ... + + ... + +``` + +To encrypt passwords in these sections, refer to [ Encryption Settings](\./guide\-encryption\.html)\. + +## Using Mirrors for Repositories + +Repositories can be declared inside a project, which means that if you have your own custom repositories, those sharing your project easily get the right settings out of the box\. However, you may want to use an alternative mirror for a particular repository without changing the project files\. Refer to [ Guide to Mirror Settings](\./guide\-mirror\-settings\.html) for more details\. + +## Profiles + +Repository configuration can also be put into a profile\. You can have multiple profiles, with one set to active so that you can easily switch environments\. Read more about profiles in [Introduction to Build Profiles](\.\./introduction/introduction\-to\-profiles\.html)\. + +## Optional configuration + +Maven will work for most tasks with the above configuration, however if you have any environmental specific configuration outside of individual projects then you will need to configure settings\. The following sections refer to what is available\. + +### Settings + +Maven has a settings file located in the Maven installation and/or user home directory that configure environmental specifics such as: + +- HTTP proxy server +- repository manager location +- server authentication and passwords +- other configuration properties + +For information on this file, see the [Settings reference](/settings\.html) + +### Security + +You can encrypt passwords in your settings file\. However, you must first configure a master password\. For more information on both server passwords and the master password, see the [Guide to Password Encryption](\./guide\-encryption\.html)\. + +### Toolchains + +You can build a project using a specific version of JDK independent from the one Maven is running with\. For more information, see the [Guide to Using Toolchains](\./guide\-using\-toolchains\.html)\. + diff --git a/content/markdown/guides/mini/guide-configuring-plugins.md b/content/markdown/guides/mini/guide-configuring-plugins.md new file mode 100644 index 0000000000..0afaf6a6f7 --- /dev/null +++ b/content/markdown/guides/mini/guide-configuring-plugins.md @@ -0,0 +1,657 @@ +--- +title: Guide to Configuring Plug-ins +author: + - Jason van Zyl + - Vincent Siveton +date: 2009-08-26 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Configuring Plug\-ins + +- [Introduction](Introduction) +- [Generic Configuration](Generic\_Configuration) + - [Help Goal](Help\_Goal) + - [Configuring Parameters](Configuring\_Parameters) + - [Mapping Value Objects](Mapping\_Value\_Objects) + - [Mapping Complex Objects](Mapping\_Complex\_Objects) + - [Mapping Collection Types](Mapping\_Collection\_Types) + - [Mapping Collections and Arrays](Mapping\_Collections\_and\_Arrays) + - [Mapping Maps](Mapping\_Maps) + - [Mapping Properties](Mapping\_Properties) +- [Configuring Build Plugins](Configuring\_Build\_Plugins) + - [Using the <executions> Tag](Using\_the\_\.3Cexecutions\.3E\_Tag) + - [Using the <dependencies> Tag](Using\_the\_\.3Cdependencies\.3E\_Tag) + - [Using the <inherited> Tag In Build Plugins](Using\_the\_\.3Cinherited\.3E\_Tag\_In\_Build\_Plugins) +- [Configuring Reporting Plugins](Configuring\_Reporting\_Plugins) + - [Using the <reporting> Tag VS <build> Tag](Using\_the\_\.3Creporting\.3E\_Tag\_VS\_\.3Cbuild\.3E\_Tag) + - [Using the <reportSets> Tag](Using\_the\_\.3CreportSets\.3E\_Tag) + - [Using the <inherited> Tag In Reporting Plugins](Using\_the\_\.3Cinherited\.3E\_Tag\_In\_Reporting\_Plugins) +## Introduction + +In Maven, there are two kinds of plugins, build and reporting: + +- **Build plugins** are executed during the build and configured in the `` element\. +- **Reporting plugins** are executed during the site generation and configured in the `` element\. + +All plugins should have at least the minimal required [information](/ref/current/maven\-model/maven\.html\#class\_plugin): `groupId`, `artifactId` and `version`\. + +**Important Note**: Always define the version of each plugin used to guarantee build reproducibility\. A good practice is to specify each build plugin's version in a `` element\. Often the <pluginManagement/> element is found in the parent POM\. For reporting plugins, specify each version in the `` element \(and in the `` element too\)\. + +## Generic Configuration + +Maven plugins \(build and reporting\) are configured by specifying a `` element where the child elements of the `` element are mapped to fields, or setters, inside your Mojo\. \(Remember that a plug\-in consists of one or more Mojos where a Mojo maps to a goal\.\) Say, for example, you have a Mojo that performs a query against a particular URL, with a specified timeout and list of options\. The Mojo might look like the following: + +``` +@Mojo( name = "query" ) +public class MyQueryMojo + extends AbstractMojo +{ + @Parameter(property = "query.url", required = true) + private String url; + + @Parameter(property = "timeout", required = false, defaultValue = "50") + private int timeout; + + @Parameter(property = "options") + private String[] options; + + public void execute() + throws MojoExecutionException + { + ... + } +} +``` + +To configure the Mojo from your POM with the desired URL, timeout and options you might have something like the following: + +``` + + ... + + + + maven-myquery-plugin + 1.0 + + http://www.foobar.com/query + 10 + + + + + + + + + + ... + +``` + +The elements in the configuration match the names of the fields in the Mojo\. The mapping is straight forward\. The `url` element maps to the `url` field, the `timeout` element maps to the `timeout` field, and the `options` element maps to the `options` field\. The mapping mechanism can deal with arrays by inspecting the type of the field and determining if a suitable mapping is possible\. + +For Mojos that are intended to be executed directly from the CLI, their parameters usually provide a means to be configured via system properties instead of a `` section in the POM\. The plugin documentation for those parameters will list an _expression_ that denotes the system properties for the configuration\. In the Mojo above, the parameter `url` is associated with the expression `${query.url}`, meaning its value can be specified by the system property `query.url` as shown below: + +``` +mvn myquery:query -Dquery.url=http://maven.apache.org +``` + +The name of the system property does not necessarily match the name of the mojo parameter\. While this is a rather common practice, you will often notice plugins that employ some prefix for the system properties to avoid name clashes with other system properties\. Though rarely, there are also plugin parameters that \(e\.g\. for historical reasons\) employ system properties which are completely unrelated to the parameter name\. So be sure to have a close look at the plugin documentation\. + +### Help Goal + +Most Maven plugins have a `help` goal that prints a description of the plugin and its parameters and types\. For instance, to see help for the javadoc goal, type: + +``` +mvn javadoc:help -Ddetail -Dgoal=javadoc +``` + +And you will see all parameters for the javadoc:javadoc goal, similar to this [page](/plugins/maven\-javadoc\-plugin/javadoc\-mojo\.html)\. + +### Configuring Parameters + +Parameterization of Mojos relies internally on the Plexus Component Configuration API provided by [sisu\-plexus](https://github\.com/eclipse/sisu\.plexus)\. + +#### Mapping Value Objects + +Mapping value types, like Boolean or Integer, is very simple\. The `` element might look like the following: + +``` + +... + + a string + true + 10 + 1.0 + c:\temp + http://maven.apache.org + +... + +``` + +The detailed type coercion is explained in the table below\. For conversion to primitive types their according [wrapper classes are used and automatically unboxed](https://docs\.oracle\.com/javase/tutorial/java/data/autoboxing\.html)\. + +|Parameter Class|Conversion from String| +|:---:|:---:| +|`Boolean`|[`Boolean.valueOf(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Boolean\.html\#valueOf\-java\.lang\.String\-)| +|`Byte`|[`Byte.decode(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Byte\.html\#decode\-java\.lang\.String\-)| +|`Character`|[`Character.valueOf(char)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Character\.html\#valueOf\-char\-) of the first character in the given string| +|`Class`|[`Class.forName(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Class\.html\#forName\-java\.lang\.String\-)| +|`java.util.Date`|[`SimpleDateFormat.parse(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/text/DateFormat\.html\#parse\-java\.lang\.String\-) for the following patterns: `yyyy-MM-dd hh:mm:ss.S a`, `yyyy-MM-dd hh:mm:ssa`, `yyyy-MM-dd HH:mm:ss.S` or `yyyy-MM-dd HH:mm:ss`| +|`Double`|[`Double.valueOf(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Double\.html\#valueOf\-java\.lang\.String\-)| +|`Enum`|[`Enum.valueOf(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Enum\.html\#valueOf\-java\.lang\.String\-)| +|`java.io.File`|[`new File(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/io/File\.html\#File\-java\.lang\.String\-) with the file separators normalized to `File.separatorChar`\. In case the file is relative, is is made absolute by prefixing it with the project's base directory\.| +|`Float`|[`Float.valueOf(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Float\.html\#valueOf\-java\.lang\.String\-)| +|`Integer`|[`Integer.decode(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Integer\.html\#decode\-java\.lang\.String\-)| +|`Long`|[`Long.decode(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Long\.html\#decode\-java\.lang\.String\-)| +|`Short`|[`Short.decode(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/Short\.html\#decode\-java\.lang\.String\-)| +|`String`|n/a| +|`StringBuffer`|[`new StringBuffer(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/StringBuffer\.html\#StringBuffer\-java\.lang\.String\-)| +|`StringBuilder`|[`new StringBuilder(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/lang/StringBuilder\.html\#StringBuilder\-java\.lang\.String\-)| +|`java.net.URI`|[`new URI(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/net/URI\.html\#URI\-java\.lang\.String\-)| +|`java.net.URL`|[`new URL(String)`](https://docs\.oracle\.com/javase/8/docs/api/java/net/URL\.html\#URL\-java\.lang\.String\-)| +#### Mapping Complex Objects + +Mapping complex types is also fairly straight forward\. Let's look at a simple example where we are trying to map a configuration for Person object\. The `` element might look like the following: + +``` + +... + + + Jason + van Zyl + + +... + +``` + +The rules for mapping complex objects are as follows: + +- There must be a private field that corresponds to name of the element being mapped\. So in our case the `person` element must map to a `person` field in the mojo\. +- The object instantiated must be in the same package as the Mojo itself\. So if your mojo is in `com.mycompany.mojo.query` then the mapping mechanism will look in that package for an object named `Person`\. The mechanism capitalizes the first letter of the element name and uses that to search for the object to instantiate\. +- If you wish to have the object to be instantiated live in a different package or have a more complicated name, specify this using an `implementation` attribute like the following: + +``` + +... + + + Jason + van Zyl + + +... + +``` + +#### Mapping Collection Types + +The configuration mapping mechanism can easily deal with most collections so let's go through a few examples to show you how it's done: + +##### Mapping Collections and Arrays + +Mapping to collections works in much the same way as mapping to arrays\. Each item is given in the XML as dedicated element\. The element name does not matter in that case\. So if you have a mojo like the following: + +``` +public class MyAnimalMojo + extends AbstractMojo +{ + @Parameter(property = "animals") + private List animals; + + public void execute() + throws MojoExecutionException + { + ... + } +} +``` + +where you have a field named `animals` then your configuration for the plug\-in would look like the following: + +``` + + ... + + + + maven-myanimal-plugin + 1.0 + + + cat + dog + aardvark + + + + + + ... + +``` + +Where each of the animals listed would be entries in the `animals` field\. Unlike arrays, collections do not necessarily have a specific component type\. In order to derive the type of a collection item, the following strategy is used: + +1. If the first item XML element contains an `implementation` hint attribute, try to load the class with the given fully qualified class name from the attribute value +1. If the first item XML element contains a `.`, try to load the class with the fully qualified class name given in the element name +1. Try the first item XML element name \(with capitalized first letter\) as a class in the same package as the mojo/object being configured +1. Use the parameter type information from either [`Field.getGenericType()`](https://docs\.oracle\.com/javase/7/docs/api/java/lang/reflect/Field\.html\#getGenericType\(\)) or [`Method.getGenericParameterTypes()`](https://docs\.oracle\.com/javase/7/docs/api/java/lang/reflect/Method\.html\#getGenericParameterTypes\(\)) +1. If the element has no children, assume its type is `String`\. Otherwise, the configuration will fail\. + +The following collection implementations are being used when there is no `implementation` hint attribute in the XML element representing the collection: + +|Collection Class|Used for| +|:---:|:---:| +|`TreeSet`|for all types assignable to `SortedSet`| +|`HashSet`|for all types assignable to `Set`| +|`ArrayList`|for every other `Collection` type which is not a `Map`| + +Since Maven 3\.3\.9 \([MNG\-5440](https://issues\.apache\.org/jira/browse/MNG\-5440)\), you can list individual items alternatively as comma\-separated list in the XML value of animals directly\. This approach is also used if configuring collection/array parameters via command line The following example is equivalent to the example above: + +``` + + ... + + + + maven-myanimal-plugin + 1.0 + + cat,dog,aardvark + + + + + ... + +``` + +Each item is mapped again according to the rules of this section depending on the type of the collection/array\. + +##### Mapping Maps + +In the same way, you could define maps like the following: + +``` +... + @Parameter + private Map myMap; +... +``` + +``` + +... + + + value1 + value2 + + +... + +``` + +Unlike Collections the value type for Maps is always derived from the parameter type information from either [`Field.getGenericType()`](https://docs\.oracle\.com/javase/7/docs/api/java/lang/reflect/Field\.html\#getGenericType\(\)) or [`Method.getGenericParameterTypes()`](https://docs\.oracle\.com/javase/7/docs/api/java/lang/reflect/Method\.html\#getGenericParameterTypes\(\))\. It falls back to `String`\. The key type must always be `String`\. + +In contrast to value objects and collections/arrays there is no string coercion defined for maps, i\.e\. you cannot give parameters of that type via CLI argument\. + +The map implementation class is by default `TreeMap` but can be overridden with an `implementation` attribute on the XML element representing the map\. + +##### Mapping Properties + +Properties should be defined like the following: + +``` +... + @Parameter + private Properties myProperties; +... +``` + +``` + +... + + + + propertyName1 + propertyValue1 + + + propertyName2 + propertyValue2 + + + +... + +``` + +In contrast to value objects and collections/arrays there is no string coercion defined for properties, i\.e\. you cannot give parameters of those type via CLI argument\. + +## Configuring Build Plugins + +The following is only to configure Build plugins in the `` element\. + +### Using the `` Tag + +You can also configure a mojo using the `` tag\. This is most commonly used for mojos that are intended to participate in some phases of the [build lifecycle](\.\./introduction/introduction\-to\-the\-lifecycle\.html)\. Using `MyQueryMojo` as an example, you may have something that will look like: + +``` + + ... + + + + maven-myquery-plugin + 1.0 + + + execution1 + test + + http://www.foo.com/query + 10 + + + + + + + + query + + + + execution2 + + http://www.bar.com/query + 15 + + + + + + + + query + + + + + + + ... + +``` + +The first execution with id "execution1" binds this configuration to the test phase\. The second execution does not have a `` tag, how do you think will this execution behave? Well, goals can have a default phase binding as discussed further below\. If the goal has a default phase binding then it will execute in that phase\. But if the goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle\. + +Note that while execution id's have to be unique among all executions of a single plugin within a POM, they don't have to be unique across an inheritance hierarchy of POMs\. Executions of the same id from different POMs are merged\. The same applies to executions that are defined by profiles\. + +How about if we have a multiple executions with different phases bound to it? How do you think will it behave? Let us use the example POM above again, but this time we shall bind `execution2` to a phase\. + +``` + + ... + + + + ... + + + execution1 + test + ... + + + execution2 + install + + http://www.bar.com/query + 15 + + + + + + + + query + + + + + + + ... + +``` + +If there are multiple executions bound to different phases, then the mojo is executed once for each phase indicated\. Meaning, `execution1` will be executed applying the configuration setup when the phase of the build is test, and `execution2` will be executed applying the configuration setup when the build phase is already in install\. + +Now, let us have another mojo example which shows a default lifecycle phase binding\. + +``` +@Mojo( name = "query", defaultPhase = LifecyclePhase.PACKAGE ) +public class MyBoundQueryMojo + extends AbstractMojo +{ + @Parameter(property = "query.url", required = true) + private String url; + + @Parameter(property = "timeout", required = false, defaultValue = "50") + private int timeout; + + @Parameter(property = "options") + private String[] options; + + public void execute() + throws MojoExecutionException + { + ... + } +} +``` + +From the above mojo example, `MyBoundQueryMojo` is by default bound to the package phase \(see the `@phase` notation\)\. But if we want to execute this mojo during the install phase and not with package we can rebind this mojo into a new lifecycle phase using the `` tag under ``\. + +``` + + ... + + + + maven-myquery-plugin + 1.0 + + + execution1 + install + + http://www.bar.com/query + 15 + + + + + + + + query + + + + + + + ... + +``` + +Now, `MyBoundQueryMojo` default phase which is package has been overridden by install phase\. + +**Note:** Configurations inside the `` element used to differ from those that are outside `` in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked\. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin\. Since Maven 3\.3\.1 this is not the case anymore as you can specify on the command line the execution id for direct plugin goal invocation\. Hence if you want to run the above plugin and it's specific execution1's configuration from the command\-line, you can execute: + +``` +mvn myquery:query@execution1 +``` + +### Using the `` Tag + +You could configure the dependencies of the Build plugins, commonly to use a more recent dependency version\. + +For instance, the Maven Antrun Plugin version 1\.2 uses Ant version 1\.6\.5, if you want to use the latest Ant version when running this plugin, you need to add `` element like the following: + +``` + + ... + + + + org.apache.maven.plugins + maven-antrun-plugin + 1.2 + ... + + + org.apache.ant + ant + 1.7.1 + + + org.apache.ant + ant-launcher + 1.7.1 + + + + + + ... + +``` + +### Using the `` Tag In Build Plugins + +By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use the `` tag: + +``` + + ... + + + + org.apache.maven.plugins + maven-antrun-plugin + 1.2 + false + ... + + + + ... + +``` + +## Configuring Reporting Plugins + +The following is only to configure Reporting plugins in the `` element\. + +### Using the `` Tag VS `` Tag + +Configuring a reporting plugin in the `` or `` elements in the pom does not exactly have the same results\. + +
+
mvn site
+
Since maven-site-plugin 3.4, it uses the parameters defined in the <configuration> element of each reporting Plugin specified in the <reporting> element, in addition to the parameters defined in the <configuration> element of each plugin specified in <build> (parameters from <build> section were previously ignored).
+
mvn aplugin:areportgoal
+
It ignores the parameters defined in the <configuration> element of each reporting Plugin specified in the <reporting> element; only parameters defined in the <configuration> element of each plugin specified in <build> are used.
+
+ +### Using the `` Tag + +You can configure a reporting plugin using the `` tag\. This is most commonly used to generate reports selectively when running `mvn site`\. The following will generate only the project team report\. + +``` + + ... + + + + org.apache.maven.plugins + maven-project-info-reports-plugin + 2.1.2 + + + + project-team + + + + + + + ... + +``` + +**Notes**: + +1. To exclude all reports, you need to use: + + ``` + + + + + + ``` + +1. Refer to each Plugin Documentation \(i\.e\. plugin\-info\.html\) to know the available report goals\. +### Using the `` Tag In Reporting Plugins + +Similar to the build plugins, to break the inheritance, you can use the `` tag: + +``` + + ... + + + + org.apache.maven.plugins + maven-project-info-reports-plugin + 2.1.2 + false + + + + ... + +``` + diff --git a/content/markdown/guides/mini/guide-creating-archetypes.md b/content/markdown/guides/mini/guide-creating-archetypes.md new file mode 100644 index 0000000000..88b2f42d9f --- /dev/null +++ b/content/markdown/guides/mini/guide-creating-archetypes.md @@ -0,0 +1,189 @@ +--- +title: Guide to Creating Archetypes +author: + - Jason van Zyl, Alexander Hars, Franz Allan Valencia See +date: 2010-04-10 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Creating Archetypes + +Creating an archetype is a pretty straight forward process\. An archetype is a very simple artifact, that contains the project prototype you wish to create\. An archetype is made up of: + +- an [archetype descriptor](/archetype/archetype\-models/archetype\-descriptor/archetype\-descriptor\.html) \(`archetype-metadata.xml` in directory: `src/main/resources/META-INF/maven/`\)\. It lists all the files that will be contained in the archetype and categorizes them so they can be processed correctly by the archetype generation mechanism\. +- the prototype files that are copied by the archetype plugin \(directory: `src/main/resources/archetype-resources/`\) +- the prototype pom \(`pom.xml` in: `src/main/resources/archetype-resources`\) +- a pom for the archetype \(`pom.xml` in the archetype's root directory\)\. + +To create an archetype follow these steps: + +## 1\. Create a new project and pom\.xml for the archetype artifact + +An example `pom.xml` for an archetype artifact looks as follows: + +``` + + + 4.0.0 + + my.groupId + my-archetype-id + 1.0-SNAPSHOT + maven-archetype + + + + + org.apache.maven.archetype + archetype-packaging + 3.1.1 + + + + +``` + +All you need to specify is a `groupId`, `artifactId` and `version`\. These three parameters will be needed later for invoking the archetype via `archetype:generate` from the commandline\. + +## 2\. Create the archetype descriptor + +The [archetype descriptor](/archetype/archetype\-models/archetype\-descriptor/archetype\-descriptor\.html) is a file called `archetype-metadata.xml` which must be located in the `src/main/resources/META-INF/maven/` directory\. An example of an archetype descriptor can be found in the quickstart archetype: + +``` + + + + + src/main/java + + + src/test/java + + + +``` + +The attribute `name` tag should be the same as the `artifactId` in the archetype `pom.xml`\. + +The boolean attribute `partial` show if this archetype is representing a full Maven project or only parts\. + +The `requiredProperties`, `fileSets` and `modules` tags represent the differents parts of the project: + +- `` : List of required properties to generate a project from this archetype +- `` : File sets definition +- `` : Modules definition + +At this point one can only specify individual files to be created but not empty directories\. + +Thus the quickstart archetype shown above defines the following directory structure: + +``` + +archetype +|-- pom.xml +`-- src + `-- main + `-- resources + |-- META-INF + | `-- maven + | `--archetype-metadata.xml + `-- archetype-resources + |-- pom.xml + `-- src + |-- main + | `-- java + | `-- App.java + `-- test + `-- java + `-- AppTest.java +``` + +## 3\. Create the prototype files and the prototype pom\.xml + +The next component of the archetype to be created is the prototype `pom.xml`\. Any `pom.xml` will do, just don't forget to the set `artifactId` and `groupId` as variables \( `${artifactId}` / `${groupId}` \)\. Both variables will be initialized from the commandline when calling `archetype:generate`\. + +An example for a prototype `pom.xml` is: + +``` + + + 4.0.0 + + ${groupId} + ${artifactId} + ${version} + jar + + ${artifactId} + http://www.myorganization.org + + + + junit + junit + 4.12 + test + + + +``` + +## 4\. Install the archetype and run the archetype plugin + +Now you are ready to install the archetype: + +``` + +mvn install +``` + +Now that you have created an archetype, you can try it on your local system by using the following command\. In this command, you need to specify the full information about the archetype you want to use \(its `groupId`, its `artifactId`, its `version`\) and the information about the new project you want to create \(`artifactId` and `groupId`\)\. Don't forget to include the version of your archetype \(if you don't include the version, you archetype creation may fail with a message that version:RELEASE was not found\) + +``` + +mvn archetype:generate \ + -DarchetypeGroupId= \ + -DarchetypeArtifactId= \ + -DarchetypeVersion= \ + -DgroupId= \ + -DartifactId= +``` + +Once you are happy with the state of your archetype, you can deploy \(or submit it to [Maven Central](/guides/mini/guide\-central\-repository\-upload\.html)\) it as any other artifact and the archetype will then be available to any user of Maven\. + +## Alternative way to start creating your Archetype + +Instead of manually creating the directory structure needed for an archetype, simply use + +``` +mvn archetype:generate + -DgroupId=[your project's group id] + -DartifactId=[your project's artifact id] + -DarchetypeGroupId=org.apache.maven.archetypes + -DarchetypeArtifactId=maven-archetype-archetype +``` + +Afterwhich, you can now customize the contents of the `archetype-resources` directory, and `archetype-metadata.xml`, then, proceed to Step\#4 \(Install the archetype and run the archetype plugin\)\. + diff --git a/content/markdown/guides/mini/guide-default-execution-ids.md b/content/markdown/guides/mini/guide-default-execution-ids.md new file mode 100644 index 0000000000..0aa91eb0af --- /dev/null +++ b/content/markdown/guides/mini/guide-default-execution-ids.md @@ -0,0 +1,162 @@ +--- +title: Guide to Configuring Default Mojo Executions +author: + - John Casey +date: 2009-06-10 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Configuring Default Mojo Executions + +In most cases where you need to configure a plugin, there are two options that work well: plugin\-level configuration and execution\-level configuration\. Plugin\-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default lifecycle, or that use a common configuration across all invocations\. In fact, for direct invocation from the command line, plugin\-level configuration has been the _only_ option historically\. + +On the other hand, in cases where a more advanced build process requires the execution of mojos \- sometimes the same mojos, sometimes different ones \- from a single plugin that use different configurations, the execution\-level configuration is most commonly used\. These cases normally involve plugins that are introduced as part of the standard build process, but which aren't present in the default lifecycle mapping for that particular packaging\. In these cases, common settings shared between executions are still normally specified in the plugin\-level configuration\. + +However, these two options leave out a few important configuration use cases: + +- Mojos run from the command line _and_ during the build, when the CLI\-driven invocation requires its own configuration\. +- Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases where the same mojos need to be added to a second execution with different configuration\. +- Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but require separate configurations\. +## Default `executionId`s for Implied Executions + +When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable to refer to them as implied executions\. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've implemented is rather simple and low\-tech, but should be more than adequate to handle even advanced use cases\. Each mojo invoked directly from the command line will have an execution Id of `default-cli` assigned to it, which will allow the configuration of that execution from the POM by using this default execution Id\. Likewise, each mojo bound to the build lifecycle via the default lifecycle mapping for the specified POM packaging will have an execution Id of `default-` assigned to it, to allow configuration of each default mojo execution independently\. + +### Example: Command\-line variant invocation of the assembly plugin + +Consider the case where the user wants to execute the `assembly:assembly` mojo directly on the command line, but already has a configuration for the `assembly:single` mojo that runs during the main build lifecycle\. Since these configurations require different options, the user cannot use the plugin\-level configuration section to specify common elements\. + +In this case, the assembly\-plugin configuration might look like this: + +``` + + maven-assembly-plugin + + gnu + + + + build-distros + package + + single + + + + src/main/assembly/bin.xml + src/main/assembly/src.xml + + + + + default-cli + + + jar-with-dependencies + project + + + + + +``` + +In the above example, you can see several interesting things\. First, the main build process will invoke the `assembly:single` mojo during the `package` phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with the project\. Second, all invocations of the assembly plugin should use a `tarLongFileMode` strategy of `gnu`\. Finally, when the assembly plugin is invoked from the command line, it will build the standard `jar-with-dependencies` and `project` artifacts for the project, and ignore the custom assembly descriptors in `src/main/assembly`\. + +Now, notice the difference in the way the two execution blocks reference assembly descriptors\. One uses custom descriptors via the `descriptors` section, and the other uses standard descriptors via the `descriptorRefs` section\. These two sections cannot override one another, so it's impossible to setup one section \- say, `descriptorRefs` \- in the plugin\-level configuration block \(to provide CLI access to it, as historical versions of Maven would require\), then have the `build-distros` invocation override it with the custom descriptors specified in the `descriptors` section\. + +### Example: Configuring `compile` to run twice + +In this scenario, the user wants to run the `compiler:compile` mojo twice for his `jar` packaging project\. The main reason for this is to provide an entry point into the application that will warn the user if he's using a Java version older than 1\.5, then exit gracefully\. Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1\.4 or older JRE\. + +Therefore, the user needs to compile the bulk of his application to target the 1\.5 Java specification, then compile the rest \(the entry point\) to target an older specification\.\.\.say, 1\.3\. The first execution will specify the `source` and `target` values at `1.5`, and add an `excludes` section to avoid compiling the entry point for the application\. The second pass will then re\-specify `source` and `target` to `1.3`, and basically invert the original `excludes` section to be an `includes` section, so as to compile _only_ the entry point class\. + +The resulting configuration might look something like this: + +``` + + maven-compiler-plugin + + 1.5 + 1.5 + + + + default-compile + + + **/cli/* + + + + + build-java14-cli + compile + + compile + + + 1.3 + 1.3 + + **/cli/* + + + + + +``` + +There are three important things to notice in the above compiler\-plugin configuration: + +- The default `source` and `target` compatibility levels are for Java 1\.5\. This means that the compiler will generate binaries for Java 1\.5 from both the main codebase and the test codebase, unless otherwise overridden\. +- The default pass of the `compile` goal will _exclude_ the `**/cli/*` path pattern, but will compile everything else in `src/main/java` to run under Java 1\.5\. +- The second pass of the `compile` mojo \- in the execution called `build-java14-cli` \- resets the `source` and `target` versions to `1.3`, and inverts the exclude rule from the first pass\. This means the second time around, the compiler will produce 1\.4\-targeted binaries for the classes matching the `**/cli/*` path pattern\. +### Example: Configuring `compile` and `testCompile` mojos separately + +Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target version 1\.4 of the Java specification as his runtime platform\. However, he still wants the convenience and other advantages to be found in a unit\-testing framework like TestNG\. This forces the user to configure the `compile` mojo with one set of `source` and `target` values \- specifically, `1.4` \- and the `testCompile` mojo with another \(`1.5`\)\. + +The resulting compiler\-plugin configuration might look something like the following: + +``` + + maven-compiler-plugin + + + default-compile + + 1.3 + 1.3 + + + + default-testCompile + + 1.5 + 1.5 + + + + +``` + +This example is fairly simple and straightforward\. First, the `default-compile` execution sets the `source` and `target` values to `1.3` to allow older Java versions to run the project\. Then, the `default-testCompile` execution resets the `source` and `target` values to `1.5`, which enables the project to use tools like TestNG that use annotations\. + +Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1\.3 by default, so the only configuration that's really required is the `default-testCompile` execution\. The `default-compile` execution respecifies plugin defaults\. The only time this might be useful is when a parent POM defines a plugin\-level configuration for `source` and `target` that needs to be changed for the purposes of these different compiler executions\. This example is meant to be illustrative of the potential for separate configuration of default lifecycle mojos\. + diff --git a/content/markdown/guides/mini/guide-deployment-security-settings.md b/content/markdown/guides/mini/guide-deployment-security-settings.md new file mode 100644 index 0000000000..e0db398f51 --- /dev/null +++ b/content/markdown/guides/mini/guide-deployment-security-settings.md @@ -0,0 +1,58 @@ +--- +title: Guide to Deployment and Security Settings +author: + - Jason van Zyl +date: 2005-10-12 +--- + + + + + + + + + + + + + + + + + + + +# Security and Deployment Settings + +Repositories to deploy to are defined in a project in the `distributionManagement` section\. However, you cannot put your username, password, or other security settings in that project\. For that reason, you should add a server definition to your own settings with an id that matches that of the deployment repository in the project\. + +In addition, some repositories may require authorisation to download from, so the corresponding settings can be specified in a server element in the same way\. + +Which settings are required will depend on the type of repository you are deploying to\. As of the first release, only SCP deployments and file deployments are supported by default, so only the following SCP configuration is needed: + +``` + + + . + . + + + repo1 + repouser + + + + . + . + +``` + +To encrypt passwords in these sections, refer to [ Encryption Settings](\./guide\-encryption\.html)\. + +**Note**: The settings descriptor documentation can be found on the [Maven Local Settings Model Website](\.\./\.\./maven\-settings/settings\.html)\. + diff --git a/content/markdown/guides/mini/guide-encryption.md b/content/markdown/guides/mini/guide-encryption.md new file mode 100644 index 0000000000..ca2f0283c0 --- /dev/null +++ b/content/markdown/guides/mini/guide-encryption.md @@ -0,0 +1,211 @@ +--- +title: Password Encryption +author: + - Oleg Gusakov + - Robert Scholte +date: 2014-03-23 +--- + + + + + + + + + + + + + + + + + + + +# Password Encryption + +1. [Introduction](Introduction) +1. [How to create a master password](How\_to\_create\_a\_master\_password) +1. [How to encrypt server passwords](How\_to\_encrypt\_server\_passwords) +1. [How to keep the master password on removable drive](How\_to\_keep\_the\_master\_password\_on\_removable\_drive) +1. [Tips](Tips) +## Introduction + +Maven supports server password encryption\. The main use case, addressed by this solution is: + +- multiple users share the same build machine \(server, CI box\) +- some users have the privilege to deploy Maven artifacts to repositories, some don't\. + - this applies to any server operations, requiring authorization, not only deployment +- `settings.xml` is shared between users + +The implemented solution adds the following capabilities: + +- authorized users have an additional `settings-security.xml` file in their `${user.home}/.m2` directory + - this file either contains encrypted **master password**, used to encrypt other passwords + - or it can contain a **relocation** \- reference to another file, possibly on removable storage + - this password is created first via CLI for now +- server entries in the `settings.xml` have passwords and/or keystore passphrases encrypted + - for now \- this is done via CLI **after** master password has been created and stored in appropriate location +## How to create a master password + +Use the following command line: + +``` +mvn --encrypt-master-password +``` + +_Note:_ Since Maven 3\.2\.1 the password argument should no longer be used \(see [Tips](Tips) below for more information\)\. Maven will prompt for the password\. Earlier versions of Maven will not prompt for a password, so it must be typed on the command\-line in plaintext\. + +This command will produce an encrypted version of the password, something like + +``` +{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} +``` + +Store this password in the `${user.home}/.m2/settings-security.xml`; it should look like + +``` + + {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} + +``` + +When this is done, you can start encrypting existing server passwords\. + +## How to encrypt server passwords + +You have to use the following command line: + +``` +mvn --encrypt-password +``` + +_Note:_Just like `--encrypt-master-password` the password argument should no longer be used since Maven 3\.2\.1 \(see [Tips below for more information\.](Tips)\)\. + +This command produces an encrypted version of it, something like + +``` +{COQLCE6DU6GtcS5P=} +``` + +Copy and paste it into the servers section of your `settings.xml` file\. This will look like: + +``` + +... + +... + + my.server + foo + {COQLCE6DU6GtcS5P=} + +... + +... + +``` + +Please note that password can contain any information outside of the curly brackets, so that the following will still work: + +``` + +... + +... + + my.server + foo + Oleg reset this password on 2009-03-11, expires on 2009-04-11 {COQLCE6DU6GtcS5P=} + +... + +... + +``` + +Then you can use, say, deploy plugin, to write to this server: + +``` +mvn deploy:deploy-file -Durl=https://maven.corp.com/repo \ + -DrepositoryId=my.server \ + -Dfile=your-artifact-1.0.jar \ +``` + +## How to keep the master password on removable drive + +Create the master password exactly as described above, and store it on a removable drive, for instance on OSX, my USB drive mounts as `/Volumes/mySecureUsb`, so I store + +``` + + {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=} + +``` + +in the file `/Volumes/mySecureUsb/secure/settings-security.xml` + +And then I create `${user.home}/.m2/settings-security.xml` with the following content: + +``` + + /Volumes/mySecureUsb/secure/settings-security.xml + +``` + +This assures that encryption only works when the USB drive is mounted by the OS\. This addresses a use case where only certain people are authorized to deploy and are issued these devices\. + +## Tips + +### Escaping curly\-brace literals in your password _\(Since: Maven 2\.2\.0\)_ + +At times, you might find that your password \(or the encrypted form of it\) contains '\{' or '\}' as a literal value\. If you added such a password as\-is to your settings\.xml file, you would find that Maven does strange things with it\. Specifically, Maven treats all the characters preceding the '\{' literal, and all the characters after the '\}' literal, as comments\. Obviously, this is not the behavior you want\. What you really need is a way of **escaping** the curly\-brace literals in your password\. + +You can do this with the widely used '\\' escape character\. If your password looks like this: + +``` +jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+{EF1iFQyJQ= +``` + +Then, the value you would add to your settings\.xml looks like this: + +``` +{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+\{EF1iFQyJQ=} +``` + +### Password Security + +Editing `settings.xml` and running the above commands can still leave your password stored locally in plaintext\. You may want to check the following locations: + +- Shell history \(e\.g\. by running `history`\)\. You may want to clear your history after encrypting the above passwords +- Editor caches \(e\.g\. `~/.viminfo`\) + +Also note that the encrypted passwords can be decrypted by someone that has the master password and settings security file\. Keep this file secure \(or stored separately\) if you expect the possibility that the `settings.xml` file may be retrieved\. + +### Password Escaping on different platforms + +On some platforms it might be necessary to quote the password if it contains special characters like `%`, `!`, `$`, etc\. For example on Windows you have to be careful about things like the following: + +The following example will not work on Windows: + +``` +mvn --encrypt-master-password a!$%^b +``` + +whereas the following will work on Windows: + +``` +mvn --encrypt-master-password "a!$%^b" +``` + +If you are on a linux/unix platform you should use single quotes for the above master password\. Otherwise the master password will not work \(caused by the dollar sign and the exclamation mark\)\. + +### Prompting for Password + +In Maven before version 3\.2\.1 you have to give the password on the command line as an argument which means you might need to escape your password\. In addition usually the shell stores the full history of commands you have entered, therefore anyone with access to your computer could restore the password from the shell\`s history\. + +Starting with Maven 3\.2\.1, the password is an optional argument\. If you omit the password, you will be prompted for it which prevents all the issues mentioned above\. + +We strongly recommend using Maven 3\.2\.1 and above to prevent problems with escaping special characters and of course security issues related to bash history or environment issues in relationship with the password\. + diff --git a/content/markdown/guides/mini/guide-generating-sources.md b/content/markdown/guides/mini/guide-generating-sources.md new file mode 100644 index 0000000000..3880a0b3b0 --- /dev/null +++ b/content/markdown/guides/mini/guide-generating-sources.md @@ -0,0 +1,58 @@ +--- +title: Guide to generating Sources +author: + - Jason van Zyl + - Karl Heinz Marbaise +date: 2005-10-12 +2016-06-11 +--- + + + + + + + + + + + + + + + + + + + +# Guide to generating sources + +Let's run though a short example\. To generate sources you must first have a plugin that participates in the `generate-sources` phase like the [ANTLR4 Maven Plugin](https://www\.antlr\.org/api/maven\-plugin/latest/)\. You configure its execution in the POM: + +``` + + + ... + + + + org.antlr + antlr4-maven-plugin + 4.5.3 + + + antlr + + antlr4 + + + + + + + ... + +``` + +When you type `mvn compile`, Maven walks through the [lifecycle](\.\./introduction/introduction\-to\-the\-lifecycle\.html) and eventually hits the `generate-sources` phase\. It sees that a plugin is configured that wants to participate in that phase, and executes the ANTLR4 Maven Plugin with the given configuration\. Later, during the compile phase, all the code generated from the grammar files is compiled without further configuration\. + diff --git a/content/markdown/guides/mini/guide-http-settings.md b/content/markdown/guides/mini/guide-http-settings.md new file mode 100644 index 0000000000..0348d9a23e --- /dev/null +++ b/content/markdown/guides/mini/guide-http-settings.md @@ -0,0 +1,383 @@ +--- +title: Guide to Advanced Wagon Transport Configuration +author: + - John Casey +date: 2011-12-12 +--- + + + + + + + + + + + + + + + + + + + +# Advanced configuration to HttpClient HTTP Wagon + +**This page contains Wagon specific information, but the default transport in Maven 3\.9\.0\+ is NOT Wagon anymore\. Make sure to check the [Resolver Transport guide](\./guide\-resolver\-transport\.html) first, as things have changed\.** + +- [Advanced configuration to HttpClient HTTP Wagon](Advanced\_configuration\_to\_HttpClient\_HTTP\_Wagon) + - [Introduction](Introduction) + - [The Basics](The\_Basics) + - [Configuring GET, HEAD, PUT, or All of the Above](Configuring\_GET\.2C\_HEAD\.2C\_PUT\.2C\_or\_All\_of\_the\_Above) + - [Taking Control of Your HTTP Headers](Taking\_Control\_of\_Your\_HTTP\_Headers) + - [Fine\-Tuning HttpClient Parameters](Fine\-Tuning\_HttpClient\_Parameters) + - [Non\-String Parameter Values](Non\-String\_Parameter\_Values) + - [Example: Using Preemptive Authentication](Example\.3A\_Using\_Preemptive\_Authentication) + - [Example: Lifting auth scope restriction for external authentication systems](Example\.3A\_Lifting\_auth\_scope\_restriction\_for\_external\_authentication\_systems) + - [Ignoring Cookies](Ignoring\_Cookies) + - [Support for General\-Wagon Configuration Standards](Support\_for\_General\-Wagon\_Configuration\_Standards) + - [HTTP Headers](HTTP\_Headers) + - [Connection Timeouts](Connection\_Timeouts) + - [Read time out](Read\_time\_out) + - [Resources](Resources) + +You can use the default wagon implementation for a given protocol, or you can select an alternative wagon `provider` on a per\-protocol basis\. For more information, see the [Guide to Wagon Providers](\./guide\-wagon\-providers\.html) \[3\]\. The default wagon http\(s\) is the HttpClient based on [Apache Http Client 4\.5](https://hc\.apache\.org/httpcomponents\-client\-4\.5\.x/)\. HTTP connection pooling prevents reopening new connections to the same server for each request\. This pool feature is configurable with some parameters \[4\]\. The default wagon comes with some default configuration: + +- http\(s\) connection pool: default to 20\. +- readTimeout: default to 1800000 \(~30 minutes\) \(see section `Read time out` below\) +- default Preemptive Authentication only with PUT \(GET doesn't use anymore default Preemptive Authentication\) +## Introduction + +The HttpClient\-based HTTP wagon offers more control over the configuration used to access HTTP\-based Maven repositories\. For starters, you have fine\-grained control over what HTTP headers are used when resolving artifacts\. In addition, you can also configure a wide range of parameters to control the behavior of HttpClient itself\. Best of all, you have the ability to control these headers and parameters for all requests, or individual request types \(GET, HEAD, and PUT\)\. + +## The Basics + +Without any special configuration, Maven's HTTP wagon uses some default HTTP headers and client parameters when managing artifacts\. The default headers are: + +``` +Cache-control: no-cache +Cache-store: no-store +Pragma: no-cache +Expires: 0 +Accept-Encoding: gzip +``` + +In addition, PUT requests made with the HTTP wagon use the following HttpClient parameter: + +``` +http.protocol.expect-continue=true +``` + +From the HttpClient documentation\[2\], this parameter provides the following functionality: + +``` +Activates 'Expect: 100-Continue' handshake for the entity enclosing methods. +The 'Expect: 100-Continue' handshake allows a client that is sending a request +message with a request body to determine if the origin server is willing to +accept the request (based on the request headers) before the client sends the +request body. + +The use of the 'Expect: 100-continue' handshake can result in noticeable performance +improvement for entity enclosing requests (such as POST and PUT) that require +the target server's authentication. + +'Expect: 100-continue' handshake should be used with caution, as it may cause +problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. +``` + +Without this setting, PUT requests that require authentication transfer their entire payload to the server before that server issues an authentication challenge\. In order to complete the PUT request, the client must then re\-send the payload with the proper credentials specified in the HTTP headers\. This results in twice the bandwidth usage, and twice the time to transfer each artifact\. + +Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request\. However, there are a few potential issues with this approach\. For one thing, in the event you have an unused `` entry that specifies an invalid username/password combination, some servers may respond with a `401 Unauthorized` even if the server doesn't actually require any authentication for the request\. In addition, blindly sending authentication credentials with every request regardless of whether the server has made a challenge can result in a security hole, since the server may not make provisions to secure credentials for paths that don't require authentication\. + +We'll discuss preemptive authentication in another example, below\. + +## Configuring GET, HEAD, PUT, or All of the Above + +**Starting with Maven 3\.9\.0 native HTTP transport will pick up the "all" settings only \(get, head, put are neglected\!\)" but it will WARN about its deprecation\. For users sticking with Wagon nothing changes\.** + +In all of the examples below, it's important to understand that you can configure the HTTP settings for all requests made to a given server, or for only one method\. To configure all methods for a server, use the following section of the `settings.xml` file: + +``` + + [...] + + + the-server + + + + [ Your configuration here. ] + + + + + + +``` + +On the other hand, if you can live with the default configuration for most requests — say, HEAD and GET requests, which are used to check for the existence of a file and retrieve a file respectively — maybe you only need to configure the PUT method: + +``` + + [...] + + + the-server + + + + [ Your configuration here. ] + + + + + + +``` + +For clarity, the other two sections are `` for GET requests, and `` for HEAD requests\. I know that's going to be hard to remember\.\.\. + +## Taking Control of Your HTTP Headers + +As you may have noticed above, the default HTTP headers do have the potential to cause problems\. For instance, some websites set the encoding for downloading GZipped files as `gzip`, in spite of the fact that the HTTP request itself isn't being sent using GZip compression\. If the client is using the `Accept-Encoding: gzip` header, this can result in the client itself decompressing the GZipped file _during the transfer_ and writing the decompressed file to the local disk with the original filename\. This can be misleading to say the least, and can use up an inordinate amount of disk space on the local computer\. + +To turn off this default behavior, simply disable the default headers\. Then, respecify the other headers that you are still interested in, like this: + +``` + + [...] + + + openssl + + + + false + + + Cache-control + no-cache + + + Cache-store + no-store + + + Pragma + no-cache + + + Expires + 0 + + + Accept-Encoding + * + + + + + + + [...] + + [...] + +``` + +## Fine\-Tuning HttpClient Parameters + +Going beyond the power of HTTP request parameters, HttpClient provides a host of other configuration options\. In most cases, you won't need to customize these\. But in case you do, Maven provides access to specify your own fine\-grained configuration for HttpClient\. Again, you can specify these parameter customizations per\-method \(HEAD, GET, or PUT\), or for all methods of interacting with a given server\. For a complete list of supported parameters, see the link\[2\] in Resources section below\. + +### Non\-String Parameter Values + +Many of the configuration parameters for HttpClient have simple string values; however, there are important exceptions to this\. In some cases, you may need to specify boolean, integer, or long values\. In others, you may even need to specify a collection of string values\. You can specify these using a simple formatting syntax, as follows: + +1. **booleans:** `%b,` +1. **integer:** `%i,` +1. **long:** `%l,` \(yes, that's an 'L', not a '1'\) +1. **double:** `%d,` +1. **collection of strings:** `%c,,,,...`, which could also be specified as: + + ``` + %c, + , + , + , + ... + ``` + +As you may have noticed, this syntax is similar to the format\-and\-data strategy used by functions like `sprintf()` in many languages\. The syntax has been chosen with this similarity in mind, to make it a little more intuitive to use\. + +#### Example: Using Preemptive Authentication + +Using the above syntax, you can configure preemptive authentication for PUT requests using the boolean HttpClient parameter `http.authentication.preemptive`, like this: + +``` + + + + my-server + + + + + + http.authentication.preemptive + %b,true + + + + + + + + +``` + +Another option is to make write it like this: + +``` + + + + my-server + + + + true + + + + + + +``` + +### Example: Lifting auth scope restriction for external authentication systems + +Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers\. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation\. Configure your server element to pass authentication to all target servers which challenge the client\. \+\-\-\-\+ _settings_ _servers_ _server_ _id_my\-server_/id_ _configuration_ _basicAuthScope_ _host_ANY_/host_ _port_ANY_/port_ _\!\-\- or even 443 to force the use of TLS \-\-_ _/basicAuthScope_ _httpConfiguration_ _all_ _params_ _property_ _name_http\.protocol\.cookie\-policy_/name_ _value_standard_/value_ _/property_ _/params_ _/all_ _/httpConfiguration_ _/configuration_ _/server_ _/servers_ _/settings_ \+\-\-\-\+ + +### Ignoring Cookies + +Like the example above, telling the HttpClient to ignore cookies for all methods of request is a simple matter of configuring the `http.protocol.cookie-policy` parameter \(it uses a regular string value, so no special syntax is required\): + +``` + + + + my-server + + + + + + http.protocol.cookie-policy + ignore + + + + + + + + +``` + +The configuration above can be useful in cases where the repository is using cookies \- like the session cookies that are often mistakenly turned on or left on in appservers \- alongside HTTP redirection\. In these cases, it becomes far more likely that the cookie issued by the appserver uses a `Path` that is inconsistent with the one used by the client to access the server\. If you have this problem, and know that you don't need to use this session cookie, you can ignore cookies from this server with the above configuration\. + +## Support for General\-Wagon Configuration Standards + +It should be noted that configuration options previously available in the HttpClient\-driven HTTP wagon are still supported in addition to this new, fine\-grained approach\. These include the configuration of HTTP headers and connection timeouts\. Let's examine each of these briefly: + +### HTTP Headers + +In all HTTP Wagon implementations, you can add your own HTTP headers like this: + +``` + + + + my-server + + + + Foo + Bar + + + + + + +``` + +It's important to understand that the above approach doesn't allow you to turn off all of the default HTTP headers; nor does it allow you to specify headers on a per\-method basis\. However, this configuration remains available in both the lightweight and httpclient\-based Wagon implementations\. + +### Connection Timeouts + +All wagon implementations that extend the `AbstractWagon` class, including those for SCP, HTTP, FTP, and more, allow the configuration of a connection timeout, to allow the user to tell Maven how long to wait before giving up on a connection that has not responded\. This option is preserved in the HttpClient\-based wagon, but this wagon also provides a fine\-grained alternative configuration that can allow you to specify timeouts per\-method for a given server\. The old configuration option \- which is still supported \- looks like this: + +``` + + + + my-server + + 6000 + + + + +``` + +\.\.\.while the new configuration option looks more like this: + +``` + + + + my-server + + + + 10000 + + + + + + +``` + +If all you need is a per\-server timeout configuration, you still have the option to use the old `` parameter\. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above\. + +### Read time out + +The default timeout is 30 minutes\. If you want to change this value, you can add the following setup in your settings: + +``` + + + + my-server + + + + 120000 + + + + + + +``` + +## Resources + +1. [HttpClient website](https://hc\.apache\.org/httpcomponents\-client\-4\.5\.x/) +1. [HttpClient preference architecture and configuration guide](https://hc\.apache\.org/httpclient\-3\.x/preference\-api\.html) +1. [Guide to Wagon Providers](\./guide\-wagon\-providers\.html) +1. [Wagon Http](/wagon/wagon\-providers/wagon\-http/) diff --git a/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md b/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md new file mode 100644 index 0000000000..dd4035fa89 --- /dev/null +++ b/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md @@ -0,0 +1,192 @@ +--- +title: Guide to Large Scale Centralized Deployments +author: + - Phil Clay +date: 2021-01-01 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Large Scale Centralized Deployments + +This guide covers a simple optimized approach to using a [repository manager](\.\./\.\./repository\-management\.html) in a large organization with hundreds/thousands of Maven projects\. + +The pillars of this approach are: + +1. Use a centralized [repository manager](\.\./\.\./repository\-management\.html)\. + - Maven clients should download needed artifacts from the repository manager\. + - Maven clients should upload proprietary artifacts to the repository manager\. +1. Configure the location to download/upload artifacts in Maven `settings.xml` files, rather than in `pom.xml` files\. +1. Centrally manage the `settings.xml` files, and distribute them via automation\. +## Repository Manager Layout + +Repository managers generally have at least three types of repositories: + +
+
hosted
+
contains artifacts uploaded to the repository manager
+
proxy
+
proxies a remote repository and caches artifacts
+
virtual
+
aggregates several repositories into one
+
+ +The simplest way to organize repositories within a repository manager is to have a single virtual repository that aggregates: + +- a proxy repository for each public repository to mirror\. \(For example: Maven Central\) +- a hosted repository for releases +- a hosted repository for snapshots +- a hosted repository that can contain both releases and snapshots \(Only needed if some projects are still using Maven Deploy Plugin < 2\.8\. See [Managing Uploads to the Repository Manager](Managing\_Uploads\_to\_the\_Repository\_Manager) for more info\.\) + +Separate hosted repositories are generally used for releases and snapshots due to the need for different artifact retention policies\. + +The following sections describe how to configure Maven clients to: + +- [Download](Managing\_Downloads\_from\_the\_Repository\_Manager) artifacts from the virtual repository\. +- [Upload](Managing\_Uploads\_to\_the\_Repository\_Manager) artifacts to one of the hosted repositories\. +## Managing Downloads from the Repository Manager + +All artifacts used by Maven projects in the organization should be downloaded from the single virtual repository of the repository manager\. + +Maven can be instructed to download artifacts from the repository manager's virtual repository by defining a mirror in the Maven `settings.xml` file as described in the [Guide to Mirror Settings](\./guide\-mirror\-settings\.html)\. + +Example: To download artifacts from the corporate repository manager's `maven-virtual` repository: + +``` + + ... + + + + corp-repository-manager + Corporate Repository Manager + external:* + https://corp-repository-manager-host/maven-virtual + + + ... + +``` + +## Managing Uploads to the Repository Manager + +All proprietary artifacts produced by Maven projects in the organization should be uploaded to the repository manager's hosted repositories\. + +The [Maven Deploy Plugin](\.\./\.\./plugins/maven\-deploy\-plugin) can be instructed to upload artifacts to the repository manager's repositories by defining the `alt*DeploymentRepository` properties in the Maven `settings.xml` file\. When these properties are defined, the Maven Deploy Plugin's [deploy](\.\./\.\./plugins/maven\-deploy\-plugin/deploy\-mojo\.html) goal uses them instead of the `` section of `pom.xml` files to determine where to upload artifacts\. + +Defining the upload destination of artifacts in `settings.xml` files rather than in the `` section of `pom.xml` files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change\. In other words, rather than changing a huge number of `pom.xml` files, you just need to change [relatively few](Settings\_File\_Locations) `settings.xml` files if/when the distribution locations need to change\. + +The ability to specify separate alternate deployment repositories for releases and snapshots via the `altReleaseDeploymentRepository` and `altSnapshotDeploymentRepository` properties, respectively, was added in Maven Deploy Plugin 2\.8\. To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin >=2\.8\. If some projects are still using an older version of Maven Deploy Plugin \(>=2\.3 and <2\.8\), then specify a single alternate deployment repository via the `altDeploymentRepository` property that points to a repository capable of containing both releases and snapshots\. + +Typically, only continuous integration servers are allowed to upload artifacts to the repository manager\. Therefore, these settings should only be specified in `settings.xml` files on continuous integration servers, and should not be in `settings.xml` files on developer machines\. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include these properties in the `settings.xml` files used by developers\. + +Example: To upload artifacts to one of the corporate repository manager's hosted repositories: + +``` + + ... + + + + corp-repository-manager + + + + corp::default::https://corp-repository-manager-host/maven-snapshots + + + corp::default::https://corp-repository-manager-host/maven-releases + + + corp::default::https://corp-repository-manager-host/maven-combined + + + + + corp + + https://ignored + + true + never + + + true + always + + + + + + + corp + + https://ignored + + true + never + + + true + always + + + + + + + + corp-repository-manager + + ... + +``` + +## Settings File Locations + +Maven `settings.xml` files need to be available wherever Maven builds are performed, typically: + +- on continuous integration servers, and +- on developer machines + +Both locations should have the mirror settings mentioned in [Managing Downloads from the Repository Manager](Managing\_Downloads\_from\_the\_Repository\_Manager)\. + +Typically, only continuous integration servers should have the deployment repository settings mentioned in [Managing Uploads to the Repository Manager](Managing\_Uploads\_to\_the\_Repository\_Manager), because only continuous integration servers should be allowed to upload to the repository manager\. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include the deployment repository properties in the `settings.xml` files used by developers\. + +How the `settings.xml` files are stored and updated is beyond the scope of this document\. The general recommendation is to manage a few `settings.xml` files centrally, and then use automation to distribute them to continuous integration servers and developer machines\. + diff --git a/content/markdown/guides/mini/guide-manifest.md b/content/markdown/guides/mini/guide-manifest.md new file mode 100644 index 0000000000..bfa2c256a8 --- /dev/null +++ b/content/markdown/guides/mini/guide-manifest.md @@ -0,0 +1,37 @@ +--- +title: Guide to Working with Manifests +author: + - Jason van Zyl + - Dennis Lundberg +date: 2010-08-19 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Working with Manifests + +In order to modify the manifest of the archive produced by the packaging plug\-ins you need to create a configuration for it\. The definitive guide for this is [the site for the Maven Archiver shared component](/shared/maven\-archiver/index\.html)\. This component is used by all our packaging plugins\. + + + + + + + + diff --git a/content/markdown/guides/mini/guide-maven-classloading.md b/content/markdown/guides/mini/guide-maven-classloading.md new file mode 100644 index 0000000000..4720c77944 --- /dev/null +++ b/content/markdown/guides/mini/guide-maven-classloading.md @@ -0,0 +1,120 @@ +--- +title: Guide to Maven Classloading +author: + - Jason van Zyl + - Anders Kristian Andersen + - Konrad Windszus +date: 2022-11-16 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Maven Classloading + +This is a description of the classloader hierarchy in Maven\. + +- [Overview](Overview) +- [Platform Classloader](Platform\_Classloader) +- [System Classloader](System\_Classloader) +- [Core Classloader](Core\_Classloader) +- [API Classloader](API\_Classloader) +- [Build Extension Classloaders](Build\_Extension\_Classloaders) +- [Project Classloaders](Project\_Classloaders) +- [Plugin Classloaders](Plugin\_Classloaders) +- [Custom Classloaders](Custom\_Classloaders) +## Overview + +Maven uses the [Plexus Classworlds](https://codehaus\-plexus\.github\.io/plexus\-classworlds/) classloading framework to create the classloader graph\. If you look in your `${maven.home}/boot` directory, you will see a single JAR which is the Classworlds JAR we use to boot the classloader graph\. The Classworlds JAR is the only element of the Java `CLASSPATH`\. The other classloaders are built by Classworlds \("realms" in Classworlds terminology\)\. + +Each realm exposes + +1. optionally some classes imported from 0\.\.n other classloaders +1. optionally some classes from a directory or JAR +1. one parent classloader + +The search order is always as given above\. + +## Platform Classloader + +This is the classloader exposing all JRE classes\. + +## System Classloader + +It contains only Plexus Classworlds and imports the platform classloader\. + +## Core Classloader + +The second classloader down the graph contains the core requirements of Maven\. **It is used by Maven internally but not by plugins**\. The core classloader has the libraries in `${maven.home}/lib`\. In general these are just Maven libraries\. For example instances of [`MavenProject`](/ref/current/apidocs/org/apache/maven/project/MavenProject\.html) belong to this classloader\. + +You can add elements to this classloader by the means outlined in [Core Extension](\./guide\-using\-extensions\.html)\. These are loaded through the same classloader as `${maven.home}/lib` and hence are available to the Maven core and all plugins for the current project \(through the API Classloader, see next paragraph\)\. More information is available in [Core Extension](\./guide\-using\-extensions\.html)\. + +## API Classloader + +The API classloader is a filtered view of the Core Classloader, done by exposing only the exported packages from all Core Extensions\. The main API is listed in [Maven Core Extensions Reference](/ref/current/maven\-core/core\-extensions\.html)\. + +This has been introduced with Maven 3\.3\.1 \([MNG\-5771](https://issues\.apache\.org/jira/browse/MNG\-5771)\)\. + +## Build Extension Classloaders + +![Build Extension Class Realm](\.\./\.\./buildExtensionClassRealm\.svg) + +For every plugin which is marked with `true` and every [build extension](/ref/current/maven\-model/maven\.html\#class\_extension) listed in the according section of the POM, there is a dedicated classloader\. Those are isolated\. That is, one build extension does not have access to other build extensions\. It imports everything from the API classloader\. All JSR 330 or Plexus components declared in the underlying JAR are registered in the global Plexus container while creating the classloader\. In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container\. Build extensions have limited effect as they are loaded late\. + +## Project Classloaders + +There is one project classloader per Maven project \(identified through its coordinates\)\. This one imports the API Classloader\. In addition it exposes all classes from all Build Extension Classloaders which are bound to the current project\. This is only released with the container\. During the build outside Mojo executions, the thread's context classloader is set to the project classloader\. + +## Plugin Classloaders + +![Plugin Class Realm](\.\./\.\./pluginClassRealm\.svg) + +Each plugin \(which is not marked as build extension\) has its own classloader that imports the Project classloader\. + +Plugins marked with `true` leverage the Build Extension classloader instead of the Plugin classloader\. + +Users can add dependencies to this classloader by adding dependencies to a plugin in the [`plugins/plugin`](/ref/current/maven\-model/maven\.html\#class\_plugin) section of their project `pom.xml`\. Here is a sample of adding `ant-nodeps` to the plugin classloader of the Antrun Plugin and hereby enabling the use of additional/optional Ant tasks: + +``` + + org.apache.maven.plugins + maven-antrun-plugin + 1.3 + + + org.apache.ant + ant-nodeps + 1.7.1 + + + ... + +``` + +Plugins can inspect their effective runtime class path via the expressions `${plugin.artifacts}` or `${plugin.artifactMap}` to have a list or map, respectively, of resolved artifacts injected from the [`PluginDescriptor`](/ref/current/maven\-plugin\-api/apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor\.html)\. + +Please note that the plugin classloader does neither contain the [dependencies](/ref/current/maven\-model/maven\.html\#class\_dependency) of the current project nor its build output\. Instead, plugins can query the project's compile, runtime and test class path from the [`MavenProject`](/ref/current/apidocs/org/apache/maven/project/MavenProject\.html) in combination with the mojo annotation `requiresDependencyResolution` from the [Mojo API Specification](/developers/mojo\-api\-specification\.html)\. For instance, flagging a mojo with `@requiresDependencyResolution runtime` enables it to query the runtime class path of the current project from which it could create further classloaders\. + +When a build plugin is executed, the thread's context classloader is set to the plugin classloader\. + +## Custom Classloaders + +Plugins are free to create further classloaders\. For example, a plugin might want to create a classloader that combines the plugin class path and the project class path\. + +It is important to understand that the plugin classloader cannot load classes from any of those custom classloaders\. Some factory patterns require that\. Here you must add the classes to the plugin classloader as shown before\. + diff --git a/content/markdown/guides/mini/guide-mirror-settings.md b/content/markdown/guides/mini/guide-mirror-settings.md new file mode 100644 index 0000000000..f2006ea667 --- /dev/null +++ b/content/markdown/guides/mini/guide-mirror-settings.md @@ -0,0 +1,135 @@ +--- +title: Guide to Mirror Settings +author: + - Jason van Zyl + - Brian Fox + - Robert Scholte +date: 2015-01-02 +--- + + + + + + + + + + + + + + + + + + + +# Using Mirrors for Repositories + +With [Repositories](/guides/introduction/introduction\-to\-repositories\.html) you specify from which locations you want to _download_ certain artifacts, such as dependencies and maven\-plugins\. Repositories can be [declared inside a project](\.\./mini/guide\-multiple\-repositories\.html), which means that if you have your own custom repositories, those sharing your project easily get the right settings out of the box\. However, you may want to use an alternative mirror for a particular repository without changing the project files\. + +Some reasons to use a mirror are: + +- There is a synchronized mirror on the internet that is geographically closer and faster +- You want to replace a particular repository with your own internal repository which you have greater control over +- You want to run a [repository manager](\.\./\.\./repository\-management\.html) to provide a local cache to a mirror and need to use its URL instead + +To configure a mirror of a given repository, you provide it in your settings file \(`${user.home}/.m2/settings.xml`\), giving the new repository its own `id` and `url`, and specify the `mirrorOf` setting that is the ID of the repository you are using a mirror of\. For example, the ID of the main Maven Central repository included by default is `central`, so to use the different mirror instance, you would configure the following: + +``` + + ... + + + other-mirror + Other Mirror Repository + https://other-mirror.repo.other-company.com/maven2 + central + + + ... + +``` + +Note that there can be at most one mirror for a given repository\. In other words, you cannot map a single repository to a group of mirrors that all define the same `` value\. Maven will not aggregate the mirrors but simply picks the first match\. If you want to provide a combined view of several repositories, use a [repository manager](\.\./\.\./repository\-management\.html) instead\. + +The settings descriptor documentation can be found on the [Maven Local Settings Model Website](\.\./\.\./maven\-settings/settings\.html)\. + +**Note**: The official Maven repository is at `https://repo.maven.apache.org/maven2` hosted by the Sonatype Company and is distributed worldwide via CDN\. + +A list of known mirrors is available in the [Repository Metadata](https://repo\.maven\.apache\.org/maven2/\.meta/repository\-metadata\.xml)\. These mirrors may not have the same contents and we don't support them in any way\. + +# Using A Single Repository + +You can force Maven to use a single repository by having it mirror all repository requests\. The repository must contain all of the desired artifacts, or be able to proxy the requests to other repositories\. This setting is most useful when using an internal company repository with a [Maven Repository Manager](\.\./\.\./repository\-management\.html) to proxy external requests\. + +To achieve this, set `mirrorOf` to `*`\. + +**Note:** This feature is only available in Maven 2\.0\.5\+\. + +``` + + ... + + + internal-repository + Maven Repository Manager running on repo.mycompany.com + http://repo.mycompany.com/proxy + * + + + ... + +``` + +# Advanced Mirror Specification + +A single mirror can handle multiple repositories\. This is typically used in conjunction with a repository manager, that gives easy centralised configuration of the list of repositories behind\. + +The syntax: + +- `*` matches all repo ids\. +- `external:*` matches all repositories except those using localhost or file based repositories\. This is used when you want to exclude redirecting repositories that are defined for Integration Testing\. +- since Maven 3\.8\.0, `external:http:*` matches all repositories using HTTP except those using localhost\. +- multiple repositories may be specified using a comma as the delimiter +- an exclamation mark may be used in conjunction with one of the above wildcards to exclude a repository id + +Be careful not to include extra whitespace around identifiers or wildcards in comma separated lists\. For example, a mirror with `` exactly matches the repository identifier\. If no direct match is found, Maven picks the first mirror declaration that matches according to the rules above \(if any\)\. Hence, you may influence match order by changing the order of the definitions in the `settings.xml` + +Examples: + +- `*` = everything +- `external:*` = everything not on the localhost and not file based\. +- `repo,repo1` = repo or repo1 +- `*,!repo1` = everything except repo1 + +``` + + ... + + + internal-repository + Maven Repository Manager running on repo.mycompany.com + http://repo.mycompany.com/proxy + external:*,!foo + + + foo-repository + Foo + http://repo.mycompany.com/foo + foo + + + ... + +``` + +# Creating Your Own Mirror + +The size of the central repository is [increasing steadily](https://search\.maven\.org/stats) To save us bandwidth and you time, mirroring the entire central repository is not allowed\. \(Doing so will get you automatically banned\.\) Instead, we suggest you setup a [repository manager](\.\./\.\./repository\-management\.html) as a proxy\. + diff --git a/content/markdown/guides/mini/guide-multiple-modules.md b/content/markdown/guides/mini/guide-multiple-modules.md new file mode 100644 index 0000000000..a29f649659 --- /dev/null +++ b/content/markdown/guides/mini/guide-multiple-modules.md @@ -0,0 +1,71 @@ +--- +title: Guide to Working with Multiple Modules +author: + - Brett Porter + - Karl Heinz Marbaise +date: 2015-03-13 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Working with Multiple Modules + +\(If you're working with Maven 4, please refer to the [ Maven 4 edition of this guide](\./guide\-multiple\-modules\-4\.html)\) + +As seen in the introduction to the POM, Maven supports project aggregation in addition to project inheritance\. This section outlines how Maven processes projects with multiple modules, and how you can work with them more effectively\. + +## The Reactor + +The mechanism in Maven that handles multi\-module projects is referred to as the _reactor_\. This part of the Maven core does the following: + +- Collects all the available modules to build +- Sorts the projects into the correct build order +- Builds the selected projects in order +### Reactor Sorting + +Because modules within a multi\-module build can depend on each other, it is important that the reactor sorts all the projects in a way that guarantees any project is built before it is required\. + +The following relationships are honoured when sorting projects: + +- a project dependency on another module in the build +- a plugin declaration where the plugin is another module in the build +- a plugin dependency on another module in the build +- a build extension declaration on another module in the build +- the order declared in the `` element \(if no other rule applies\) + +Note that only "instantiated" references are used \- `dependencyManagement` and `pluginManagement` elements do not cause a change to the reactor sort order\. + +### Command Line Options + +No special configuration is required to take advantage of the reactor, however it is possible to customize its behavior\. + +The following command line switches are available: + +- `--resume-from` \- resumes a reactor from the specified project \(e\.g\. when it fails in the middle\) +- `--also-make` \- build the specified projects, and any of their dependencies in the reactor +- `--also-make-dependents` \- build the specified projects, and any that depend on them +- `--fail-fast` \- the default behavior \- whenever a module build fails, stop the overall build immediately +- `--fail-at-end` \- if a particular module build fails, continue the rest of the reactor and report all failed modules at the end instead +- `--non-recursive` \- do not use a reactor build, even if the current project declares modules and just build the project in the current directory + +Refer to the Maven command line interface reference for more information on these switches\. + +## More information + +- [ Chapter 6\. A Multi\-module Project \(Maven by Example\)](http://books\.sonatype\.com/mvnex\-book/reference/multimodule\.html) diff --git a/content/markdown/guides/mini/guide-multiple-repositories.md b/content/markdown/guides/mini/guide-multiple-repositories.md new file mode 100644 index 0000000000..218aaec184 --- /dev/null +++ b/content/markdown/guides/mini/guide-multiple-repositories.md @@ -0,0 +1,115 @@ +--- +title: Guide to using Multiple Repositories +author: + - Jason van Zyl +date: 2005-10-12 +--- + + + + + + + + + + + + + + + + + + + +# Setting up Multiple Repositories + +There are two different ways that you can specify the use of multiple repositories\. The first way is to specify in a POM which repositories you want to use\. That is supported both inside and outside of build profiles: + +``` + + +... + + + my-repo1 + your custom repo + http://jarsm2.dyndns.dk + + + my-repo2 + your custom repo + http://jarsm2.dyndns.dk + + +... + +``` + +**NOTE:** You will also get the standard set of repositories as defined in the [Super POM](\.\./introduction/introduction\-to\-the\-pom\.html\#Super\_POM)\. + +The other way you can specify multiple repositories is by creating a profile in the `${user.home}/.m2/settings.xml` or `${maven.home}/conf/settings.xml` file like the following: + +``` + + + ... + + ... + + myprofile + + + my-repo2 + your custom repo + http://jarsm2.dyndns.dk + + + + ... + + + + myprofile + + ... + +``` + +If you specify repositories in profiles you must remember to activate that particular profile\! As you can see above we do this by registering a profile to be active in the `activeProfiles` element\. + +You could also activate this profile on the command like by executing the following command: + +``` + +mvn -Pmyprofile ... +``` + +In fact the `-P` option will take a CSV list of profiles to activate if you wish to activate multiple profiles simultaneously\. + +**Note**: The settings descriptor documentation can be found on the [Maven Local Settings Model Website](\.\./\.\./maven\-settings/settings\.html)\. + +## Repository Order + +Remote repository URLs are queried in the following order for artifacts until one returns a valid result: + +1. effective settings: + 1. Global `settings.xml` + 1. User `settings.xml` +1. local effective build POM: + 1. Local `pom.xml` + 1. Parent POMs, recursively + 1. Super POM +1. effective POMs from dependency path to the artifact\. + +For each of these locations, the repositories within the profiles are queried first in the order outlined at [Introduction to build profiles](\.\./introduction/introduction\-to\-profiles\.html)\. + +Before downloading from a repository, [mirrors configuration](\./guide\-mirror\-settings\.html) is applied\. + +Effective settings and local build POM, with profile taken into account, can easily be reviewed to see their repositories order with `mvn help:effective-settings` and `mvn help:effective-pom -Dverbose`\. + +## Repository IDs + +Each repository must have a **unique ID**\. Clashing repository IDs within either effective settings or effective POMs lead to build failures\. However, repositories from POM get overwritten by repositories with the same ID from effective settings\. Repository IDs are also used in the [local repository metadata](https://maven\.apache\.org/ref/3\-LATEST/maven\-repository\-metadata/)\. + diff --git a/content/markdown/guides/mini/guide-naming-conventions.md b/content/markdown/guides/mini/guide-naming-conventions.md new file mode 100644 index 0000000000..89e1f196f0 --- /dev/null +++ b/content/markdown/guides/mini/guide-naming-conventions.md @@ -0,0 +1,45 @@ +--- +title: Guide to Naming Conventions +author: + - Carlos Sanchez +date: 2005-11-01 +--- + + + + + + + + + + + + + + + + + + + +# Guide to naming conventions on groupId, artifactId, and version + +- **groupId** uniquely identifies your project across all projects\. A group ID should follow [Java's package name rules](https://docs\.oracle\.com/javase/specs/jls/se6/html/packages\.html\#7\.7)\. This means it starts with a reversed domain name you control\. For example, + + `org.apache.maven`, `org.apache.commons` + + Maven does not enforce this rule\. There are many legacy projects that do not follow this convention and instead use single word group IDs\. However, it will be difficult to get a new single word group ID approved for inclusion in the Maven Central repository\. + + You can create as many subgroups as you want\. A good way to determine the granularity of the `groupId` is to use the project structure\. That is, if the current project is a multiple module project, it should append a new identifier to the parent's `groupId`\. For example, + + `org.apache.maven`, `org.apache.maven.plugins`, `org.apache.maven.reporting` + +- **artifactId** is the name of the jar without version\. If you created it, then you can choose whatever name you want with lowercase letters and no strange symbols\. If it's a third party jar, you have to take the name of the jar as it's distributed\. + + eg\. `maven`, `commons-math` + +- **version** if you distribute it, then you can choose any typical version with numbers and dots \(1\.0, 1\.1, 1\.0\.1, \.\.\.\)\. Don't use dates as they are usually associated with SNAPSHOT \(nightly\) builds\. If it's a third party artifact, you have to use their version number whatever it is, and as strange as it can look\. For example, + + `2.0`, `2.0.1`, `1.3.1` + diff --git a/content/markdown/guides/mini/guide-new-committers.md b/content/markdown/guides/mini/guide-new-committers.md new file mode 100644 index 0000000000..bc18e5907e --- /dev/null +++ b/content/markdown/guides/mini/guide-new-committers.md @@ -0,0 +1,35 @@ +--- +title: Guide for new committers +author: + - Jason van Zyl +date: 2005-11-20 +--- + + + + + + + + + + + + + + + + + + + +# Guide for new committers + +First thing is to sort out some administrative tasks\. Before your account is created and commit access granted you must complete and fax back to Apache the [Committer's License Agreement](http://www\.apache\.org/licenses/\#clas)\. + +While this process is sorting itself out it is recommended that you peruse the various guides provided by Apache\. All the guides are located in the [Development Infrastructure Information](http://www\.apache\.org/dev/)\. + +Of particular interest is the [Committer's FAQ](http://www\.apache\.org/dev/committers\.html) and the [New Committer's Guide](http://www\.apache\.org/dev/new\-committers\-guide\.html)\. + +If you have any questions please feel free to ask any of the Maven developers\. + diff --git a/content/markdown/guides/mini/guide-proxies.md b/content/markdown/guides/mini/guide-proxies.md new file mode 100644 index 0000000000..0956b9bf09 --- /dev/null +++ b/content/markdown/guides/mini/guide-proxies.md @@ -0,0 +1,59 @@ +--- +title: Guide to using proxies +author: + - Jason van Zyl +date: 2005-10-12 +--- + + + + + + + + + + + + + + + + + + + +# Configuring a proxy + +You can configure a proxy to use for some or all of your HTTP requests with Maven\. The username and password are only required if your proxy requires basic authentication \(note that later releases may support storing your passwords in a secured keystore \- in the mean time, please ensure your settings\.xml file \(usually $\{user\.home\}/\.m2/settings\.xml\) is secured with permissions appropriate for your operating system\)\. + +The `nonProxyHosts` setting accepts wild cards, and each host not to proxy is separated by the | character\. This matches the JDK configuration equivalent\. + +``` + + + . + . + + + example-proxy + true + http + proxy.example.com + 8080 + proxyuser + somepassword + www.google.com|*.example.com + + + . + . + +``` + +Please note that currently NTLM proxies are not supported as they have not been tested\. Some transports allow to use the relevant Java system properties to make this work, but that approach is specific for given implementation, and should not be considered the "official" way of configuring proxies\. + +## Resources + +1. [Settings descriptor documentation](\.\./\.\./maven\-settings/settings\.html) +1. [Configuring Maven](\./guide\-configuring\-maven\.html) diff --git a/content/markdown/guides/mini/guide-releasing.md b/content/markdown/guides/mini/guide-releasing.md new file mode 100644 index 0000000000..17bbdb99b6 --- /dev/null +++ b/content/markdown/guides/mini/guide-releasing.md @@ -0,0 +1,252 @@ +--- +title: Guide to using the release plugin +author: + - Jason van Zyl + - Trent Rosenbaum + - Vincent Massol + - Karl Heinz Marbaise +date: 2006-10-07 +2015-07-31 +--- + + + + + + + + + + + + + + + + + + + +# Releasing + +## Introduction + +The main aim of the maven\-release plugin is to provide a standard mechanism to release project artifacts outside the immediate development team\. The plugin provides basic functionality to create a release and to update the project's SCM accordingly\. + +To create a release the maven\-release plugin is executed through maven in 2 stages: + +1. Preparing the release\. +1. Performing the release\. +## Preparing the release + +The plugin will record release information into a new revision of the project's _pom\.xml_ file as well as applying SCM versioning to the project's resources\. + +The `release:prepare` goal will: + +1. Verify that there are no uncommitted changes in the workspace\. +1. Prompt the user for the desired tag, release and development version names\. +1. Modify and commit release information into the _pom\.xml_ file\. +1. Tag the entire project source tree with the new tag name\. + +The following example shows how to run the `release:prepare` goal with a Subversion SCM\. The commandline example directs the plugin to locate a Subversion SCM on a local file system\. + +``` +mvn release:prepare \ + -Dproject.scm.developerConnection=scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk \ + -DtagBase=file:///D:/subversion_data/repos/my_repo/my-app-example/tags +``` + +When using the `release:prepare` goal, the user must supply maven with information regarding the current location of the project's SCM\. In the previous example maven was supplied with the current location of the development trunk and the new location to record tagged instances of the project\. + +- **project\.scm\.developerConnection** + + The current location of the development trunk\. A valid SCM URL format appropriate to the SCM provider\. The "SCM:Provider:" prefix is used to determine the provider being used\. + +- **tagbase** + + The new location to record a tagged release\. A valid SCM URL format appropriate to the SCM provider without the "SCM:Provider:" prefix\. + +The previous goal parameters can be supplied while executing maven on the commandline, \(as shown in the previous example\) or they can be defined and maintained within the project's _pom\.xml_ file\. The location of the current development trunk is defined within the _pom\.xml_ file in the following form: + +``` + + 4.0.0 + com.mycompany.app + app + jar + 1.0-SNAPSHOT + Application + http://app.mycompany.com + ... + + scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk + + ... + + + ... + + maven-release-plugin + 2.5.2 + + ... + + file:///D:/subversion_data/repos/my_repo/my-app-example/tags + + ... + + + ... + + + ... + +``` + +To define the tagBase parameter within the _pom\.xml_ file a tagBase element must be defined within a _plugins/plugin/configuration_ element\. The following example shows how this would look within the _pom\.xml_ file\. + +``` + + 4.0.0 + com.mycompany.app + app + jar + 1.0-SNAPSHOT + Application + http://app.mycompany.com + ... + + scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk + + ... + + + ... + + maven-release-plugin + 2.5.2 + + ... + + file:///D:/subversion_data/repos/my_repo/my-app-example/tags + + ... + + + ... + + + ... + +``` + +During the execution of the `release:prepare` goal maven will interact with the user to gather information about the current release\. Maven will prompt the user for the following information: + +- **A Desired SCM provider tag name**\. + + This is a SCM provider specific value, in the case of the Subversion SCM provider this value is equal to the directory name that will appear under the URL provided by the the tagBase parameter\. + +- **A Desired project release version**\. + + This value is placed in the _pom\.xml_ that will define the current release\. If a development _pom\.xml_ holds a version value of 1\.0\-SNAPSHOT then the release version would be 1\.0\. This is not enforced and can be a value appropriate to yourself or a company environment\. + +- **A New development version**\. + + This value is the placed in the next revision of the _pom\.xml_ file used for continuing development\. If the current release represented version 1\.0 then an appropriate value could be 2\.0\-SNAPSHOT\. The SNAPSHOT designator is required to prepare and perform future releases\. This value is then committed in the next development revision of the _pom\.xml_ file\. + +After maven has been supplied with the required information the maven\-release plugin will interact with the project's SCM and define a relese to be extracted and deployed\. At the same time the project's development trunk is updated allowing developers to continue with further modifications that will be included within future releases\. + +## Performing the release + +The plugin will extract file revisions associated with the current release\. Maven will compile, test and package the versioned project source code into an artifact\. The final deliverable will then be released into an appropriate maven repository\. + +The `release:perform` goal will: + +1. Extract file revisions versioned under the new tag name\. +1. Execute the maven build lifecycle on the extracted instance of the project\. +1. Deploy the versioned artifacts to appropriate local and remote repositories\. + +The following example shows how to run the `release:perform` goal from the commandline\. + +``` +mvn release:perform +``` + +The `release:perform` goal requires a file called _release\.properties_ to be present within the project root directory\. The _release\.properties_ file is constructed during the execution of the `release:prepare` goal and contains all the information needed to locate and extract the correctly tagged version of the project\. Shown below is an example of the contents that can appear within an instance of the _release\.properties_ file\. + +**Note:** The location of the _release\.properties_ file is under review and could be moved to the target directory\. + +``` +#Generated by Release Plugin on: Sat Nov 12 11:22:33 GMT 2005 +#Sat Nov 12 11:22:33 GMT 2005 +maven.username=myusername +checkpoint.transformed-pom-for-release=OK +scm.tag=1.0 +scm.url=scm\:svn\:file\:///D\:/subversion_data/repos/my_repo/my-app-example/trunk +scm.tag-base=file\:///D\:/subversion_data/repos/my_repo/my-app-example/tags +checkpoint.transform-pom-for-development=OK +checkpoint.local-modifications-checked=OK +checkpoint.initialized=OK +checkpoint.checked-in-release-version=OK +checkpoint.tagged-release=OK +checkpoint.prepared-release=OK +checkpoint.check-in-development-version=OK +``` + +The _release\.properties_ file is created while preparing the release\. After performing the release the file remains within the project root directory until the maven user deletes it\. The _release\.properties_ file can be given to any developer within the team and by simply excuting the `release:perform` goal can create and deploy a new instance of the project artifact time and again\. + +During the execution of the `release:perform` goal the entire maven build lifecycle is executed on the project\. The tagged project source code is extracted, compiled, tested, documented and deployed\. An instance of the release artifact is deployed to the machine's local repository\. An another instance of the release can be deployed to a remote repository by configuring the _distributionManagement_ element within the _pom\.xml_ file\. + +The following is an example of how a distributionManagement element can be configured within a project _pom\.xml_ file\. + +``` + + 4.0.0 + com.mycompany.app + app + jar + 1.0-SNAPSHOT + Application + http://app.mycompany.com + ... + + + myRepoId + myCompanyReporsitory + ftp://repository.mycompany.com/repository + + + ... + +``` + +If the distributionManagement element is not configured within the _pom\.xml_ file then the deployment of the artifact will fail\. Maven will report a failure back to the user for the execution of the maven\-deploy plugin\. Please refer maven documentationa and additional mini guides for the use of the maven\-deploy plugin\. + +The following delvierables are created and deployed to local and remoted repositories after the execution of the `release:perform` goal has finished\. + +- _artifact id_\-_version_\.jar + + The binaries for the current release of the project\. + +- _artifact id_\-_version_\-javadoc\.jar + + The javadoc explaining the current functionality of the classes within the current release\. + +- _artifact id_\-_version_\-source\.jar + + The source code revisions used to build the current release of the project\. + +- _artifact id_\-_version_\.pom + + The contents of the _pom\.xml_ file used to create the current release of the project\. + +## Troubleshooting + +### I get a "The authenticity of host '_host_' can't be established\." error and the build hangs + +This is because your `~user/.ssh/known_hosts` file doesn't have the host listed\. You'd normally get a prompt to add the host to the known host list but Maven doesn't propagate that prompt\. The solution is to add the host the `known_hosts` file before executing Maven\. On Windows, this can be done by installing an OpenSSH client \(for example [SSHWindows](http://sshwindows\.sourceforge\.net/download/)\), running `ssh + + + + + + + + + + + + + + + + + +# Guide to relocation + +Sometimes it is necessary to relocate artifacts in the repository\. One example of that is when a project moves from one groupId to a different groupId\. + +Making changes to the repository can have far reaching consequences\. So it is best to get it right the first time, hence this guide\. + +**2020 rework in progress**, see [discussion on dev mailing list](https://lists\.apache\.org/thread\.html/r5e940260cfe5234f540c20fdb7bb7dacbb63b911a4b902c75f4f0cd2%40%3Cdev\.maven\.apache\.org%3E), still need analysis of issues, definition of improvements, and of course implementation\.\.\. + +## How to relocate a Maven 2 artifact to a different groupId + +The goal of the example below is for the `foo` project to relocate its groupId from `bar` to `org.bar`\. + +### Working on past versions + +1. Copy all `foo`\-related files from `/bar/foo/` in your Maven 2 repository to a temporary location\. +1. Change the groupId to `org.bar` in all `foo`\-related POM files in the temporary location\. +1. Copy all files from the temporary location to `/org/bar/foo/` in your Maven 2 repository\. +1. Create a minimal Maven 2 POM file for every old release of `foo` in your Maven 2 repository\. The POM files only need to include `groupId`, `artifactId`, `version` and the relocation section\. + + **Note:** Before you replace your old POM files in `/bar/foo/` with these minimal POM files, make sure you have made backups\! + + The minimal POM file might look like this for version 1\.0 of `foo`: + + ``` + + 4.0.0 + bar + foo + 1.0 + + + org.bar + + + + ``` + + In this case we are relocating because the groupId has changed\. We only need to add the element that has changed to the `relocation` element\. For information on which elements are allowed in the `relocation` element, see [the POM reference](/ref/current/maven\-model/maven\.html\#class\_relocation)\. + +1. If your project uses MD5 or SHA1 checksums you must now create new checksums for the pom files in `/bar/foo/` in your Maven 2 repository\. If the POM file needs to be signed, do that as well\. +1. If your project syncs with Central, you should now initiate that sync\. This might happen automatically depending on your projects sync policy\. + +Your `foo`\-artifacts are now available to Maven users with both the old and the new groupId\. Projects using the old groupId will automatically be redirected to the new groupId and a warning telling the user to update their dependencies will be issued\. + +### Releasing the next version + +When the next release of `foo` is made, you should publish two Maven 2 POM files: first you should publish `foo`'s POM with the new groupId `org.bar`\. + +Because data in the repository is not supposed to change, Maven doesn't download POM files that it has already downloaded\. Therefore you will also need to publish a relocation POM file with the old groupId `bar` for the new version: this should be a minimal relocation POM \(as described in step 4 above\), but for the new version of `foo`\. + +For the release after that, you only need to publish a Maven POM with a groupId of `org.bar`, since users of the previous version have been informed of the changed groupId\. + +## Examples + +### Apache Ant + +1. has published its releases until 1\.6\.5 to Maven 1\-compliant `ant:ant` coordinates \(see [repository content](https://repo\.maven\.apache\.org/maven2/ant/ant/)\), +1. starting with 1\.7\.0, moved to reverse\-DNS compliant Maven 2\+ `org.apache.ant:ant` coordinates, \(see [repository content](https://repo\.maven\.apache\.org/maven2/org/apache/ant/ant/)\), +1. published one `ant:ant:1.7.0` relocation POM in old groupId to advertise about the move \(see [repository content](https://repo\.maven\.apache\.org/maven2/ant/ant/1\.7\.0/)\)\. + +Notice that past `ant:ant` versions POMs \(until 1\.6\.5\) have not been modified to advertise about the move: Central POM content is not expected to be changed once published \(because initial content has been downloaded many times and is not expected to be re\-loaded later\)\. + +### Apache POI + +1. has published its releases until 3\.0\-alpha\-3 to Maven 1\-compliant `poi:poi` coordinates \(see [repository content](https://repo\.maven\.apache\.org/maven2/poi/poi/)\), +1. starting with 3\.0\-FINAL, moved to reverse\-DNS compliant Maven 2\+ `org.apache.poi:poi` coordinates, \(see [repository content](https://repo\.maven\.apache\.org/maven2/org/apache/poi/poi/)\), +1. published `poi:poi:3.0-FINAL` relocation POM **with jars** in old groupId to advertise about the move \(see [repository content](https://repo\.maven\.apache\.org/maven2/poi/poi/3\.0\-FINAL/)\)\. +1. published `poi:poi` relocation POMs for 3\.0\.1\-FINAL, 3\.0\.2\-beta1/beta2/FINAL and 3\.1\-beta1/beta2/FINAL in old groupId to advertise about the move \(see [repository content](https://repo\.maven\.apache\.org/maven2/poi/poi/)\)\. +### Testing + +Using `pom.xml` + +``` + + + 4.0.0 + + test + relocation-test + 1.0-SNAPSHOT + + + + ant + ant + 1.7.0 + + + poi + poi + 3.0-FINAL + + + +``` + +Dependency resolution of these relocated artifacts follows to the new relocated coordinates, issuing a warning: + +``` +$ mvn dependency:list dependency:tree +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------< test:relocation-test >------------------------ +[INFO] Building relocation-test 1.0-SNAPSHOT +[INFO] from pom.xml +[INFO] --------------------------------[ jar ]--------------------------------- +[WARNING] The artifact ant:ant:jar:1.7.0 has been relocated to org.apache.ant:ant:jar:1.7.0 +[WARNING] The artifact poi:poi:jar:3.0-FINAL has been relocated to org.apache.poi:poi:jar:3.0-FINAL +[INFO] +[INFO] --- dependency:3.6.0:list (default-cli) @ relocation-test --- +[INFO] +[INFO] The following files have been resolved: +[INFO] org.apache.ant:ant:jar:1.7.0:compile -- module ant (auto) +[INFO] org.apache.ant:ant-launcher:jar:1.7.0:compile -- module ant.launcher (auto) +[INFO] org.apache.poi:poi:jar:3.0-FINAL:compile -- module poi (auto) +[INFO] commons-logging:commons-logging:jar:1.1:compile -- module commons.logging (auto) +[INFO] log4j:log4j:jar:1.2.13:compile -- module log4j (auto) +[INFO] +[INFO] +[INFO] --- dependency:3.6.0:tree (default-cli) @ relocation-test --- +[WARNING] The artifact ant:ant:jar:1.7.0 has been relocated to org.apache.ant:ant:jar:1.7.0 +[WARNING] The artifact poi:poi:jar:3.0-FINAL has been relocated to org.apache.poi:poi:jar:3.0-FINAL +[INFO] test:relocation-test:jar:1.0-SNAPSHOT +[INFO] +- org.apache.ant:ant:jar:1.7.0:compile +[INFO] | \- org.apache.ant:ant-launcher:jar:1.7.0:compile +[INFO] \- org.apache.poi:poi:jar:3.0-FINAL:compile +[INFO] +- commons-logging:commons-logging:jar:1.1:compile +[INFO] \- log4j:log4j:jar:1.2.13:compile +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +``` + diff --git a/content/markdown/guides/mini/guide-repository-ssl.md b/content/markdown/guides/mini/guide-repository-ssl.md new file mode 100644 index 0000000000..2d4b8278ac --- /dev/null +++ b/content/markdown/guides/mini/guide-repository-ssl.md @@ -0,0 +1,123 @@ +--- +title: Remote repository access through authenticated HTTPS +author: + - Arnaud Bailly +date: 2005-11-11 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Remote repository access through authenticated HTTPS + +This document describes how to configure Maven to access a remote repository that sits behind an HTTPS server which requires client authentication with certificates\. + +## The problem + +There is a maven repository at `https://my.server.com/maven`\. This server only serves clients authenticated through SSL protocol by a valid certificate signed by an approved certificate authority's certificate which we call the `CACert`\. In the simplest case where the server is used internally by an identified community of users \(e\.g\. corporate intranet\), the server's certificate is the certificate authority as the server is used only internally\. + +So we assume that we have access to the trusted certificate in X\.509 format stored in a file named: + +``` + /somewhere/in/filesystem/CACert.cert +``` + +The client's certificate has been issued by some means not described in this document in PKCS\#12 format, which is the format that is accepted by browsers \(at least Firefox and Internet Explorer\) for import into their keystore\. This file is named: + +``` + /home/directory/mycertificate.p12 +``` + +and we assume it is accessible when launching maven\. This file contains the client's private key which may be very sensitive information so it is secured by a password: + +``` + CeRtPwD +``` + +The remote repository is referenced either through the `pom.xml` file: + +``` +maven.repo.remote=https://my.server.com/maven,http://www.ibiblio.org/maven +``` + +## The solution + +For maven to use this repository, we should take the following steps: + +1. Create a store to hold the server's certificate usings Oracle's [ keytool](https://docs\.oracle\.com/javase/8/docs/technotes/tools/unix/keytool\.html), +1. Define properties to be used by HttpClient for finding keys and certificate +### Storing certificate + +The following command line imports the certififcate authority's certificate into a JKS formatted key store named `trust.jks`, the _trust store_\. + +``` +$> keytool -v -alias mavensrv -import \ + -file /somewhere/in/filesystem/CACert.cert\ + -keystore trust.jks +Enter keystore password: +Owner: .... +Issuer: .... +Serial number: .... +Valid from: Mon Feb 21 22:34:25 CET 2005 until: Thu Feb 19 22:34:25 CET 2015 +Certificate fingerprints: + MD5: ....... + SHA1: ..... +Trust this certificate? [no]: yes +Certificate was added to keystore +[Storing trust.jks] +$> +``` + +Note that it should be possible to import a full chain of certificates with only one root certificate being trusted but the author did not test it\. + +### Setting properties + +The following properties must be set at start of maven to be accessible when HttpClient starts up\. + +
+
javax.net.ssl.trustStore
+
the path to the keystore where trusted certificates are stored
+
javax.net.ssl.trustStoreType
+
the type of storage for this store, maybe either jks (default) or pkcs12
+
javax.net.ssl.trustStorePassword
+
the password protecting the store
+
javax.net.ssl.keyStore
+
the path to the keystore where user's private key is stored
+
javax.net.ssl.keyStoreType
+
the type of storage for this store, maybe either jks (default) or pkcs12
+
javax.net.ssl.keyStorePassword
+
the password protecting the store
+
+ +Not all the properties must be set depending of your precise settings: type of store may left to default, password may be empty\. + +They may be set either on maven's command\-line, in `.mavenrc` file or in `MAVEN_OPTS` environment variable\. For the setting defined in this document, here is an example `.mavenrc` file: + +``` +MAVEN_OPTS="-Xmx512m -Djavax.net.ssl.trustStore=trust.jks \ + -Djavax.net.ssl.trustStorePassword= \ + -Djavax.net.ssl.keyStore=/home/directory/mycertificate.p12 \ + -Djavax.net.ssl.keyStoreType=pkcs12 \ + -Djavax.net.ssl.keyStorePassword=XXXXXX" +``` + +## Links + +The following links may be useful in understanding SSL infrastructure management in Java: + +- [ HttpClient](http://hc\.apache\.org/httpclient\-3\.x/sslguide\.html)'s SSL guide diff --git a/content/markdown/guides/mini/guide-reproducible-builds.md b/content/markdown/guides/mini/guide-reproducible-builds.md new file mode 100644 index 0000000000..19e06fec48 --- /dev/null +++ b/content/markdown/guides/mini/guide-reproducible-builds.md @@ -0,0 +1,108 @@ +--- +title: Guide to Configuring for Reproducible Builds +author: + - Hervé Boutemy +date: 2019-11-03 +--- + + + + + + + + + + + + + + + + + + + +# Configuring for Reproducible Builds + +## What are Reproducible Builds? + +[Reproducible builds](https://reproducible\-builds\.org/) are a set of software development practices that create an independently\-verifiable path from source to binary code\. A build is **reproducible** if given the same source code, build environment and build instructions, any party can recreate **bit\-by\-bit** identical copies of all specified artifacts\. + +[Reproducible Central](https://github\.com/jvm\-repo\-rebuild/reproducible\-central) lists projects releases that have been checked as reproducible by rebuilding independently from the reference build published in Central Repository\. + +## How do I configure my Maven build? + +There is no Maven version prerequisite\. Everything happens at plugin level: + +1. Upgrade your plugins to reproducible versions: to easily detect [required upgrades](/plugins/maven\-artifact\-plugin/plugin\-issues\.html), run + + ``` + mvn artifact:check-buildplan + ``` + +1. Enable Reproducible Builds mode for plugins, by adding [`project.build.outputTimestamp` property](https://cwiki\.apache\.org/confluence/pages/viewpage\.action?pageId=74682318\#Reproducible/VerifiableBuilds\-OutputArchiveEntriesTimestamp) to the project's `pom.xml`: + + ``` + + 2023-01-01T00:00:00Z + + ``` + +Notice: starting with Maven 4\.0\.0\-beta\-5, Reproducible Builds mode will be active by default \(see [MNG\-8258](https://issues\.apache\.org/jira/browse/MNG\-8258)\), without modifying project's `pom.xml`\. Setting a value in your `pom.xml` will only be useful if you want to override the inherited value\. + +You have the basics configured\. The output should be mostly reproducible now\. + +## How to test my Maven build reproducibility? + +Using [`maven-artifact-plugin`'s `compare` goal](/plugins/maven\-artifact\-plugin/compare\-mojo\.html), you can easily check that the second build of your project produce the same output than an initial build: + +1. build and `install` your project \(don't hesitate to customize arguments to better match your project\): + + ``` + mvn clean install + ``` + +1. rebuild \(`verify` only, without installing\) and check against the previous install: + + ``` + mvn clean verify artifact:compare + ``` + +Notice that this local test does NOT really prove that your build is yet reproducible by a third party, because it may still suffer from environment leaks \(username, current directory, \.\.\.\)\. But it is easy to do, and prevents basic non\-reproducible issues like timestamps\. Really checking reproducibility requires to rebuild from a completely different setup: this is harder to do, even if containers may ease the task\. + +## How to fix my Maven build reproducibility? + +If something is still not reproducible after initial setup and [automatic check from `artifact:check-buildplan`](/plugins/maven\-artifact\-plugin/plugin\-issues\.html): + +1. Use [diffoscope](https://diffoscope\.org/) to find the unstable output between builds\. The `artifact:buildinfo` goal proposes a command with path to files: just copy/paste to launch\. +1. Find the plugin that generated this output\. +1. Check if a reproducible version of the plugin is available\. If not, please open an issue to help plugin maintainers improving Reproducible Builds support at every plugin level\. +## More Details + +Reproducible Builds for Maven: + +- Require **no version ranges** in dependencies, +- Generally give **different results on Windows and Unix** because of different newlines\. \(carriage return linefeed on Windows, linefeed on Unixes\) +- Generally depend on the **major version of the JDK** used to compile\. \(Even with source/target defined, each major JDK version changes the generated bytecode\) + +For detailed explanations, see [Maven "Reproducible/Verifiable Builds" Wiki page](https://s\.apache\.org/reproducible\-builds)\. + +## FAQ + +- Q\. Can the `project.build.outputTimestamp` property in `pom.xml` be updated automatically at release time? + + A\. Yes\. + + Details depend on your release process tooling: + + - if you use [maven\-release\-plugin](/plugins/maven\-release\-plugin/), you'll need **version 3\.0\.0\-M1 or later**: it will automatically update the timestamp value in `pom.xml` during the release in the same commit that updates version, + - if you have a custom release process tooling, you'll need to add the feature to your release tooling\. Notice that if you're using `versions-maven-plugin` in custom release scripts, starting with release 2\.9\.0, [`versions:set` goal updates the property](https://github\.com/mojohaus/versions\-maven\-plugin/issues/453)\. + - instead of explicitly writing a timestamp in their `pom.xml`, some people tend to prefer using last Git commit timestamp, like `${git.commit.time}` from [git\-commit\-id\-maven\-plugin](https://github\.com/git\-commit\-id/git\-commit\-id\-maven\-plugin) \(with `UTC` to be independent from user's timezone\)\. + +Don't hesitate to share your questions or solutions on [user mailing\-list](/mailing\-lists\.html)\. + +- Q\. Which additional plugins need to be updated for Reproducible Builds? + + A\. See the list of [required upgrades](/plugins/maven\-artifact\-plugin/plugin\-issues\.html) + diff --git a/content/markdown/guides/mini/guide-site.md b/content/markdown/guides/mini/guide-site.md new file mode 100644 index 0000000000..bf1680d5fb --- /dev/null +++ b/content/markdown/guides/mini/guide-site.md @@ -0,0 +1,289 @@ +--- +title: Guide to creating a site +author: + - Brett Porter + - Jason van Zyl +date: 2015-07-18 +--- + + + + + + + + + + + + + + + + + + + +# Creating a site + +## Creating Content + +The first step to creating your site is to create some content\. In Maven, the site content is separated by format, as there are several available\. + +``` ++- src/ + +- site/ + +- apt/ + | +- index.apt + ! + +- markdown/ + | +- content.md + | + +- fml/ + | +- general.fml + | +- faq.fml + | + +- xdoc/ + | +- other.xml + | + +- site.xml +``` + +You will notice there is now a `${project.basedir}/src/site` directory within which is contained a `site.xml` site descriptor along with various directories corresponding to the supported document types\. + +Let's take a look at the examples of the various document types: + +- `apt`: the APT format, "Almost Plain Text", is a wiki\-like format that allows you to write simple, structured documents \(like this one\) very quickly\. A full reference of the [APT Format](/doxia/references/apt\-format\.html) is available, +- `markdown`: the well known [Markdown](https://en\.wikipedia\.org/wiki/Markdown) format, +- `fml`: the FML format is the [FAQ format](/doxia/references/fml\-format\.html), +- `xdoc`: an XML document conforming to a small and simple set of tags, see the [full reference](/doxia/references/xdoc\-format\.html)\. + +Other formats are available, but at this point these 4 are the best tested\. + +There are also several possible output formats, but as of Maven Site Plugin, only XHTML is available\. + +Note that all of the above is optional \- just one index file is required in one of the input trees\. Each of the paths will be merged together to form the root directory of the site\. + +## Customizing the Look & Feel + +If you want to tune the way your site looks, you can use a custom **skin** to provide your own CSS styles\. If that is still not enough, you can even tweak the output templates that Maven uses to generate the site documentation\. + +You can visit the [Skins index](/skins/) to have a look at some of the skins that you can use to change the look of your site\. + + + + +## Generating the Site + +Generating the site is very simple, and fast\! + +``` +mvn site +``` + +By default, the resulting site will be in `target/site/...` + +For more information on the Maven Site Plugin, see the [ maven\-site\-plugin reference](\.\./\.\./plugins/maven\-site\-plugin/)\. + +## Deploying the Site + +### Classical Website deployment + +To be able to deploy the site with a classical network protocol \(ftp, scp, webdav\), you must first declare a location to distribute to in your `pom.xml`, similar to the repository for deployment: + +``` + + ... + + + website + scp://www.mycompany.com/www/docs/project/ + + + ... + +``` + +- the `` element identifies the repository, so that you can attach credentials to it in your `settings.xml` file using the [ `` element](\.\./\.\./settings\.html\#Servers) as you would for any other repository, +- the `` gives the location to deploy to\. Currently, only SSH is supported by default, as above which copies to the host `www.mycompany.com` in the path `/www/docs/project/`, but you can [add more protocols as required](/plugins/maven\-site\-plugin/examples/adding\-deploy\-protocol\.html)\. If subprojects inherit the site URL from a parent POM, they will automatically get their `` appended to form their effective deployment location\. + +Once distribution location is configured, deploying the site is done by using the `site-deploy` phase of the site lifecycle\. + +``` +mvn site-deploy +``` + +### GitHub Pages, Apache svnpubsub/gitpubsub Deployment + +When site publication is done with a SCM commit, like with [GitHub Pages](https://pages\.github\.com/) or [Apache svnpubsub/gitpubsub](https://infra\.apache\.org/project\-site\.html\#tools), deploying the site will be done with [Maven SCM Publish Plugin](/plugins/maven\-scm\-publish\-plugin/)\. + +For example with a project hosted on GitHub and using GitHub Pages for its site publication: + +``` + + org.apache.maven.plugins + maven-scm-publish-plugin + 3.1.0 + + ${project.scm.developerConnection} + gh-pages + + +``` + +Deploying the site is done in 2 steps: + +1. staging the content by using the `site` phase of the site lifecycle followed by `site:stage`: `mvn site site:stage` +1. publishing the staged site to the SCM: `mvn scm-publish:publish-scm` +## Creating a Site Descriptor + +The `site.xml` file is used to describe the structure of the site\. A sample is given below: + +``` + + + + Maven + https://maven.apache.org/images/apache-maven-project.png + https://maven.apache.org/ + + + https://maven.apache.org/images/maven-small.gif + + + + + + + + + + + + + + + + + + + + + ... + + +``` + + + +**Note:** The `` element above\. When building the site, this is replaced by a menu with links to all the reports that you have configured\. + +More information about the site descriptor is available at the [dedicated page of Maven Site Plugin](/plugins/maven\-site\-plugin/examples/sitedescriptor\.html)\. + +## Adding Extra Resources + +You can add any arbitrary resource to your site by including them in a `resources` directory as shown below\. Additional CSS files will be picked up when they are placed in the `css` directory within the `resources` directory\. + +``` ++- src/ + +- site/ + +- resources/ + +- css/ + | +- site.css + | + +- images/ + +- pic1.jpg +``` + +The file `site.css` will be added to the default XHTML output, so it can be used to adjust the default Maven stylesheets if desired\. + +The file `pic1.jpg` will be available via a relative reference to the `images` directory from any page in your site\. + +## Configuring Reports + +Maven has several reports that you can add to your web site to display the current state of the project\. These reports take the form of plugins, just like those used to build the project\. + +There are many standard reports that are available by gleaning information from the POM\. Currently what is provided by default are: + +- Dependencies Report +- Mailing Lists +- Continuous Integration +- Source Repository +- Issue Tracking +- Project Team +- License + +To find out more please refer to the [Project Info Reports Plugin](\.\./\.\./plugins/maven\-project\-info\-reports\-plugin/)\. + +To add these reports to your site, you must add the Project Info Reports plugin to a special `` section in the POM\. The following example shows how to configure the standard project information reports that display information from the POM in a friendly format: + +``` + + ... + + + + org.apache.maven.plugins + maven-project-info-reports-plugin + 2.8 + + + + ... + +``` + +If you have included the appropriate `` tag in your `site.xml` descriptor, then when you regenerate the site those items will appear in the menu\. + +Many other plugins provide reporting goals: look for "R" \(Reporting\) value in the "Type" column of the [ list of plugins](/plugins/)\. When plugins are both Build and Reporting plugins, defining explicitly the version in the reporting section is usually not necessary since reporting will use the version from `build/plugins` or `build/pluginManagement`\. Since Maven Site Plugin 3\.4, reporting plugin also get configuration from `build/pluginManagement`\. + +**Note:** Many report plugins provide a parameter called `outputDirectory` or similar to specify the destination for their report outputs\. This parameter is only relevant if the report plugin is run standalone, i\.e\. by invocation directly from the command line\. In contrast, when reports are generated as part of the site, the configuration of the Maven Site Plugin will determine the effective output directory to ensure that all reports end up in a central location\. + + +## Internationalization + +Internationalization in Maven is very simple, as long as the reports you are using have that particular locale defined\. For an overview of supported languages and instructions on how to add further languages, please see the related article [ Internationalization](\.\./\.\./plugins/maven\-site\-plugin/i18n\.html) from the Maven Site Plugin\. + +To enable multiple locales, add a configuration similar to the following to your POM: + +``` + + ... + + + + org.apache.maven.plugins + maven-site-plugin + 3.4 + + en,fr + + + + + ... + +``` + +This will generate both an English and a French version of the site\. If `en` is your current locale, then it will be generated at the root of the site, with a copy of the French translation of the site in the `fr/` subdirectory\. + +To add your own content for that translation instead of using the default, place a subdirectory with that locale name in your site directory and create a new site descriptor with the locale in the file name\. For example: + +``` ++- src/ + +- site/ + +- apt/ + | +- index.apt (Default version) + | + +- fr/ + | +- apt/ + | +- index.apt (French version) + | + +- site.xml (Default site descriptor) + +- site_fr.xml (French site descriptor) +``` + +With one site descriptor per language, the translated site\(s\) can evolve independently\. + diff --git a/content/markdown/guides/mini/guide-snippet-macro.md b/content/markdown/guides/mini/guide-snippet-macro.md new file mode 100644 index 0000000000..129a819fe4 --- /dev/null +++ b/content/markdown/guides/mini/guide-snippet-macro.md @@ -0,0 +1,97 @@ +--- +title: Guide to the Snippet Macro +author: + - Wendy Smoak +date: 2014-08-20 +--- + + + + + + + + + + + + + + + + + + + + +# Guide to the Snippet Macro + +When generating your project website with Maven, you have the option of dynamically including _snippet_s of source code in your pages\. + +A _snippet_ is a section of a source code file that is surrounded by specially formatted comments\. + +This functionality is inspired by the [Confluence](http://www\.atlassian\.com/software/confluence/) snippet macro, and is provided by the Maven Doxia project by way of the Maven Site Plugin\. + +To include snippets of source code in your documentation, first add comments in the source document surrounding the lines you want to include, and then refer to the snippet by its id in the documentation file\. Each snippet must be assigned an id, and the id must be unique within the source document\. The id parameter is not required if you want to include the entire file\. + +Following are examples of snippets in various source documents, as well as the corresponding macros in the APT documentation format\. + +See the Doxia [Macros Guide](/doxia/macros/index\.html\#Snippet\_Macro) for more information and examples\. + +## Snippets in Sources + +### Java + +``` + // START SNIPPET: snip-id + public static void main( String[] args ) + { + System.out.println( "Hello World!" ); + } + // END SNIPPET: snip-id +``` + +### XML + +``` + + + /logon.jsp + + success + /mainMenu.jsp + + + +``` + +### JSP + +``` + <%-- START SNIPPET: snip-id --%> + + <%-- END SNIPPET: snip-id --%> +``` + +## Snippets in Documentation + +### APT + +``` + %{snippet|id=snip-id|url=http://svn.example.com/path/to/Sample.java} + + %{snippet|id=snip-id|url=file:///path/to/Sample.java} +``` + +As of doxia\-core version 1\.0\-alpha\-9, a 'file' parameter is also available\. If a full path is not specified, the location is assumed to be relative to $\{project\.basedir\}\. + +``` + ~~ Since doxia-core 1.0-alpha-9 + %{snippet|id=abc|file=src/main/webapp/index.jsp} +``` + +- Macros in apt **must not** be indented\. +- Exactly one of `url` or `file` **must** be specified\. diff --git a/content/apt/guides/mini/guide-using-ant.apt b/content/markdown/guides/mini/guide-using-ant.md similarity index 55% rename from content/apt/guides/mini/guide-using-ant.apt rename to content/markdown/guides/mini/guide-using-ant.md index d75d359b32..d62d58ce89 100644 --- a/content/apt/guides/mini/guide-using-ant.apt +++ b/content/markdown/guides/mini/guide-using-ant.md @@ -1,37 +1,33 @@ - ------ - Guide to using Ant with Maven - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ +--- +title: Guide to using Ant with Maven +author: + - Jason van Zyl +date: 2005-10-12 +--- -~~ 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. + + + + + + + + + + + + + + + + + + +# Guide to using Ant with Maven -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html +The example above illustrates how to bind an ant script to a lifecycle phase\. You can add a script to each lifecycle phase, by duplicating the _execution/_ section and specifying a new phase\. -Guide to using Ant with Maven - - The example above illustrates how to bind an ant script to a lifecycle phase. You can add a script to each lifecycle - phase, by duplicating the section and specifying a new phase. - -+----+ +``` 4.0.0 @@ -66,12 +62,11 @@ Guide to using Ant with Maven +``` -+----+ - - So a concrete example would be something like the following: +So a concrete example would be something like the following: -+----+ +``` 4.0.0 @@ -105,5 +100,5 @@ Guide to using Ant with Maven +``` -+----+ diff --git a/content/markdown/guides/mini/guide-using-extensions.md b/content/markdown/guides/mini/guide-using-extensions.md new file mode 100644 index 0000000000..2174e1727f --- /dev/null +++ b/content/markdown/guides/mini/guide-using-extensions.md @@ -0,0 +1,92 @@ +--- +title: Guide to using Extensions +author: + - Jason van Zyl + - Konrad Windszus +date: 2022-11-16 +--- + + + + + + + + + + + + + + + + + + + +# Using Extensions + +Extensions are a way to add classes to either the [Core Classloader](\./guide\-maven\-classloading\.html\#Core\_Classloader) \(Core Extensions\) or the [Project Classloader](\./guide\-maven\-classloading\.html\#Project\_Classloaders) \(Build Extensions\)\. This is necessary for adjusting Maven in a way that affects more than just one plug\-in\. + +The mechanism allows extensions to either replace default [Sisu components](https://www\.eclipse\.org/sisu/) with custom ones or add new components which are used at run time\. In addition one could also expose additional packages from the Core Classloader\. + +Extensions are typically used to enable [Wagon providers](\.\./\.\./wagon/wagon\-providers/), used for the transport of artifact between repositories, and plug\-ins which [provide lifecycle enhancements](\.\./\.\./examples/maven\-3\-lifecycle\-extensions\.html)\. + +## Loading Extensions + +There are different means of loading extensions depending on the type\. There are _core extensions_ which are loaded **early** and build extensions which are loaded **late**\. Some extensions require early loading as they fundamentally change Maven behaviour\. An extension's documentation should indicate whether it provides a core or a build extension\. + +### Core Extension + +- Registered via extension jar in `${maven.home}/lib/ext` +- Registered via CLI argument `mvn -Dmaven.ext.class.path=extension.jar` +- Registered via [`.mvn/extensions.xml` file](\.\./\.\./configure\.html\#mvn\-extensions\-xml\-file) +### Build Extension + +- Registered via [`project->build->plugins->plugin`](\.\./\.\./pom\.html\#Plugins) with element `extensions` being set to `true`\. This is useful for regular plug\-ins carrying some extensions\. + + Example: + + ``` + + + ... + + + + org.apache.felix + maven-bundle-plugin + true + + ... + + + + + ... + + + ``` + +- Registered as build extension in [`project->build->extensions->extension`](\.\./\.\./pom\.html\#Extensions) + + Example: + + ``` + + + ... + + + + org.apache.maven.wagon + wagon-ftp + 2.10 + + + + ... + + + ``` + diff --git a/content/markdown/guides/mini/guide-using-modello.md b/content/markdown/guides/mini/guide-using-modello.md new file mode 100644 index 0000000000..424d2ad56e --- /dev/null +++ b/content/markdown/guides/mini/guide-using-modello.md @@ -0,0 +1,303 @@ +--- +title: Guide to using Modello +author: + - Jason van Zyl + - Hervé Boutemy +date: 2009-03-01 +--- + + + + + + + + + + + + + + + + + + + +# Guide to using Modello + +[Modello](https://codehaus\-plexus\.github\.io/modello/) is a tool for generating resources from a simple model\. From a [simple model](https://codehaus\-plexus\.github\.io/modello/modello\.html) you can generate things like: + +- Java sources +- XML serialization code for the model +- XML deserialization code for model +- Model documentation +- XSD + +A typical modello model looks like the following: + +``` + + archetype-descriptor + ArchetypeDescriptor + + This is a reference for the Archetype descriptor used to describe archetypes's metadata.

+

The metadata about an archetype is stored in the archetype-metadata.xml file located + in the META-INF/maven directory of its jar file.

]]> + + + + + package + org.apache.maven.archetype.metadata + + + + + + ArchetypeDescriptor + 1.0.0+ + AbstractArchetypeDescriptor + + + name + 1.0.0+ + String + true + Name of the Archetype, that will be displayed to the user when choosing an archetype. + + + partial + 1.0.0+ + boolean + false + Is this archetype representing a full Maven project or only parts? + + + requiredProperties + 1.0.0+ + List of required properties to generate a project from this archetype. + + RequiredProperty + * + + + + + + + ModuleDescriptor + 1.0.0+ + AbstractArchetypeDescriptor + + + id + 1.0.0+ + String + true + The module's artifactId. + + + dir + 1.0.0+ + String + true + The module's directory. + + + name + 1.0.0+ + String + true + The module's name. + + + + + + AbstractArchetypeDescriptor + 1.0.0+ + + + fileSets + 1.0.0+ + + FileSet + * + + true + File sets definition. + + + modules + 1.0.0+ + + ModuleDescriptor + * + + false + Modules definition. + + + + + + FileSet + 1.0.0+ + __property__ pattern, it is replaced with corresponding property value. + ]]> + + + filtered + 1.0.0+ + boolean + false + Velocity templates. + They can be non-filtered, which means the selected files will be copied without modification. + ]]> + + + packaged + 1.0.0+ + boolean + false + Filesets can be packaged, which means the selected files will be generated/copied in a directory + structure that is prepended by the package property. They can be non-packaged, which means that the selected + files will be generated/copied without that prepend. + + + encoding + 1.0.0+ + String + false + Encoding to use when filtering content. + + + directory + 1.0.0+ + String + false + + The directory where the files will be searched for, which is also the directory where the + project's files will be generated. + + + includes + 1.0.0+ + + String + * + + false + Inclusion definition "à la" Ant. + + + excludes + 1.0.0+ + + String + * + + false + Exclusion definition "à la" Ant. + + + + + + + + + + + RequiredProperty + 1.0.0+ + Definition of a property required when generating a project from this archetype. + + + key + 1.0.0+ + String + true + Key value of the property. + + + defaultValue + String + false + Default value of the property. + + + validationRegex + 1.1.0+ + String + false + A regular expression used to validate the property. + + + + + +``` + +To utilize Modello, you would configure the `modello-maven-plugin` something like the following where you want to generate the Java sources for the model, the xpp3 serialization code and the xpp3 deserialization code \(see [modello\-plugin\-xpp3](https://codehaus\-plexus\.github\.io/modello/modello\-plugins/modello\-plugin\-xpp3/) for more details\): + +``` + + + ... + + + + org.codehaus.modello + modello-maven-plugin + 1.8.3 + + + + + xpp3-reader + + xpp3-writer + + java + + + + + + src/main/mdo/archetype-descriptor.mdo + + 1.0.0 + true + + + + + ... + +``` + diff --git a/content/markdown/guides/mini/guide-using-one-source-directory.md b/content/markdown/guides/mini/guide-using-one-source-directory.md new file mode 100644 index 0000000000..fcb5c41e53 --- /dev/null +++ b/content/markdown/guides/mini/guide-using-one-source-directory.md @@ -0,0 +1,164 @@ +--- +title: Guide to Using Maven when You Can't Use the Conventions +author: + - Brett Porter +date: 2005-12-05 +--- + + + + + + + + + + + + + + + + + + + +# 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\. + +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 than 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? + +\.\.\. + + +### How do I do this? + +\.\.\. + + +### 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 Guide](\.\./getting\-started/) + + + +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: + +``` + + my-parent + pom + ... + + core + module + + +``` + +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\. + +``` + + 4.0.0 + + my-groupId + my-parent + 1.0-SNAPSHOT + + + my-core + + + ../src/main/java + + + + maven-compiler-plugin + 2.0.2 + + **/core/** + + + + + +``` + +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 \(i\.e\., 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 \(e\.g\., just a subset of classes, or the same JAR with debugging enabled\), Maven supports this using profiles\. See [ Introduction to Profiles](\.\./introduction/introduction\-to\-profiles\.html) for more information\. diff --git a/content/markdown/guides/mini/guide-using-toolchains.md b/content/markdown/guides/mini/guide-using-toolchains.md new file mode 100644 index 0000000000..0009829e5a --- /dev/null +++ b/content/markdown/guides/mini/guide-using-toolchains.md @@ -0,0 +1,144 @@ +--- +title: Guide to Using Toolchains +author: + - Maria Odea Ching + - Dennis Lundberg + - Karl Heinz Marbaise +date: 2016-03-08 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Using Toolchains + +## What are Toolchains? + +Maven Toolchains provide a way for a project to specify the JDK \(or other tools\) used to build the project, without needing to configure this in each plugin or in every `pom.xml`\. + +When Maven Toolchains are used to specify the JDK, a project can be built by a specific version of the JDK independent of the one Maven is running with\. This is similar to how JDK versions can be set in IDEs like IDEA, NetBeans and Eclipse\. + +### Prerequisites + +For more details about Toolchains' design and implementation, see [Toolchains](https://cwiki\.apache\.org/confluence/display/MAVENOLD/Toolchains)\. + +Below are some plugins which are toolchain\-aware, with the toolchain\-type used: + +|Toolchain type|**Plugin**|**Starting with**|**Hosted at**| +|:---:|---|---|---| +|jdk|[`maven-compiler-plugin`](/plugins/maven\-compiler\-plugin/)|2\.1|Apache Maven| +|jdk|[`maven-jarsigner-plugin`](/plugins/maven\-jarsigner\-plugin/)|1\.3|Apache Maven| +|jdk|[`maven-javadoc-plugin`](/plugins/maven\-javadoc\-plugin/)|2\.5|Apache Maven| +|jdk|[`maven-pmd-plugin`](/plugins/maven\-pmd\-plugin/)|3\.14\.0|Apache Maven| +|jdk|[`maven-surefire-plugin`](/plugins/maven\-surefire\-plugin/)|2\.5|Apache Maven| +|jdk|[`maven-failsafe-plugin`](/plugins/maven\-failsafe\-plugin/)|2\.5|Apache Maven| +|jdk|[`animal-sniffer-maven-plugin`](https://www\.mojohaus\.org/animal\-sniffer/animal\-sniffer\-maven\-plugin/)|1\.3|MojoHaus| +|jdk|[`cassandra-maven-plugin`](https://www\.mojohaus\.org/cassandra\-maven\-plugin/)|0\.7\.0\-1|MojoHaus| +|jdk|[`exec-maven-plugin`](https://www\.mojohaus\.org/exec\-maven\-plugin/)|1\.1\.1|MojoHaus| +|jdk|[`jdiff-maven-plugin`](https://www\.mojohaus\.org/jdiff\-maven\-plugin/)|1\.0\-beta\-1\-SNAPSHOT|MojoHaus| +|jdk|[`keytool-maven-plugin`](https://www\.mojohaus\.org/keytool/keytool\-maven\-plugin/)|1\.4|MojoHaus| +|protobuf|[`protobuf-maven-plugin`](https://www\.xolstice\.org/protobuf\-maven\-plugin/examples/protobuf\-toolchain\.html)|0\.6\.1|github| +## Using Toolchains in Your Project + +There are two essential components that you need to configure in order to use toolchains: + +1. the [`maven-toolchains-plugin`](/plugins/maven\-toolchains\-plugin/) in your project POM, +1. the [`toolchains.xml`](/ref/current/maven\-core/toolchains\.html) file on the building machine\. + +The `maven-toolchains-plugin` is the one that sets the toolchain to be used by the toolchain\-aware plugins in your project\. + +For example, you want to use a different JDK version to build your project than the version used to run Maven, you can configure the version you want to use via this plugin as shown in the `pom.xml` below: + +``` + + ... + + org.apache.maven.plugins + maven-compiler-plugin + 3.1 + + + org.apache.maven.plugins + maven-toolchains-plugin + 1.1 + + + + toolchain + + + + + + + 1.8 + openjdk + + + + + ... + +``` + +As you can see in the example above, a JDK toolchain with `` "1\.8" and `` "openjdk" is to be used\. Now how does the plugin know where this JDK is installed? This is where the `toolchains.xml` file comes in\. + +The `toolchains.xml` file \(see below\) is the configuration file where you set the installation paths of your toolchains\. This file should be put in the `${user.home}/.m2` directory\. When the `maven-toolchains-plugin` executes, it looks for the `toolchains.xml` file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin\. In this example, that is a JDK toolchain with `` "1\.8" and `` "openjdk"\. Once a match is found, the plugin then stores the toolchain to be used in the MavenSession\. As you can see in the `toolchains.xml` below, there is indeed a JDK toolchain with `` "1\.8" and `` "openjdk" configured\. So when the `maven-compiler-plugin` configured in the `pom.xml` above executes, it sees that a JDK toolchain is set in the MavenSession and will use that toolchain \(that would be the JDK installed at `/path/to/jdk/1.8` in this example\) to compile the sources\. + +Starting with [Maven 3\.3\.1](/docs/3\.3\.1/release\-notes\.html) you can put the `toolchains.xml` file wherever you like by using the `--global-toolchains file` option, but it is recommended to locate it into `${user.home}/.m2/`\. + +``` + + + + + jdk + + 1.8 + openjdk + + + /path/to/jdk/1.8 + + + + jdk + + 17 + azul + + + /path/to/jdk/17 + + + + + + netbeans + + 5.5 + + + /path/to/netbeans/5.5 + + + +``` + +You can configure as many toolchains as you want in your `toolchains.xml` file\. + diff --git a/content/markdown/guides/mini/guide-wagon-providers.md b/content/markdown/guides/mini/guide-wagon-providers.md new file mode 100644 index 0000000000..500fc6d891 --- /dev/null +++ b/content/markdown/guides/mini/guide-wagon-providers.md @@ -0,0 +1,77 @@ +--- +title: Guide to Selecting Alternative Wagon Providers +author: + - John Casey +date: 2009-07-13 +--- + + + + + + + + + + + + + + + + + + + +# Guide to Selecting Alternative Wagon Providers + +By default, Maven uses the `java.net.URLConnection` \(`HttpURLConnection`\) classes provided with the JDK to access repositories that use the HTTP/HTTPs protocols\. Unfortunately, since this implementation contains certain bugs, Maven users may find themselves unable to connect to servers that demand some configurations\. A couple examples of weird behavior include line\-wrapping the Authorization header's Base64 value when passwords are long, and using cached values in preemptive authentication for successive connections to the same server\. + +Maven 2\.2\.0 attempted to amend this problem by switching over to a Wagon implementation that's based on Apache HttpClient\. Unfortunately, it soon became apparent that HttpClient doesn't support NTLM \(at least, version 2\), which effectively means users behind NTLMv2 proxies cannot use Maven 2\.2\.0\. + +To hopefully resolve this once and for all, Maven 2\.2\.1 will contain support for specifying which Wagon provider you want to use for a given protocol during the build\. The provider name will then be appended to the protocol using the format `-` to form the component role\-hint for the Wagon\. + +As of Maven 2\.2\.1, there are two ways to specify which Wagon provider should be used: via the command line, or in the `` configuration section of the `settings.xml`\. + +## Command\-Line Configuration + +To specify the Wagon provider from the command line, simply use the `-Dmaven.wagon.provider.=` command\-line option, like the following: + +``` +mvn -Dmaven.wagon.provider.http=httpclient clean install +``` + +This instructs Maven to use the HttpClient\-based Wagon implementation for connections to HTTP repositories\. + +## `settings.xml` Configuration + +To specify which Wagon provider to use for a particular server, modify your `settings.xml` file to add the `` configuration to your `` entry, like the following: + +``` + + [...] + + + central + + httpclient + [...] + + +``` + +## Available Wagon Providers + +Maven 2\.2\.1 provides two providers for HTTP/HTTPS Wagons: `lightweight` and `httpclient`\. If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the extension binds its Wagon components to role\-hints of the form `-` in order to allow users to specify your alternative Wagon provider\. For instance, the HttpClient HTTP Wagon component definition looks like this: + +``` + + org.apache.maven.wagon.Wagon + http-httpclient + org.apache.maven.wagon.providers.http.HttpWagon + per-lookup + +``` + +**NOTE:** The default provider for HTTP/HTTPS Wagons is `lightweight`\. + diff --git a/content/markdown/maven-features.md b/content/markdown/maven-features.md new file mode 100644 index 0000000000..e2f6b398b5 --- /dev/null +++ b/content/markdown/maven-features.md @@ -0,0 +1,41 @@ +--- +title: Maven Features +author: + - Jason van Zyl +date: 2005-10-12 +--- + + + + + + + + + + + + + + + + + + +# Feature Summary + +The following are the key features of Maven in a nutshell: + +- Simple project setup that follows best practices \- get a new project or module started in seconds +- Consistent usage across all projects \- means no ramp up time for new developers coming onto a project +- Superior dependency management including automatic updating, dependency closures \(also known as transitive dependencies\) +- Able to easily work with multiple projects at the same time +- A [large and growing repository of libraries and metadata](/repository/) to use out of the box, and arrangements in place with the largest Open Source projects for real\-time availability of their latest releases +- Extensible, with the ability to easily [write plugins](/plugin\-developers/) in Java or scripting languages +- Instant access to new features with little or no extra configuration +- Ant tasks for dependency management and deployment outside of Maven +- Model based builds: Maven is able to build any number of projects into predefined output types such as a JAR, WAR, or distribution based on metadata about the project, without the need to do any scripting in most cases\. +- Coherent site of project information: Using the same metadata as for the build process, Maven is able to generate a web site or PDF including any documentation you care to add, and adds to that standard reports about the state of development of the project\. Examples of this information can be seen at the bottom of the left\-hand navigation of this site under the "Project Information" and "Project Reports" submenus\. +- Release management and distribution publication: Without much additional configuration, Maven will integrate with your source control system \(such as Subversion or Git\) and manage the release of a project based on a certain tag\. It can also publish this to a distribution location for use by other projects\. Maven is able to publish individual outputs such as a JAR, an archive including other dependencies and documentation, or as a source distribution\. +- Dependency management: Maven encourages the use of a central repository of JARs and other dependencies\. Maven comes with a mechanism that your project's clients can use to download any JARs required for building your project from a central JAR repository much like Perl's CPAN\. This allows users of Maven to reuse JARs across projects and encourages communication between projects to ensure that backward compatibility issues are dealt with\. + diff --git a/content/markdown/plugin-developers/common-bugs.md b/content/markdown/plugin-developers/common-bugs.md new file mode 100644 index 0000000000..0f18552982 --- /dev/null +++ b/content/markdown/plugin-developers/common-bugs.md @@ -0,0 +1,315 @@ +--- +title: Common Bugs and Pitfalls +author: + - Benjamin Bentmann +date: 2008-08-29 +--- + + + + + + + + + + + + + + + + + + + +# Common Bugs and Pitfalls + +Maven is not the smallest project in terms of source code and has as such already suffered from many bugs\. Having a closer look at all the issues revealed some coding problems that had widespread among the various subcomponents\. This document lists these commonly occurring anti patterns in order to help the Maven community to prevent rather than fix bugs\. Note that the primary focus is on pointing out problems that are subtle in their nature rather than giving a comprehensive guide for Java or Maven development\. + +- [Reading and Writing Text Files](Reading\_and\_Writing\_Text\_Files) +- [Converting between URLs and Filesystem Paths](Converting\_between\_URLs\_and\_Filesystem\_Paths) +- [Handling Strings Case\-insensitively](Handling\_Strings\_Case\-insensitively) +- [Creating Resource Bundle Families](Creating\_Resource\_Bundle\_Families) +- [Using System Properties](Using\_System\_Properties) +- [Using Shutdown Hooks](Using\_Shutdown\_Hooks) +- [Resolving Relative Paths](Resolving\_Relative\_Paths) +- [Determining the Output Directory for a Site Report](Determining\_the\_Output\_Directory\_for\_a\_Site\_Report) +- [Retrieving the Mojo Logger](Retrieving\_the\_Mojo\_Logger) +## Reading and Writing Text Files + +Textual content is composed of characters while file systems merely store byte streams\. A file encoding \(aka charset\) is used to convert between bytes and characters\. The challenge is using the right file encoding\. + +The JVM has this notion of a default encoding \(given by the `file.encoding` property\) which it derives from a system's locale\. While this might be a convenient feature sometimes, using this default encoding for a project build is in general a bad idea: The build output will depend on the machine/developer who runs the build\. As such, usage of the default encoding threatens the dream of a reproducible build\. + +For example, if developer A has UTF\-8 as default encoding while developer B uses ISO\-8859\-1, text files are very likely to get messed up during resource filtering or similar tasks\. + +Therefore, developers should avoid any direct or indirect usage of the classes/methods that simply employ the platform's default encoding\. For instance, `FileWriter` and `FileReader` should usually be avoided: + +``` +/* + * FIXME: This assumes the source file is using the platform's default encoding. + */ +Reader reader = new FileReader( javaFile ); +``` + +Instead, the classes `OutputStreamWriter` and `OutputStreamReader` can be used in combination with an explicit encoding value\. This encoding value can be retrieved from a mojo parameter such that the user can configure the plugin to fit his/her needs\. + +To save the user from configuring each plugin individually, conventions have been established that allow a user to centrally configure the file encoding per POM\. Plugin developers should respect these conventions whereever possible: + +- [Source File Encoding](https://cwiki\.apache\.org/confluence/display/MAVEN/POM\+Element\+for\+Source\+File\+Encoding) +- [Report Output Encoding](http://cwiki\.apache\.org/confluence/display/MAVENOLD/Reporting\+Encoding\+Configuration) + +Finally note that XML files require special handling because they are equipped with an encoding declaration in the XML prolog\. Reading or writing XML files with an encoding that does not match their XML prolog's `encoding` attribute is a bad idea: + +``` +/* + * FIXME: This assumes the XML encoding declaration matches the platform's default encoding. + */ +Writer writer = new FileWriter( xmlFile ); +writer.write( xmlContent ); +``` + +To ease the correct processing of XML files, developers are encouraged to use [`ReaderFactory.newXmlReader()`](https://codehaus\-plexus\.github\.io/plexus\-utils/apidocs/org/codehaus/plexus/util/ReaderFactory\.html\#newXmlReader\(java\.io\.File\)) and [`WriterFactory.newXmlWriter()`](https://codehaus\-plexus\.github\.io/plexus\-utils/apidocs/org/codehaus/plexus/util/WriterFactory\.html\#newXmlWriter\(java\.io\.File\)) from the Plexus Utilities\. + +## Converting between URLs and Filesystem Paths + +URLs and filesystem paths are really two different things and converting between them is not trivial\. The main source of problems is that different encoding rules apply for the strings that make up a URL or filesystem path\. For example, consider the following code snippet and its associated console output: + +``` +File file = new File( "foo bar+foo" ); +URL url = file.toURI().toURL(); + +System.out.println( file.toURL() ); +> file:/C:/temp/foo bar+foo + +System.out.println( url ); +> file:/C:/temp/foo%20bar+foo + +System.out.println( url.getPath() ); +> /C:/temp/foo%20bar+foo + +System.out.println( URLDecoder.decode( url.getPath(), "UTF-8" ) ); +> /C:/temp/foo bar foo +``` + +First of all, please note that [`File.toURL()`](http://java\.sun\.com/javase/6/docs/api/java/io/File\.html\#toURL\(\)) does not escape the space character \(and others\)\. This yields an invalid URL, as per [RFC 2396, section 2\.4\.3 "Excluded US\-ASCII Characters"](http://www\.faqs\.org/rfcs/rfc2396\.html)\. The class `java.net.URL` will silently accept such invalid URLs, in contrast `java.net.URI` will not \(see also [`URL.toURI()`](http://java\.sun\.com/javase/6/docs/api/java/net/URL\.html\#toURI\(\))\)\. For this reason, `File.toURL()` has been deprecated and should be replaced with `File.toURI().toURL()`\. + +Next, [`URL.getPath()`](http://java\.sun\.com/javase/6/docs/api/java/net/URL\.html\#getPath\(\)) does in general not return a string that can be used as a filesystem path\. It returns a substring of the URL and as such can contain escape sequences\. The prominent example is the space character which will show up as "%20"\. People sometimes hack around this by means of `replace("%20", " ")` but that does simply not cover all cases\. It's worth to mention that on the other hand the related method [`URI.getPath()`](http://java\.sun\.com/javase/6/docs/api/java/net/URI\.html\#getPath\(\)) does decode escapes but still the result is not a filesystem path \(compare the source for the constructor `File(URI)`\)\. To summarize, the following idiom is to be avoided: + +``` +URL url = new URL( "file:/C:/Program%20Files/Java/bin/java.exe" ); + +/* + * FIXME: This does not decode percent encoded characters. + */ +File path = new File( url.getPath() ); +``` + +To decode a URL, people sometimes also choose [`java.net.URLDecoder`](http://java\.sun\.com/javase/6/docs/api/java/net/URLDecoder\.html)\. The pitfall with this class is that is actually performs HTML form decoding which is yet another encoding and not the same as the URL encoding \(compare the last paragraph in class javadoc about [`java.net.URL`](http://java\.sun\.com/javase/6/docs/api/java/net/URL\.html)\)\. For instance, a `URLDecoder` will erroneously convert the character "\+" into a space as illustrated by the last sysout in the example above\. + +In an ideal world, code targetting JRE 1\.4\+ could easily avoid these problems by using the constructor [`File(URI)`](http://java\.sun\.com/javase/6/docs/api/java/io/File\.html\#File\(java\.net\.URI\)) as suggested by the following snippet: + +``` +URL url = new URL( "file:/C:/Documents and Settings/user/.m2/settings.xml" ); + +/* + * FIXME: This assumes the URL is fully compliant with RFC 3986. + */ +File path = new File( new URI( url.toExternalForm() ) ); +``` + +The remaining source of frustration is the conversion from `URL` to `URI`\. As already said, the `URL` class accepts malformed URLs which will make the constructor of `URI` throw an exception\. And indeed, class loaders from Sun JREs up to Java 1\.4 will deliver malformed URLs when queried for a resource\. Likewise, the class loaders employed by Maven 2\.x deliver malformed resource URLs regardless of the JRE version \(see [MNG\-3607](https://issues\.apache\.org/jira/browse/MNG\-3607)\)\. + +For all these reasons, it is recommended to use [`FileUtils.toFile()`](http://commons\.apache\.org/io/api\-release/org/apache/commons/io/FileUtils\.html\#toFile\(java\.net\.URL\)) from Commons IO or [`FileUtils.toFile()`](https://codehaus\-plexus\.github\.io/plexus\-utils/apidocs/org/codehaus/plexus/util/FileUtils\.html\#toFile\(java\.net\.URL\)) from a recent Plexus Utilities\. + +## Handling Strings Case\-insensitively + +When developers need to compare strings without regard to case or want to realize a map with case\-insensitive string keys, they often employ [`String.toLowerCase()`](http://java\.sun\.com/javase/6/docs/api/java/lang/String\.html\#toLowerCase\(\)) or [`String.toUpperCase()`](http://java\.sun\.com/javase/6/docs/api/java/lang/String\.html\#toUpperCase\(\)) to create a "normalized" string before doing a simple `String.equals()`\. Now, the `to*Case()` methods are overloaded: One takes no arguments and one takes a `Locale` object\. + +The gotcha with the arg\-less methods is that their output depends on the default locale of the JVM but the default locale is out of control of the developer\. That means the string expected by the developer \(who runs/tests his code in a JVM using locale `xy`\) does not necessarily match the string seen by another user \(that runs a JVM with locale `ab`\)\. For example, the comparison shown in the next code snippet is likely to fail for systems with default locale Turkish because Turkish has unusual casing rules for the characters "i" and "I": + +``` +/* + * FIXME: This assumes the casing rules of the current platform + * match the rules for the English locale. + */ +if ( "info".equals( debugLevel.toLowerCase() ) ) + logger.info( message ); +``` + +For case\-insensitive string comparisons which should be locale\-insensitive, the method [`String.equalsIgnoreCase()`](http://java\.sun\.com/javase/6/docs/api/java/lang/String\.html\#equalsIgnoreCase\(java\.lang\.String\)) should be used instead\. If only a substring like a prefix/suffix should be compared, the method [`String.regionMatches()`](http://java\.sun\.com/javase/6/docs/api/java/lang/String\.html\#regionMatches\(boolean,%20int,%20java\.lang\.String,%20int,%20int\)) can be used instead\. + +If the usage of `String.to*Case()` cannot be avoided, the overloaded version taking a `Locale` object should be used, passing in [`Locale.ENGLISH`](http://java\.sun\.com/javase/6/docs/api/java/util/Locale\.html\#ENGLISH)\. The resulting code will still run on Non\-English systems, the parameter only locks down the casing rules used for the string comparison such that the code delivers the same results on all platforms\. + +## Creating Resource Bundle Families + +Especially reporting plugins employ resource bundles to support internationalization\. One language \(usually English\) is provided as the fallback/default language in the base resource bundle\. Due to the lookup strategy performed by [`ResourceBundle.getBundle()`](http://java\.sun\.com/javase/6/docs/api/java/util/ResourceBundle\.html\#getBundle\(java\.lang\.String,%20java\.util\.Locale,%20java\.lang\.ClassLoader\)), one must always provide a dedicated resource bundle for this default language, too\. This bundle should be empty because it inherits the strings via the parent chain from the base bundle, but it must exist\. + +The following example illustrates this requirement\. Imagine the broken resource bundle family shown below which is intended to provide localization for English, German and French: + +``` +src/ ++- main/ + +- resources/ + +- mymojo-report.properties + +- mymojo-report_de.properties + +- mymojo-report_fr.properties +``` + +Now, if a resource bundle is to be looked up for English on a JVM whose default locale happens to be French, the bundle `mymojo-report_fr.properties` will be loaded instead of the intended bundle `mymojo-report.properties`\. + +Reporting plugins that suffer from this bug can easily be detected by executing `mvn site -D locales=xy,en` where `xy` denotes any other language code supported by the particular plugin\. Specifying `xy` as the first locale will have the Maven Site Plugin change the JVM's default locale to `xy` which in turn causes the lookup for `en` to fail as outlined above unless the plugin has a dedicated resource bundle for English\. + +## Using System Properties + +Maven's command line supports the definition of system properties via arguments of the form `-D key=value`\. While these properties are called system properties, plugins should never use [`System.getProperty()`](http://java\.sun\.com/javase/6/docs/api/java/lang/System\.html\#getProperty\(java\.lang\.String\)) and related methods to query these properties\. For example, the following code snippet will not work reliably when Maven is embedded, say into an IDE or a CI server: + +``` +public MyMojo extends AbstractMojo +{ + public void execute() + { + /* + * FIXME: This prevents proper embedding into IDEs or CI systems. + */ + String value = System.getProperty( "maven.test.skip" ); + } +} +``` + +The problem is that the properties managed by the `System` class are global, i\.e\. shared among all threads in the current JVM\. To prevent conflicts with other code running in the same JVM, Maven plugins should instead query the execution properties\. These can be obtained from [`MavenSession.getExecutionProperties()`](https://maven\.apache\.org/ref/current/maven\-core/apidocs/org/apache/maven/execution/MavenSession\.html\#getExecutionProperties\(\))\. + +## Using Shutdown Hooks + +People occasionally employ shutdown hooks to perform cleanup tasks, e\.g\. to delete temporary files as shown in the example below: + +``` +public MyMojo extends AbstractMojo +{ + public void execute() + { + File tempFile = File.createTempFile( "temp", null ); + /* + * FIXME: This assumes the JVM terminates soon after + * the Maven build has finished. + */ + tempFile.deleteOnExit(); + } +} +``` + +The problem is that the JVM executing Maven can be running much longer than the actual Maven build\. Of course, this does not apply to the standalone invocation of Maven from the command line\. However, it affects the embedded usage of Maven in IDEs or CI servers\. In those cases, the cleanup tasks will be deferred, too\. If the JVM is then executing a bunch of other Maven builds, many such cleanup tasks can sum up, eating up resources of the JVM\. + +For this reason, plugin developers should avoid usage of shutdown hooks and rather use `try`/`finally` blocks to perform cleanup as soon as the resources are no longer needed\. + +## Resolving Relative Paths + +It is common practice for users of Maven to specify relative paths in the POM, not to mention that the Super POM does so, too\. The intention is to resolve such relative paths against the base directory of the current project\. In other words, the paths `target/classes` and `${project.basedir}/target/classes` should resolve to the same directory for a given POM\. + +Unfortunately, the class [`java.io.File`](http://java\.sun\.com/javase/6/docs/api/java/io/File\.html) does not resolve relative paths against the project's base directory\. As mentioned in its class javadoc, it resolves relative paths against the current working directory\. In plain English: Unless a Maven component has complete control over the current working directory, any usage of `java.io.File` in combination with a relative path is a bug\. + +At first glance, one might be tempted to argue that the project base directory is equal to the current working directory\. However, this assumption is generally not true\. Consider the following scenarios: + +1. Reactor Builds + + When a child module is build during a reactor build, the current working directory is usually the base directory of the parent project, not the base directory of the current module\. That is the most common scenario where users are faced with the bug\. + +1. Embedded Maven Invocations + + Other tools, most notably IDEs, that run Maven under the hood may have set the current working directory to their installation directory or whatever they like\. + +1. Maven Invocations using the `-f` Switch + + While it is surely an uncommon use\-case, the user is free to invoke Maven from an arbitrary working directory by specifying an absolute path like `mvn -f /home/me/projects/demo/pom.xml`\. + +Hence this example code is prone to misbehave: + +``` +public MyMojo extends AbstractMojo +{ + /** + * @parameter + */ + private String outputDirectory; + + public void execute() + { + /* + * FIXME: This will resolve relative paths like "target/classes" against + * the user's working directory instead of the project's base directory. + */ + File outputDir = new File( outputDirectory ).getAbsoluteFile(); + } +} +``` + +In order to guarantee reliable builds, Maven and its plugins must manually resolve relative paths against the project's base directory\. A simple idiom like the following will do just fine: + +``` +File file = new File( path ); +if ( !file.isAbsolute() ) +{ + file = new File( project.getBasedir(), file ); +} +``` + +Many Maven plugins can get this resolution automatically if they declare their affected mojo parameters of type `java.io.File` instead of `java.lang.String`\. This subtle difference in parameter types will trigger a feature known as _path translation_, i\.e\. the Maven core will automatically resolve relative paths when it pumps the XML configuration into a mojo\. + +## Determining the Output Directory for a Site Report + +Most reporting plugins inherit from `AbstractMavenReport`\. In doing so, they need to implement the inherited but abstract method `getOutputDirectory()`\. To implement this method, plugins usually declare a field named `outputDirectory` which they return in the method\. Nothing wrong so far\. + +Now, some plugins need to create additional files in the report output directory that accompany the report generated via the sink interface\. While it is tempting to use either the method `getOutputDirectory()` or the field `outputDirectory` directly in order to setup a path for the output files, this leads most likely to a bug\. More precisely, those plugins will not properly output files when run by the Maven Site Plugin as part of the site lifecycle\. This is best noticed when the output directory for the site is configured directly in the Maven Site Plugin such that it deviates from the expression `${project.reporting.outputDirectory}` that the plugins use by default\. Multi\-language site generation is another scenario to exploit this bug which is illustrated below: + +``` +public MyReportMojo extends AbstractMavenReport +{ + /** + * @parameter default-value="${project.reporting.outputDirectory}" + */ + private File outputDirectory; + + protected String getOutputDirectory() + { + return outputDirectory.getAbsolutePath(); + } + + public void executeReport( Locale locale ) + { + /* + * FIXME: This assumes the mojo parameter reflects the effective + * output directory as used by the Maven Site Plugin. + */ + outputDirectory.mkdirs(); + } +} +``` + +There are in principal two situations in which a report mojo could be invoked\. The mojo might be run directly from the command line or the default build lifecycle or it might be run indirectly as part of the site generation along with other report mojos\. The glaring difference between these two invocations is the way the output directory is controlled\. In the first case, the parameter `outputDirectory` from the mojo itself is used\. In the second case however, the Maven Site Plugin takes over control and will set the output directory according to its own configuration by calling `MavenReport.setReportOutputDirectory()` on the reports being generated\. + +Therefore, developers should always use `MavenReport.getReportOutputDirectory()` if they need to query the effective output directory for the report\. The implementation of `AbstractMavenReport.getOutputDirectory()` is only intended as a fallback in case the mojo is not run as part of the site generation\. + +## Retrieving the Mojo Logger + +Maven employs an IoC container named Plexus to setup a plugin's mojos before their execution\. In other words, components required by a mojo will be provided by means of dependency injection, more precisely field injection\. The important point to keep in mind is that this field injection happens _after_ the mojo's constructor has finished\. This means that references to injected components are invalid during the construction time of the mojo\. + +For example, the next snippet tries to retrieve the mojo logger during construction time but the mojo logger is an injected component and as such has not been properly initialized yet: + +``` +public MyMojo extends AbstractMojo +{ + /* + * FIXME: This will retrieve a wrong logger instead of the intended mojo logger. + */ + private Log log = getLog(); + + public void execute() + { + log.debug( "..." ); + } +} +``` + +In case of the logger, the above mojo will simply use a default console logger, i\.e\. the code defect is not immediately noticeable by a `NullPointerException`\. This default logger will however use a different message format for its output and also outputs debug messages even if Maven's debug mode was not enabled\. For this reason, developers must not try to cache the logger during construction time\. The method `getLog()` is fast enough and can simply be called whenever one needs it\. \+\-\-\- + diff --git a/content/markdown/plugin-developers/cookbook/index.md b/content/markdown/plugin-developers/cookbook/index.md new file mode 100644 index 0000000000..b4e4180a1a --- /dev/null +++ b/content/markdown/plugin-developers/cookbook/index.md @@ -0,0 +1,32 @@ +--- +title: Plugins Cookbook +author: + - Brett Porter + - Vincent Siveton +date: 2009-08-02 +--- + + + + + + + + + + + + + + + + + + + +# Maven Extensions Cookbook + +Extensions are based on components, defined either with Plexus or JSR\-330: + +- [How to upgrade from Plexus javadoc tags to Plexus Java annotations?](\./plexus\-plugin\-upgrade\.html) +- [Using JSR\-330 \(instead of Plexus Java annotations\)](/maven\-jsr330\.html) diff --git a/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md b/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md new file mode 100644 index 0000000000..424236f8bc --- /dev/null +++ b/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md @@ -0,0 +1,160 @@ +--- +title: Cookbook - How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations +author: + - Hervé Boutemy +date: 2012-06-02 +--- + + + + + + + + + + + + + + + + + + + +# Cookbook: How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations? + +## Summary + +This recipe describes how to upgrade from Plexus Javadoc Tags to Plexus Java Annotations when defining a Plexus component\. + +This is done in 2 steps: + +1. replace the [deprecated `plexus-maven-plugin`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/), which only supports Plexus Javadoc Tags, with its [successor: `plexus-component-metadata`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/), which support both Plexus Javadoc Tags and Plexus Java Annotations, +1. update sources with [Java Annotations for Plexus](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-annotations/)\. + +**Notice**: if you're targeting components for Maven 3\.1\.0\+, using [`@Named`/`@Inject` JSR\-330 annotations](/maven\-jsr330\.html) instead of `@Component`/`@Requirement` Plexus Java Annotations may be a good next step + +## Prerequisite Plugins + +Here is the list of the plugins used: + +|**Plugin**|**Version**| +|---|---| +|[`plexus-maven-plugin`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/)|1\.3\.8| +|[`plexus-component-metadata`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/)|1\.7\.1| +## Equivalence Table + +||**plexus\-maven\-plugin**|**plexus\-component\-metadata**| +|:---:|:---:|:---:| +||[project](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/) / [plugin info](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/plugin\-info\.html)|[project](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/) / [plugin info](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/plugin\-info\.html)| +|latest|1\.3\.8|1\.7\.1| +|phase|process\-sources|process\-classes| +|goals|[`descriptor`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/descriptor\-mojo\.html)|[`generate-metadata`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/generate\-metadata\-mojo\.html)| +||[`merge-descriptors`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/merge\-descriptors\-mojo\.html)|see `staticMetadataDirectory` parameter   +default: `${project.basedir}/src/main/resources/META-INF/plexus`| +||[`test-descriptor`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/test\-descriptor\-mojo\.html)|[`generate-test-metadata`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-metadata/generate\-test\-metadata\-mojo\.html)| +||[`test-merge-descriptors`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/test\-merge\-descriptors\-mojo\.html)|see `testStaticMetadataDirectory` parameter   +default: `${project.basedir}/src/test/resources/META-INF/plexus`| +||[`components-report`](https://codehaus\-plexus\.github\.io/plexus\-maven\-plugin/components\-report\-mojo\.html)|reporting feature not available| +|source annotations|javadoc tags:   +`@plexus.component`, `@plexus.requirement`, `@plexus.configuration`  |javadoc tags \+ [`plexus-component-annotations`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-annotations/) Java 5 annotations:  +[`@Component`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-annotations/apidocs/org/codehaus/plexus/component/annotations/Component\.html), [`@Requirement`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-annotations/apidocs/org/codehaus/plexus/component/annotations/Requirement\.html), [`@Configuration`](https://codehaus\-plexus\.github\.io/plexus\-containers/plexus\-component\-annotations/apidocs/org/codehaus/plexus/component/annotations/Configuration\.html),| +## Recipe + +### Plugin Configuration + +In your `pom.xml`, replace `plexus-maven-plugin` configuration: + +``` + + + + + org.codehaus.plexus + plexus-maven-plugin + 1.3.8 + + + + descriptor + + + + + + +``` + +with corresponding `plexus-component-metadata` configuration: + +``` + + + + + org.codehaus.plexus + plexus-component-metadata + 1.7.1 + + + + generate-metadata + + + + + + +``` + +If `merge-descriptors` is used, move the handwritten xml file to `${project.basedir}/src/main/resources/META-INF/plexus`\. + +### Replacing Plexus Javadoc Tags with Plexus Java 5 Annotations + +In your `pom.xml`, add `plexus-component-annotations` dependency: + +``` + + + + org.codehaus.plexus + plexus-component-annotations + 1.7.1 + + + +``` + +In your java sources, replace javadoc tags: + +``` +/** + * @plexus.component role="foo.MyComponent" role-hint="hint-value" + */ +public class MyComponentImplementation + implements MyComponent +{ + /** + * @plexus.requirement + */ + private InjectedComponent; +} +``` + +with corresponding Java 5 annotations + +``` +import org.codehaus.plexus.component.annotations.Component; +import org.codehaus.plexus.component.annotations.Requirement; + +@Component( role = MyComponent.class, hint = "hint-value" ) +public class MyComponentImplementation + implements MyComponent +{ + @Requirement + private InjectedComponent; +} +``` + diff --git a/content/markdown/plugin-developers/index.md b/content/markdown/plugin-developers/index.md new file mode 100644 index 0000000000..0e7290496f --- /dev/null +++ b/content/markdown/plugin-developers/index.md @@ -0,0 +1,52 @@ +--- +title: Plugin Developers Centre +author: + - Brett Porter +date: 2008-01-01 +--- + + + + + + + + + + + + + + + + + + + +# Plugin Developers Centre + +This documentation centre is for those who are developing Maven plugins\. This might be for your own build, or as an accompaniment to your third party tool\. + + + +**What is a Mojo?** A mojo is a **M**aven plain **O**ld **J**ava **O**bject\. Each mojo is an executable _goal_ in Maven, and a plugin is a distribution of one or more related mojos\. + + +- [ Introduction to Plugin Development](\.\./guides/introduction/introduction\-to\-plugins\.html) \- Introduction to concepts +- [ Your First Mojo](\.\./guides/plugin/guide\-java\-plugin\-development\.html) \- Learn how to write your first plugin +- [ Your First Report Mojo](\.\./guides/plugin/guide\-java\-report\-plugin\-development\.html) \- Learn how to write your first reporting plugin +- [ Testing your Plugin](\./plugin\-testing\.html) \- How to write tests for your plugins +- TODO: creating and using custom packaging \(like [`maven-archetype` packaging](/archetype/archetype\-packaging/)\) +- [ Common Bugs and Pitfalls](\./common\-bugs\.html) \- Overview of problematic coding patterns + +## Reference + +- [ Mojo API and Annotation Reference](\.\./developers/mojo\-api\-specification\.html) +- [ Maven Plugin Tools and annotations](/plugin\-tools/maven\-plugin\-tools\-annotations/index\.html) +- [ Maven API Reference](\.\./ref/current/index\.html) +- [ Maven Class Loading](\.\./guides/mini/guide\-maven\-classloading\.html) +## Extensions + +- [Maven 3 lifecycle extensions](\.\./examples/maven\-3\-lifecycle\-extensions\.html) +- [How to upgrade from Plexus javadoc tags to Plexus Java annotations?](\./cookbook/plexus\-plugin\-upgrade\.html) +- [Using JSR\-330 \(instead of Plexus Java annotations\)](/maven\-jsr330\.html) diff --git a/content/markdown/plugin-developers/plugin-testing.md b/content/markdown/plugin-developers/plugin-testing.md new file mode 100644 index 0000000000..3f6ffba68d --- /dev/null +++ b/content/markdown/plugin-developers/plugin-testing.md @@ -0,0 +1,154 @@ +--- +title: Developers centre - Testing Plugins Strategies +author: + - Vincent Siveton +date: 2008-01-01 +2015-06-16 +--- + + + + + + + + + + + + + + + + + + + +# Introduction + +Currently, Maven only supports unit testing out of the box\. This document is intended to help Maven Developers test plugins with unit tests, integration tests, and functional tests\. + + +# Testing Styles: Unit Testing vs\. Functional/Integration Testing + +A unit test attempts to verify a mojo as an isolated unit, by mocking out the rest of the Maven environment\. A mojo unit test does not attempt to run your plugin in the context of a real Maven build\. Unit tests are designed to be fast\. + +A functional/integration test attempts to use a mojo in a real Maven build, by launching a real instance of Maven in a real project\. Normally this requires you to construct special dummy Maven projects with real POM files\. Often this requires you to have already installed your plugin into your local repository so it can be used in a real Maven build\. Functional tests run much more slowly than unit tests, but they can catch bugs that you may not catch with unit tests\. + +The general wisdom is that your code should be mostly tested with unit tests, but should also have some functional tests\. + +# Unit Tests + +## Using JUnit alone + +In principle, you can write a unit test of a plugin Mojo the same way you'd write any other JUnit test case, by writing a class that `extends TestCase`\. + +However, most mojos need more information to work properly\. For example, you'll probably need to inject a reference to a MavenProject, so your mojo can query project variables\. + +## Using PlexusTestCase + +Mojo variables are injected using Plexus, and many Mojos are written to take specific advantage of the Plexus container \(by executing a lifecycle or having various injected dependencies\)\. + +If all you need are Plexus container services, you can write your class with `extends PlexusTestCase` instead of TestCase\. + +With that said, if you need to inject Maven objects into your mojo, you'll probably prefer to use the maven\-plugin\-testing\-harness\. + +## maven\-plugin\-testing\-harness + +The [maven\-plugin\-testing\-harness](/plugin\-testing/maven\-plugin\-testing\-harness/) is explicitly intended to test the `org.apache.maven.reporting.AbstractMavenReport#execute()` implementation\. + +In general, you need to include `maven-plugin-testing-harness` as a dependency, and create a \*MojoTest \(by convention\) class which `extends AbstractMojoTestCase`\. + +``` +... + + ... + + org.apache.maven.plugin-testing + maven-plugin-testing-harness + 3.3.0 + test + + ... + +... +``` + +``` +public class YourMojoTest + extends AbstractMojoTestCase +{ + /** + * @see junit.framework.TestCase#setUp() + */ + protected void setUp() throws Exception + { + // required for mojo lookups to work + super.setUp(); + } + + /** + * @throws Exception + */ + public void testMojoGoal() throws Exception + { + File testPom = new File( getBasedir(), + "src/test/resources/unit/basic-test/basic-test-plugin-config.xml" ); + + YourMojo mojo = (YourMojo) lookupMojo( "yourGoal", testPom ); + + assertNotNull( mojo ); + } +} +``` + +For more information, refer to [Maven Plugin Harness Wiki](http://cwiki\.apache\.org/confluence/display/MAVENOLD/Maven\+Plugin\+Harness) + +# Integration/Functional testing + +## maven\-verifier + +maven\-verifier tests are run using JUnit or TestNG, and provide a simple class allowing you to launch Maven and assert on its log file and built artifacts\. It also provides a ResourceExtractor, which extracts a Maven project from your src/test/resources directory into a temporary working directory where you can do tricky stuff with it\. Follow the [Getting Started](/shared/maven\-verifier/getting\-started\.html) guide to learn more about creating maven\-verifier tests\. + +Maven itself uses maven\-verifier to run its core integration tests\. For more information, please refer to [Creating a Maven Integration Test](https://cwiki\.apache\.org/confluence/display/MAVEN/Creating\+a\+Maven\+Integration\+Test)\. + +**Note**: maven\-verifier and maven\-verifier\-plugin sound similar, but are totally different unrelated pieces of code\. maven\-verifier\-plugin simply verifies the existence/absence of files on the filesystem\. You could use it for functional testing, but you may need more features than maven\-verifier\-plugin provides\. + +## maven\-invoker\-plugin + +You can use [maven\-invoker\-plugin](https://maven\.apache\.org/plugins/maven\-invoker\-plugin/) to invoke Maven and to provide some BeanShell/Groovy tests\. Tests written in this way don't run under JUnit/TestNG; instead, they're run by Maven itself\. + +You can take a look at the [maven\-install\-plugin](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-install\-plugin/src/it/) how there are integration tests are written\. + +``` + + ... + + + + org.apache.maven.plugins + maven-invoker-plugin + 1.10 + + src/it + + **/pom.xml + + verify + + + + + run + + + + + ... + + + ... + +``` + diff --git a/content/markdown/plugins/index.md b/content/markdown/plugins/index.md new file mode 100644 index 0000000000..5c98e21f38 --- /dev/null +++ b/content/markdown/plugins/index.md @@ -0,0 +1,163 @@ +--- +title: Available Plugins +author: + - Brett Porter + - Jason van Zyl + - Dennis Lundberg + - Olivier Lamy + - Benson Margulies + - Karl-Heinz Marbaise +date: 2017-05-05 +--- + + + + + + + + + + + + + + + + + + +# Available Plugins + +Maven is \- at its heart \- a plugin execution framework; all work is done by plugins\. Looking for a specific goal to execute? This page lists the core plugins and others\. There are the build and the reporting plugins: + +- **Build plugins** will be executed during the build and they should be configured in the `` element from the POM\. +- **Reporting plugins** will be executed during the site generation and they should be configured in the `` element from the POM\. Because the result of a Reporting plugin is part of the generated site, Reporting plugins should be both internationalized and localized\. You can read more about the [localization of our plugins](\./localization\.html) and how you can help\. +## Supported By The Maven Project + +To see the most up\-to\-date list browse the Maven repository, specifically the [ `org/apache/maven/plugins`](https://repo\.maven\.apache\.org/maven2/org/apache/maven/plugins/) subdirectory\. _\(Plugins are organized according to a directory structure that resembles the standard Java package naming convention\)_ + + + + + + + +|**Plugin**|**Type\***|**Version**|**Release Date**|**Description**|**Source Repository**|**Issue Tracking**| +|---|---|---|---|---|---|---| +|**Core plugins**||||**Plugins corresponding to default core phases \(ie\. clean, compile\)\. They may have multiple goals as well\.**||| +|[ `clean`](/plugins/maven\-clean\-plugin/)|B|3\.4\.0|2024\-06\-16|Clean up after the build\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-clean\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-clean\-plugin/)|[Jira MCLEAN](https://issues\.apache\.org/jira/browse/MCLEAN)| +|[ `compiler`](/plugins/maven\-compiler\-plugin/)|B|3\.13\.0|2024\-03\-15|Compiles Java sources\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-compiler\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-compiler\-plugin/)|[Jira MCOMPILER](https://issues\.apache\.org/jira/browse/MCOMPILER)| +|[ `deploy`](/plugins/maven\-deploy\-plugin/)|B|3\.1\.3|2024\-08\-19|Deploy the built artifact to the remote repository\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-deploy\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-deploy\-plugin/)|[Jira MDEPLOY](https://issues\.apache\.org/jira/browse/MDEPLOY)| +|[ `failsafe`](/surefire/maven\-failsafe\-plugin/)|B|3\.5\.1|2024\-10\-01|Run the JUnit integration tests in an isolated classloader\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-surefire\.git) / [GitHub](https://github\.com/apache/maven\-surefire/)|[Jira SUREFIRE](https://issues\.apache\.org/jira/browse/SUREFIRE)| +|[ `install`](/plugins/maven\-install\-plugin/)|B|3\.1\.3|2024\-08\-19|Install the built artifact into the local repository\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-install\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-install\-plugin/)|[Jira MINSTALL](https://issues\.apache\.org/jira/browse/MINSTALL)| +|[ `resources`](/plugins/maven\-resources\-plugin/)|B|3\.3\.1|2023\-03\-21|Copy the resources to the output directory for including in the JAR\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-resources\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-resources\-plugin/)|[Jira MRESOURCES](https://issues\.apache\.org/jira/browse/MRESOURCES)| +|[ `site`](/plugins/maven\-site\-plugin/)|B|3\.21\.0|2024\-10\-18|Generate a site for the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-site\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-site\-plugin/)|[Jira MSITE](https://issues\.apache\.org/jira/browse/MSITE)| +|[ `surefire`](/surefire/maven\-surefire\-plugin/)|B|3\.5\.1|2024\-10\-01|Run the JUnit unit tests in an isolated classloader\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-surefire\.git) / [GitHub](https://github\.com/apache/maven\-surefire/)|[Jira SUREFIRE](https://issues\.apache\.org/jira/browse/SUREFIRE)| +|[ `verifier`](/plugins/maven\-verifier\-plugin/)|B|1\.1|2015\-04\-14|Useful for integration tests \- verifies the existence of certain conditions\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-verifier\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-verifier\-plugin/)|[Jira MVERIFIER](https://issues\.apache\.org/jira/browse/MVERIFIER)| +|**Packaging types/tools**||||**These plugins relate to packaging respective artifact types\.**||| +|[ `ear`](/plugins/maven\-ear\-plugin/)|B|3\.3\.0|2022\-10\-18|Generate an EAR from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-ear\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-ear\-plugin/)|[Jira MEAR](https://issues\.apache\.org/jira/browse/MEAR)| +|[ `ejb`](/plugins/maven\-ejb\-plugin/)|B|3\.2\.1|2022\-04\-18|Build an EJB \(and optional client\) from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-ejb\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-ejb\-plugin/)|[Jira MEJB](https://issues\.apache\.org/jira/browse/MEJB)| +|[ `jar`](/plugins/maven\-jar\-plugin/)|B|3\.4\.2|2024\-06\-16|Build a JAR from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jar\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jar\-plugin/)|[Jira MJAR](https://issues\.apache\.org/jira/browse/MJAR)| +|[ `rar`](/plugins/maven\-rar\-plugin/)|B|3\.0\.0|2022\-07\-17|Build a RAR from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-rar\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-rar\-plugin/)|[Jira MRAR](https://issues\.apache\.org/jira/browse/MRAR)| +|[ `war`](/plugins/maven\-war\-plugin/)|B|3\.4\.0|2023\-06\-11|Build a WAR from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-war\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-war\-plugin/)|[Jira MWAR](https://issues\.apache\.org/jira/browse/MWAR)| +|[ `app-client/acr`](/plugins/maven\-acr\-plugin/)|B|3\.1\.0|2018\-06\-19|Build a JavaEE application client from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-acr\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-acr\-plugin/)|[Jira MACR](https://issues\.apache\.org/jira/browse/MACR)| +|[ `shade`](/plugins/maven\-shade\-plugin/)|B|3\.6\.0|2024\-05\-31|Build an Uber\-JAR from the current project, including dependencies\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shade\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-shade\-plugin/)|[Jira MSHADE](https://issues\.apache\.org/jira/browse/MSHADE)| +|[ `source`](/plugins/maven\-source\-plugin/)|B|3\.3\.1|2024\-04\-02|Build a source\-JAR from the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-source\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-source\-plugin/)|[Jira MSOURCES](https://issues\.apache\.org/jira/browse/MSOURCES)| +|[ `jlink`](/plugins/maven\-jlink\-plugin/)|B|3\.2\.0|2024\-02\-01|Build Java Run Time Image\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jlink\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jlink\-plugin/)|[Jira MJLINK](https://issues\.apache\.org/jira/browse/MJLINK)| +|[ `jmod`](/plugins/maven\-jmod\-plugin/)|B|3\.0\.0\-alpha\-1|2017\-09\-17|Build Java JMod files\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jmod\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jmod\-plugin/)|[Jira MJMOD](https://issues\.apache\.org/jira/browse/MJMOD)| +|**Reporting plugins**||||**Plugins which generate reports, are configured as reports in the POM and run under the site generation lifecycle\.**||| +|[ `changelog`](/plugins/maven\-changelog\-plugin/)|R|2\.3|2014\-06\-24|Generate a list of recent changes from your SCM\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-changelog\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-changelog\-plugin/)|[Jira MCHANGELOG](https://issues\.apache\.org/jira/browse/MCHANGELOG)| +|[ `changes`](/plugins/maven\-changes\-plugin/)|B\+R|2\.12\.1|2016\-11\-01|Generate a report from an issue tracker or a change document\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-changes\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-changes\-plugin/)|[Jira MCHANGES](https://issues\.apache\.org/jira/browse/MCHANGES)| +|[ `checkstyle`](/plugins/maven\-checkstyle\-plugin/)|B\+R|3\.6\.0|2024\-10\-22|Generate a Checkstyle report\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-checkstyle\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-checkstyle\-plugin/)|[Jira MCHECKSTYLE](https://issues\.apache\.org/jira/browse/MCHECKSTYLE)| +|[ `doap`](/plugins/maven\-doap\-plugin/)|B|1\.2|2015\-03\-17|Generate a Description of a Project \(DOAP\) file from a POM\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-doap\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-doap\-plugin/)|[Jira MDOAP](https://issues\.apache\.org/jira/browse/MDOAP)| +|[ `javadoc`](/plugins/maven\-javadoc\-plugin/)|B\+R|3\.10\.1|2024\-09\-26|Generate Javadoc for the project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-javadoc\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-javadoc\-plugin/)|[Jira MJAVADOC](https://issues\.apache\.org/jira/browse/MJAVADOC)| +|[ `jdeps`](/plugins/maven\-jdeps\-plugin/)|B|3\.1\.2|2019\-06\-12|Run JDK's JDeps tool on the project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jdeps\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jdeps\-plugin/)|[Jira MJDEPS](https://issues\.apache\.org/jira/browse/MJDEPS)| +|[ `jxr`](/jxr/maven\-jxr\-plugin/)|R|3\.6\.0|2024\-10\-22|Generate a source cross reference\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jxr\.git) / [GitHub](https://github\.com/apache/maven\-jxr/)|[Jira JXR](https://issues\.apache\.org/jira/browse/JXR)| +|[ `linkcheck`](/plugins/maven\-linkcheck\-plugin/)|R|1\.2|2014\-10\-08|Generate a Linkcheck report of your project's documentation\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-linkcheck\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-linkcheck\-plugin/)|[Jira MLINKCHECK](https://issues\.apache\.org/jira/browse/MLINKCHECK)| +|[ `pmd`](/plugins/maven\-pmd\-plugin/)|B\+R|3\.25\.0|2024\-08\-22|Generate a PMD report\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-pmd\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-pmd\-plugin/)|[Jira MPMD](https://issues\.apache\.org/jira/browse/MPMD)| +|[ `plugin-report`](/plugin\-tools/maven\-plugin\-report\-plugin/)|R|3\.15\.1|2024\-10\-22|Create a plugin documentation for any mojos found in the source tree\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-plugin\-tools\.git) / [GitHub](https://github\.com/apache/maven\-plugin\-tools/)|[Jira MPLUGIN](https://issues\.apache\.org/jira/browse/MPLUGIN)| +|[ `project-info-reports`](/plugins/maven\-project\-info\-reports\-plugin/)|R|3\.8\.0|2024\-10\-18|Generate standard project reports\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-project\-info\-reports\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-project\-info\-reports\-plugin/)|[Jira MPIR](https://issues\.apache\.org/jira/browse/MPIR)| +|[ `surefire-report`](/surefire/maven\-surefire\-report\-plugin/)|R|3\.5\.1|2024\-10\-01|Generate a report based on the results of unit tests\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-surefire\.git) / [GitHub](https://github\.com/apache/maven\-surefire/)|[Jira SUREFIRE](https://issues\.apache\.org/jira/browse/SUREFIRE)| +|**Tools**||||**These are miscellaneous tools available through Maven by default\.**||| +|[ `antrun`](/plugins/maven\-antrun\-plugin/)|B|3\.1\.0|2022\-04\-18|Run a set of ant tasks from a phase of the build\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-antrun\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-antrun\-plugin/)|[Jira MANTRUN](https://issues\.apache\.org/jira/browse/MANTRUN)| +|[ `artifact`](/plugins/maven\-artifact\-plugin/)|B|3\.5\.2|2024\-10\-15|Manage artifacts tasks like buildinfo\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-artifact\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-artifact\-plugin/)|[Jira MARTIFACT](https://issues\.apache\.org/jira/browse/MARTIFACT)| +|[ `archetype`](/archetype/maven\-archetype\-plugin/)|B|3\.3\.1|2024\-10\-25|Generate a skeleton project structure from an archetype\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-archetype\.git) / [GitHub](https://github\.com/apache/maven\-archetype/)|[Jira ARCHETYPE](https://issues\.apache\.org/jira/browse/ARCHETYPE)| +|[ `assembly`](/plugins/maven\-assembly\-plugin/)|B|3\.7\.1|2024\-03\-15|Build an assembly \(distribution\) of sources and/or binaries\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-assembly\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-assembly\-plugin/)|[Jira MASSEMBLY](https://issues\.apache\.org/jira/browse/MASSEMBLY)| +|[ `dependency`](/plugins/maven\-dependency\-plugin/)|B\+R|3\.8\.1|2024\-10\-18|Dependency manipulation \(copy, unpack\) and analysis\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-dependency\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-dependency\-plugin/)|[Jira MDEP](https://issues\.apache\.org/jira/browse/MDEP)| +|[ `enforcer`](/enforcer/maven\-enforcer\-plugin/)|B|3\.5\.0|2024\-05\-26|Environmental constraint checking \(Maven Version, JDK etc\), User Custom Rule Execution\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-enforcer\.git) / [GitHub](https://github\.com/apache/maven\-enforcer/)|[Jira MENFORCER](https://issues\.apache\.org/jira/browse/MENFORCER)| +|[ `gpg`](/plugins/maven\-gpg\-plugin/)|B|3\.2\.7|2024\-09\-24|Create signatures for the artifacts and poms\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-gpg\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-gpg\-plugin/)|[Jira MGPG](https://issues\.apache\.org/jira/browse/MGPG)| +|[ `help`](/plugins/maven\-help\-plugin/)|B|3\.5\.1|2024\-10\-18|Get information about the working environment for the project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-help\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-help\-plugin/)|[Jira MPH](https://issues\.apache\.org/jira/browse/MPH)| +|[ `invoker`](/plugins/maven\-invoker\-plugin/)|B\+R|3\.8\.1|2024\-10\-18|Run a set of Maven projects and verify the output\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-invoker\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-invoker\-plugin/)|[Jira MINVOKER](https://issues\.apache\.org/jira/browse/MINVOKER)| +|[ `jarsigner`](/plugins/maven\-jarsigner\-plugin/)|B|3\.1\.0|2024\-09\-03|Signs or verifies project artifacts\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jarsigner\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jarsigner\-plugin/)|[Jira MJARSIGNER](https://issues\.apache\.org/jira/browse/MJARSIGNER)| +|[ `jdeprscan`](/plugins/maven\-jdeprscan\-plugin/)|B|3\.0\.0\-alpha\-1|2017\-11\-15|Run JDK's JDeprScan tool on the project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jdeprscan\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-jdeprscan\-plugin/)|[Jira MJDEPRSCAN](https://issues\.apache\.org/jira/browse/MJDEPRSCAN)| +|[ `patch`](/plugins/maven\-patch\-plugin/)|B|1\.2|2015\-03\-09|Use the gnu patch tool to apply patch files to source code\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-patch\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-patch\-plugin/)|[Jira MPATCH](https://issues\.apache\.org/jira/browse/MPATCH)| +|[ `pdf`](/plugins/maven\-pdf\-plugin/)|B|1\.6\.1|2022\-08\-16|Generate a PDF version of your project's documentation\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-pdf\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-pdf\-plugin/)|[Jira MPDF](https://issues\.apache\.org/jira/browse/MPDF)| +|[ `plugin`](/plugin\-tools/maven\-plugin\-plugin/)|B|3\.15\.1|2024\-10\-22|Create a Maven plugin descriptor for any mojos found in the source tree, to include in the JAR\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-plugin\-tools\.git) / [GitHub](https://github\.com/apache/maven\-plugin\-tools/)|[Jira MPLUGIN](https://issues\.apache\.org/jira/browse/MPLUGIN)| +|[ `release`](/plugins/maven\-release\-plugin/)|B|3\.1\.1|2024\-07\-11|Release the current project \- updating the POM and tagging in the SCM\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-release\.git) / [GitHub](https://github\.com/apache/maven\-release/)|[Jira MRELEASE](https://issues\.apache\.org/jira/browse/MRELEASE)| +|[ `remote-resources`](/plugins/maven\-remote\-resources\-plugin/)|B|3\.2\.0|2024\-03\-03|Copy remote resources to the output directory for inclusion in the artifact\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-remote\-resources\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-remote\-resources\-plugin/)|[Jira MRRESOURCES](https://issues\.apache\.org/jira/browse/MRRESOURCES)| +|[ `scm`](/scm/maven\-scm\-plugin/)|B|2\.1\.0|2024\-04\-14|Execute SCM commands for the current project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-scm\.git ) / [GitHub](https://github\.com/apache/maven\-scm/)|[Jira SCM](https://issues\.apache\.org/jira/browse/SCM)| +|[ `scm-publish`](/plugins/maven\-scm\-publish\-plugin/)|B|3\.3\.0|2024\-06\-16|Publish your Maven website to a scm location\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-scm\-publish\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-scm\-publish\-plugin/)|[Jira MSCMPUB](https://issues\.apache\.org/jira/browse/MSCMPUB)| +|[ `scripting`](/plugins/maven\-scripting\-plugin/)|B|3\.0\.0|2021\-03\-01|The Maven Scripting Plugin wraps the Scripting API according to JSR223\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-scripting\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-scripting\-plugin/)|[Jira MSCRIPTING](https://issues\.apache\.org/jira/browse/MSCRIPTING)| +|[ `stage`](/plugins/maven\-stage\-plugin/)|B|1\.0|2015\-03\-03|Assists with release staging and promotion\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-stage\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-stage\-plugin/)|[Jira MSTAGE](https://issues\.apache\.org/jira/browse/MSTAGE)| +|[ `toolchains`](/plugins/maven\-toolchains\-plugin/)|B|3\.2\.0|2024\-04\-21|Allows to share configuration across plugins\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-toolchains\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-toolchains\-plugin/)|[Jira MTOOLCHAINS](https://issues\.apache\.org/jira/browse/MTOOLCHAINS)| +|[ `wrapper`](/plugins/maven\-wrapper\-plugin/)|B|3\.3\.2|2024\-05\-24|Download and unpack the maven wrapper distribution|[Git](https://gitbox\.apache\.org/repos/asf/maven\-wrapper\-plugin\.git) / [GitHub](https://github\.com/apache/maven\-wrapper/)|[Jira MWRAPPER](https://issues\.apache\.org/jira/browse/MWRAPPER)| + +\* **B**uild or **R**eporting plugin + +There are also some sandbox plugins into our [source repository](https://svn\.apache\.org/repos/asf/maven/sandbox/trunk/plugins)\. + +Previous archived versions of plugins reference documentations are [located here](\.\./plugins\-archives/)\. + +## Retired + +|**Plugin**|**Type\***|**Version**|**Retired Date**|**Description**| +|---|---|---|---|---| +|[ `ant`](/plugins/maven\-ant\-plugin/)|B|2\.4|2019\-06\-02|Generate an Ant build file for the project\.| +|[ `docck`](/plugins/maven\-docck\-plugin/)|B|1\.2|2023\-10\-22|Documentation checker plugin\.| +|[ `eclipse`](/plugins/maven\-eclipse\-plugin/)|B|2\.10|2015\-10\-07|Generate an Eclipse project files for the current project\.| +|[ `idea`](/plugins/maven\-idea\-plugin/)|B|2\.2\.1|2013\-07\-26|Create/update an IDEA workspace for the current project \(individual modules are created as IDEA modules\)| +|[ `one`](/plugins/maven\-one\-plugin/)|B|1\.3|2013\-07\-30|A plugin for interacting with legacy Maven 1\.x repositories and builds\.| +|[ `reactor`](/plugins/maven\-reactor\-plugin/)|B|1\.1|2014\-03\-24|Build a subset of interdependent projects in a reactor \(Maven 2 only\)\.| +|[ `repository`](/plugins/maven\-repository\-plugin/)|B|2\.4|2019\-04\-30|Plugin to help with repository\-based tasks\.| +## Outside The Maven Land + +### At MojoHaus \(formerly known as codehaus\.org\) + +There are also [many plug\-ins](https://www\.mojohaus\.org/plugins\.html) available at the [ MojoHaus](https://github\.com/mojohaus) project at GitHub\. + +Here are a few common ones: + +|**Plugin** \(see [complete list with version](https://www\.mojohaus\.org/plugins\.html)\)|**Description**| +|---|---| +|[ `animal-sniffer`](https://www\.mojohaus\.org/animal\-sniffer/animal\-sniffer\-maven\-plugin/)|Build signatures of APIs \(JDK for example\) and checks your classes against them\.| +|[ `build-helper`](https://www\.mojohaus\.org/build\-helper\-maven\-plugin/)|Attach extra artifacts and source directories to build\.| +|[ `buildplan`](https://www\.mojohaus\.org/buildplan\-maven\-plugin/)|Inspect the lifecycle of your build\.| +|[ `castor`](https://www\.mojohaus\.org/castor\-maven\-plugin/)|Generate sources from an XSD using Castor\.| +|[ `clirr`](https://www\.mojohaus\.org/clirr\-maven\-plugin/)|Compare binaries or sources for compatibility using Clirr| +|[ `javacc`](https://www\.mojohaus\.org/javacc\-maven\-plugin/)|Generate sources from a JavaCC grammar\.| +|[ `jdepend`](https://www\.mojohaus\.org/jdepend\-maven\-plugin/)|Generate a report on code metrics using JDepend\.| +|[ `nar-maven-plugin`](https://maven\-nar\.github\.io/)|Compiles C, C\+\+, Fortran for different architectures\.| +|[ `native`](https://www\.mojohaus\.org/maven\-native/native\-maven\-plugin/)|Compiles C and C\+\+ code with native compilers\.| +|[ `sql`](https://www\.mojohaus\.org/sql\-maven\-plugin/)|Executes SQL scripts from files or inline\.| +|[ `taglist`](https://www\.mojohaus\.org/taglist\-maven\-plugin/)|Generate a list of tasks based on tags in your code\.| +|[ `versions`](https://www\.mojohaus\.org/versions\-maven\-plugin/)|Manage versions of your project, its modules, dependencies and plugins\.| +### Misc + +A number of other projects provide their own Maven plugins\. This includes: + +|**Plugin**|**Maintainer**|**Description**| +|---|---|---| +|[ `cargo`](https://codehaus\-cargo\.github\.io/)|[Cargo Project](https://codehaus\-cargo\.github\.io/)|Start/stop/configure J2EE containers and deploy to them\.| +|[ `clover`](https://confluence\.atlassian\.com/display/CLOVER/Clover\-for\-Maven\+2)|[Atlassian Clover](https://www\.atlassian\.com/software/clover/)|Generate a Clover report\.| +|[ `jetty`](https://www\.eclipse\.org/jetty/documentation/current/jetty\-maven\-plugin\.html)|[Jetty Project](https://www\.eclipse\.org/jetty/)|Jetty Run a Jetty container for rapid webapp development\.| +|[ `jalopy`](http://www\.triemax\.com/products/jalopy/manual/plugin\-maven\.html)|[Triemax](http://www\.triemax\.com/)|Use Jalopy to format your source code\.| +|[ `rat`](https://creadur\.apache\.org/rat/)|[Apache Creadur Project](https://creadur\.apache\.org/)|Release Audit Tool \(RAT\) to verify files\.| +|[ `Genesis Plugins`](https://geronimo\.apache\.org/maven/genesis/plugins/tools\-maven\-plugin/index\.html)|[Apache Geronimo Project](https://geronimo\.apache\.org/)|Verify legal files in artifacts\.| +|[ `Apache Tomcat`](https://tomcat\.apache\.org/maven\-plugin\.html)|[Apache Tomcat Project](https://tomcat\.apache\.org/maven\-plugin\.html)|Run an Apache Tomcat container for rapid webapp development\.| +|[ `OWASP dependency-check`](https://jeremylong\.github\.io/DependencyCheck/)|[OWASP Dependency\-check Project](https://www\.owasp\.org/index\.php/OWASP\_Dependency\_Check)|Run OWASP Dependency\-Check, a utility that identifies project dependencies and checks if there are any known, publicly disclosed, vulnerabilities\.| +|[ `CycloneDX`](https://github\.com/CycloneDX/cyclonedx\-maven\-plugin)|[CycloneDX Project](https://cyclonedx\.org/)|Generate Software Bill of Materials \(SBOM\) in CycloneDX format\.| +|[ `pgpverify`](https://www\.simplify4u\.org/pgpverify\-maven\-plugin/)|[Simplify4U](https://www\.simplify4u\.org/)|Verify PGP signature of all project dependencies\.| +## Resources + +1. [Guide to Configuring Plugins](\.\./guides/mini/guide\-configuring\-plugins\.html) diff --git a/content/markdown/plugins/localization.md b/content/markdown/plugins/localization.md new file mode 100644 index 0000000000..30492be50b --- /dev/null +++ b/content/markdown/plugins/localization.md @@ -0,0 +1,118 @@ +--- +title: Localization of Plugins +author: + - Dennis Lundberg + - Vincent Siveton +date: 2012-03-12 +--- + + + + + + + + + + + + + + + + + + + +# Localization of Plugins + +Most of the plugins involved with the site generation are fully internationalized\. This means that adapting them to another language, a process known as localization, is very easy\. All that is needed is to download a couple of properties files and start translating the texts in them\. If you want to provide a patch for an unsupported language, there are detailed instructions below\. + +For the basic site generation there are currently files for three components that needs to be localized to support a new language: Maven Site Plugin, Maven Project Info Reports Plugin and Maven Doxia Tools\. + +**Note:** The links to SVN below goes to the latest development code\. So the files may be newer than the ones included in the latest release\. + +In the table below you can see our localized plugins and which languages they are available in\. + +|Plugin|ca|cs|da|de|es|fr|gl|hu|it|ja|ko|lt|nl|no|pl|pt|pt\_BR|ru|sk|sv|tr|zh\_CN|zh\_TW|l10n report|SVN| +|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---| +|Changelog|\-|\-|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-changelog\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-changelog\-plugin/src/main/resources/)| +|Changes|\-|\-|\-|OK|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-changes\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-changes\-plugin/src/main/resources/)| +|Checkstyle|\-|\-|\-|OK|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-checkstyle\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-checkstyle\-plugin/src/main/resources/)| +|Dependency|\-|\-|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-dependency\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-dependency\-plugin/src/main/resources/)| +|DOAP|\-|\-|\-|OK|OK|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|[l10n report](/plugins/maven\-doap\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-doap\-plugin/src/main/resources/)| +|Doxia Integration Tools|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|[l10n report](/doxia/doxia\-tools/doxia\-integration\-tools/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/doxia/doxia\-sitetools/trunk/doxia\-integration\-tools/src/main/resources/)| +|Javadoc|\-|\-|\-|OK|\-|OK|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-javadoc\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-javadoc\-plugin/src/main/resources/)| +|JXR|\-|\-|\-|OK|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-jxr\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/jxr/trunk/maven\-jxr\-plugin/src/main/resources/)| +|PMD|\-|\-|\-|OK|\-|OK|\-|\-|OK|\-|\-|\-|OK|\-|\-|\-|OK|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-pmd\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-pmd\-plugin/src/main/resources/)| +|Plugin|\-|\-|\-|OK|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-plugin\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugin\-tools/trunk/maven\-plugin\-plugin/src/main/resources/)| +|Project Info Reports|\-|OK|\-|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|[l10n report](/plugins/maven\-project\-info\-reports\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-project\-info\-reports\-plugin/src/main/resources/)| +|Surefire report|\-|\-|\-|OK|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|\-|OK|\-|\-|\-|[l10n report](/plugins/maven\-surefire\-report\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/surefire/trunk/maven\-surefire\-report\-plugin/src/main/resources/)| +|Site|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|OK|[l10n report](/plugins/maven\-site\-plugin/l10n\-status\.html)|[SVN](https://svn\.apache\.org/repos/asf/maven/plugins/trunk/maven\-site\-plugin/src/main/resources/)| + +Is your favourite plugin missing a localization for your language? Please help us expand the language support by following the instructions below\. + +## Localizing a Plugin + +- Check out the source code for the plugin you want to add a translation to\. +- Find the resource bundles that needs to be translated\. They are often found in the `src/main/resources` directory\. +- Copy the basefile for the bundle, i\.e\. the one **without** a language extension\. The copy should have the same name as the original file, except for the addition of a language extension\. If, for example, you want to translate the Checkstyle Plugin into Spanish, you would copy `src/main/resources/checkstyle-report.properties` to `src/main/resources/checkstyle-report_es.properties`\. +- Edit the new file and translate all the properties\. Do not change the formating of the file, i\.e\. keep the current indentation and line breaks\. This makes it easy to use a graphical diff tool to find missing keys in the file\. +- Convert the new file so that all non\-US\-ASCII characters are transformed into Unicode escapes, see below for a tool that can help with this\. +- Run "mvn install" for the plugin\. +- Configure a project to use the latest SNAPSHOT version of the plugin you are working on\. Also configure the project to produce a site in the language you are adding a translation for\. For Spanish, as we used in the example above, it would look like this: + + ``` + + + + org.apache.maven.plugins + maven-site-plugin + + es + + + + + ``` + +- Run "mvn site" on that project to test it\. +- When you are happy with your translation, create an issue in JIRA for the plugin in question, with a description like this: "Add Spanish translation"\. Take note of the issue number\. +- Create a patch file that contains your new translation\. Use the issue number when you name the file: + + ``` + svn diff > MYISSUE-123.patch + ``` + +- Attach your patch file to the issue in JIRA\. +## Tools + +There is a command line tool called **native2ascii** that can be used to convert a text file to use Unicode\-encoded characters instead of native\-encoded characters\. This is part of the Java SDK and you can [read more about it here](http://java\.sun\.com/j2se/1\.5\.0/docs/tooldocs/windows/native2ascii\.html)\. You use it like this: + +``` +native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.properties +``` + +### Tools to find out the charset of a file + +- Unix `file` command +- [cpdetector](http://cpdetector\.sourceforge\.net/) +- [IntelliJ IDEA ShowEncodingPlugin](http://plugins\.intellij\.net/plugin/?id=24) +- [Notepad\+\+](http://notepad\-plus\.sourceforge\.net/) +### Tools to write a file in a given charset + +Any editor like Notepad\+\+, Eclipse, IntelliJ IDEA, \.\.\. + +### Tools to convert a file from one encoding to another encoding + +- Unix `iconv` command +- Notepad\+\+ +### IDE plugins + +- [Properties Editor Eclipse Plugin](http://propedit\.sourceforge\.jp/index\_en\.html) +## References + +Please refer to the [Java Internationalization home page](http://java\.sun\.com/javase/technologies/core/basic/intl/) for an introduction to the topic\. + +You can also refer to this Sun FAQ: [How Can I Determine the Encoding of a File?](http://developers\.sun\.com/global/technology/standards/reference/faqs/determining\-file\-encoding\.html) + diff --git a/content/markdown/repository/central-index.md b/content/markdown/repository/central-index.md new file mode 100644 index 0000000000..e2277ce6c6 --- /dev/null +++ b/content/markdown/repository/central-index.md @@ -0,0 +1,54 @@ +--- +title: Central Index +author: + - Hervé Boutemy +date: 2017-04-23 +--- + + + + + + + + + + + + + + + + + + +# Central Index + +Central repository provides [an index in `/.index`](https://repo\.maven\.apache\.org/maven2/\.index/): + +- full index \(`nexus-maven-repository-index.gz`\) is updated weekly, +- incremental index \(`nexus-maven-repository-index..gz` \+ `nexus-maven-repository-index.properties`\)\. + +This index is build using [Maven Indexer](/maven\-indexer/): see [indexer\-core documentation](/maven\-indexer/indexer\-core/) for more details on the fields that are available\. + +You can use [Maven Indexer API](/maven\-indexer/indexer\-core/apidocs/) \(see [examples](/maven\-indexer/indexer\-examples/)\) to use this index with a dedicated API, or use [Apache Lucene](https://lucene\.apache\.org/) indexes browsers like [Luke](https://github\.com/DmitryKey/luke) or [Marple](https://github\.com/flaxsearch/marple) after unpacking the index \(see [`-u` CLI option](/maven\-indexer/indexer\-cli/)\)\. + +## Digging Into Central Index with Luke + +- download [the Central index: `nexus-maven-repository-index.gz`](https://repo\.maven\.apache\.org/maven2/\.index/) +- download [Maven Indexer CLI](https://repo\.maven\.apache\.org/maven2/org/apache/maven/indexer/indexer\-cli/5\.1\.1/indexer\-cli\-5\.1\.1\.jar) and [unpack](/maven\-indexer\-archives/maven\-indexer\-LATEST/indexer\-cli/) the index to raw Lucene index directory: + + ``` + java -jar indexer-cli-5.1.1.jar --unpack nexus-maven-repository-index.gz --destination central-lucene-index --type full + ``` + +- download and extract [Luke binary tarball](https://github\.com/DmitryKey/luke/releases/download/luke\-4\.10\.4/luke\-with\-deps\.tar\.gz) and launch it on the Central index with Lucene format: + + ``` + luke.sh -ro -index central-lucene-index + ``` + + You need an old Luke version using an old Lucene version, since Maven Indexer 5\.5\.1 uses Lucene 3\.6\.2: for this tutorial, we chose Luke version 4\.10\.4, but you may choose another version\. + + But with more recent Maven Indexer releases, more recent Lucene version have been used: see \[Maven Indexer dependencies\]\(/maven\-indexer/indexer\-core/dependencies\.html\)\. + diff --git a/content/markdown/repository/central-metadata.md b/content/markdown/repository/central-metadata.md new file mode 100644 index 0000000000..8b45f96fa4 --- /dev/null +++ b/content/markdown/repository/central-metadata.md @@ -0,0 +1,43 @@ +--- +title: Guide to Metadata in Central Maven Repository +author: + - Carlos Sanchez +date: 2005-10-31 +--- + + + + + + + + + + + + + + + + + + + +# Guide to add, improve or fix metadata in the Central Maven Repository + +## POM Metadata + +There are artifacts in the [Central Maven repository](\./) that don't have POMs\. They come from projects with repositories that have been synced into central without extra checks \(particularly historical ones that were in _Maven 1_ format\)\. We know about the problems but can't do anything unless you provide a POM for it or you ask the project in question to add the POM when they add the artifacts\. + +We don't change dependencies in POMs already in the repository anymore as builds need to be reproducible\. Same applies to POMs that don't exist\. We can only add a POM with no dependencies, because doing any other way would break previous builds that were using that artifact\. + +An alternative is to create a new version with the fixes\. If the broken artifact is `org.foo/bar/1.0` you can provide a fixed POM, JAR,\.\.\. under `org.foo/bar/1.0-1` \(add a comment to the POM explaining what is being fixed and why\)\. See [Maven Repository Upload](\./guide\-central\-repository\-upload\.html) for the instructions to get this new version in the repository\. + +You need to contact the original publisher of the metadata to make sure in next versions it will be fixed or improved before getting it into the repository\. + +## Other Issues + +For any other types of issues related to metadata in the repository \(POM related, or [`maven-metadata.xml`](/ref/current/maven\-repository\-metadata/), or anything else\), open an issue at [MVNCENTRAL](https://issues\.sonatype\.org/browse/MVNCENTRAL) with the relevant information and explain the reasons why it is an issue\. + +**Important:** by default assume that we won't trust your info, so you must provide all links to the project documentation you can to convince us that your solution is right\. + diff --git a/content/markdown/repository/guide-central-repository-upload.md b/content/markdown/repository/guide-central-repository-upload.md new file mode 100644 index 0000000000..c8ecf5b51c --- /dev/null +++ b/content/markdown/repository/guide-central-repository-upload.md @@ -0,0 +1,141 @@ +--- +title: Guide to uploading artifacts to the Central Repository +author: + - Jason van Zyl + - Brian Fox +date: 2018-12-31 +--- + + + + + + + + + + + + + + + + + + + +# Guide to uploading artifacts to the Central Repository + +In order for users of Maven to utilize artifacts produced by your project, you must deploy them to a remote repository\. Many open source projects want to allow users of their projects who build with Maven to have transparent access to their project's artifacts\. In order to allow for this, a project should deploy their artifacts to the [Central Repository](/repository/)\. + +# Requirements + +1. **releases**: Only _releases_ can be uploaded to the Central Repository, that means files that won't change and that only depend on other files already released and available in the repository, +1. **javadoc and sources** for IDE lookup, +1. **PGP signature**, +1. **minimum POM information**: There are some requirements for the minimal information in the POMs that are in the Central Repository, see [here](https://central\.sonatype\.org/pages/requirements\.html\#sufficient\-metadata), +1. **coordinates**: Picking the appropriate coordinates for your project is important\. See the guidelines [here](https://central\.sonatype\.org/pages/choosing\-your\-coordinates\.html), particularly on [groupId and domain ownership](https://central\.sonatype\.org/pages/producers\.html\#individual\-projects\-open\-source\-software\-repository\-hosting\-ossrh)\. + +The updated list of requirements can be found **[here](https://central\.sonatype\.org/pages/requirements\.html)**\. + +## Explanation + +Some folks have asked _"why do we require all this information in the POM for deployed artifacts?"_, so here's a small explanation\. + +The POM being deployed with the artifact is part of the process to make transitive dependencies a reality in Maven\. The logic for getting transitive dependencies working is really not that hard, the problem is getting the data\. The other applications that are made possible by having all the POMs available for artifacts are vast, so by placing them into the Central Repository as part of the process we open up the doors to new ideas that involve unified access to project POMs\. + +We ask for the license because it is possible that your project's license may change in the course of its lifetime, and we are trying to create tools to help sort out licensing issues\. For example, knowing all the licenses for a particular graph of artifacts, we could have some strategies that would identify potential licensing problems\. + +## A basic sample: + +``` + + + 4.0.0 + org.apache.maven + maven + 2.0 + jar + + Maven core + The maven main core project description + http://maven.apache.org + + + + Apache License, Version 2.0 + http://www.apache.org/licenses/LICENSE-2.0.txt + repo + + + + + https://svn.apache.org/viewvc/maven + + + + + ... + ... + ... + + ... + + + + +``` + +## PGP Signature + +When people download artifacts from the Central Repository, they might want to verify these artifacts' PGP signatures against a public key server\. If there are no signatures, then users have no guarantee that they are downloading the original artifact\. + +To improve the quality of the Central Repository, we require you to provide PGP signatures for all your artifacts \(all files except checksums\), and distribute your public key to a key server like [http://pgp\.mit\.edu](http://pgp\.mit\.edu)\. Read [Working with PGP Signatures](http://central\.sonatype\.org/pages/working\-with\-pgp\-signatures\.html) for more information\. + +## FAQ and common mistakes + +- I have other `repositories` or `pluginRepositories` listed in my POM, is that a problem? + + At present, this won't preclude your project from being included, but we do strongly encourage making sure all your dependencies are included in the Central Repository\. If you rely on sketchy repositories that have junk in them or disappear, it just creates havok for downstream users\. Try to keep your dependencies among reliable repos like Central, Jboss, etc\. + +- What about artifacts that can't be distributed because of their license? + + In that case only the POM for that dependency is required, listing where the dependency can be downloaded from\. [See an example](https://repo\.maven\.apache\.org/maven2/javax/activation/activation/1\.0\.2/activation\-1\.0\.2\.pom)\. + +- I have a patched version of the foo project developed at foo\.com, what `groupId` should I use? + + When you patch / modify a third party project, that patched version becomes your project and therefore should be distributed under a `groupId` you control as any project you would have developed, never under `com.foo`\. See above considerations about `groupId`\. + +- My project is hosted at a project hosting service like SourceForge or Github, what should I use as groupId? + + If your project name is `foo` at SourceForge, you can use `net.sf.foo`\. If your username is `bar` on Github, you can use `com.github.bar`\. You can also use another reversed domain name you control\. The group ID does not have to reflect the project host\. + +# Publishing your artifacts to the Central Repository + +## Approved Repository Hosting + +Instead of maintaining repository rsync feeds for each projects, we now encourage projects to use an approved repository hosting location\. + +Currently approved repository hosting locations: + +- [Apache Software Foundation](https://repository\.apache\.org/) \(for all Apache projects\) +- see [the full list](https://central\.sonatype\.org/publish/large\-orgs/) + +Automatic publication will be provided for Forges that provide hosting services for OSS projects and other large project repositories that meet certain minimum criteria such as validation of PGP keys and pom contents as defined above\. If you are interested in becoming an approved Forge, [contact us](https://central\.sonatype\.org/publish/large\-orgs/)\. + +## Other Projects + +The easiest way to upload another project is to use the [Open Source Software Repository Hosting \(OSSRH\)](https://central\.sonatype\.org/pages/ossrh\-guide\.html), which is an approved repository provided by Sonatype for _any_ OSS Project that wants to get its artifacts into the Central Repository\. + +## Explanations + +Having each project maintain its own repository with rsync to the Central Repository was the preferred process until January 2010\. However, we are no longer accepting rsync requests on a per project basis\. + +Over time, we have learned that this process is not scalable\. Many of the projects being synced release very infrequently, yet we have to hit hundreds of servers several times a day looking for artifacts that don't change\. Additionally, there is no good mechanism currently for validating the incoming data via the rsync, and this leads to bad metadata that affects everyone\. + +The aggregation of projects into larger feeds allows us to sync faster and more often, and ensuring these locations perform sufficient checks increases the quality of metadata for everyone\. + diff --git a/content/markdown/run-maven/index.md b/content/markdown/run-maven/index.md new file mode 100644 index 0000000000..325ac84af8 --- /dev/null +++ b/content/markdown/run-maven/index.md @@ -0,0 +1,90 @@ +--- +title: Running Maven +author: + - Brett Porter +date: 2006-11-03 +--- + + + + + + + + + + + + + + + + + + + +# Building a Project with Maven + +The vast majority of Maven\-built projects can be built with the following command: + +``` +mvn verify +``` + +This command tells Maven to build all the modules, and to check if all integration tests succeeded \(when any was defined\) + +That's it\! If you look in the `target` subdirectory, you should find the build output and the final library or application that was being built\. + +**Note:** Some projects have multiple modules, so the library or application you are looking for may be in a module subdirectory\. + +While this will build most projects and Maven encourages this standard convention, builds can be customisable\. If this does not suffice, please consult the project's documentation\. + +## More than just the Build + +Maven can do more than just build software \- it can assist with testing, run web applications and produce reports on projects, as well as any number of other tasks provided by plug\-ins\. + +## When Things go Wrong + +The following are some common problems when building with Maven, and how to resolve them\. + +### Missing Dependencies + +A missing dependency presents with an error like the following: + +``` +[INFO] Failed to resolve artifact. + +Missing: + ---------- +1) jnuit:junit:jar:3.8.1 + + Try downloading the file manually from the project website. + + Then, install it using the command: + mvn install:install-file -DgroupId=jnuit -DartifactId=junit \ + -Dversion=3.8.1 -Dpackaging=jar -Dfile=/path/to/file + + Path to dependency: + 1) org.apache.maven:maven:pom:2.1-SNAPSHOT + 2) jnuit:junit:jar:3.8.1 + + ---------- +1 required artifact is missing. + +for artifact: + org.apache.maven:maven:pom:2.1-SNAPSHOT + +from the specified remote repositories: + central (https://repo.maven.apache.org/maven2) +``` + +To resolve this issue, it depends on what the dependency is and why it is missing\. The most common cause is because it can not be redistributed from the repository and must be manually installed using the instructions given in the message\. This is most common with some older JARs from Sun \(usually `javax.*` group IDs\), and is further documented in the [ Guide to Coping with Sun JARs](\.\./guides/mini/guide\-coping\-with\-sun\-jars\.html)\. + +You can check the list of repositories at the end of the error to ensure that the expected ones are listed \- it may be that the project requires an alternative repository that has not been declared properly or is not accessible with your Maven configuration\. + +In other cases, it may be an incorrectly declared dependency \(like the typo in the example above\) which the project would need to fix, like a compilation error\. + +### Inconsistent output + +Most plugins are optimized to know if they have to execute their task\. In some cases, the output can be polluted from a previous build and the end result is not what you expected\. In such rare situations, you can call the `clean` phase which means: remove the output directory\. You can also call it as `mvn clean verify` which means: first clean up the output directory, next build the project and verify the outcome\. + diff --git a/content/markdown/shared/index.md b/content/markdown/shared/index.md new file mode 100644 index 0000000000..0cb2ba85ae --- /dev/null +++ b/content/markdown/shared/index.md @@ -0,0 +1,57 @@ +--- +title: Shared Components +author: + - Dennis Lundberg + - John Casey + - Karl Heinz Marbaise +date: 2017-05-03 +--- + + + + + + + + + + + + + + + + + + +# Shared Components + +The shared components are currently under transition to Maven 3\.x only components\. + +|**Shared Component**|**Version**|**Release Date**|**Description**|**Source Repository**|**Issue Tracking**| +|---|---|---|---|---|---| +|[ `file-management`](/shared/file\-management/)|3\.1\.0|2022\-06\-29|API to collect files from a given directory using several include/exclude rules\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-file\-management\.git) / [GitHub](https://github\.com/apache/maven\-file\-management/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = file\-management)| +|[ `maven-archiver`](/shared/maven\-archiver/)|3\.6\.3|2024\-10\-22|Is mainly used by plugins to handle packaging\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-archiver\.git) / [GitHub](https://github\.com/apache/maven\-archiver/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-archiver)| +|[ `maven-artifact-transfer`](/shared/maven\-artifact\-transfer/)|0\.13\.1|2020\-12\-26|An API to install, deploy and resolve artifacts with Maven|[Git](https://gitbox\.apache\.org/repos/asf/maven\-artifact\-transfer\.git) / [GitHub](https://github\.com/apache/maven\-artifact\-transfer/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-artifact\-transfer)| +|[ `maven-common-artifact-filters`](/shared/maven\-common\-artifact\-filters/)|3\.4\.0|2024\-06\-05|Filters lists of Artifact instances\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-common\-artifact\-filters\.git) / [GitHub](https://github\.com/apache/maven\-common\-artifact\-filters/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-common\-artifact\-filters)| +|[ `maven-dependency-analyzer`](/shared/maven\-dependency\-analyzer/)|1\.15\.1|2024\-10\-22|Maven Dependency Analyzer component\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-dependency\-analyzer\.git) / [GitHub](https://github\.com/apache/maven\-dependency\-analyzer/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-dependency\-analyzer)| +|[ `maven-dependency-tree`](/shared/maven\-dependency\-tree/)|3\.3\.0|2024\-05\-29|Maven Dependency Tree constructs a tree model of a Maven project's dependencies\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-dependency\-tree\.git) / [GitHub](https://github\.com/apache/maven\-dependency\-tree/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-dependency\-tree)| +|[ `maven-doxia-tools`](/doxia/doxia\-sitetools/doxia\-integration\-tools/)|||moved to [ `doxia-integration-tools`](/doxia/doxia\-sitetools/doxia\-integration\-tools/)||| +|[ `maven-filtering`](/shared/maven\-filtering/)|3\.4\.0|2024\-08\-28|Components for filtering resources\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-filtering\.git) / [GitHub](https://github\.com/apache/maven\-filtering/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-filtering)| +|[ `maven-invoker`](/shared/maven\-invoker/)|3\.3\.0|2024\-05\-07|Fires up a Maven build in a new JVM\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-invoker\.git) / [GitHub](https://github\.com/apache/maven\-invoker/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-invoker)| +|[ `maven-jarsigner`](/shared/maven\-jarsigner/)|3\.1\.0|2024\-08\-15|This component provides some utilities to sign/verify jars/files in your Mojos\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-jarsigner\.git) / [GitHub](https://github\.com/apache/maven\-jarsigner/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-jarsigner)| +|[ `maven-mapping`](/shared/maven\-mapping/)|3\.0\.0|2015\-11\-19|A shared component for all plugins that need to do mapping\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-mapping\.git) / [GitHub](https://github\.com/apache/maven\-mapping/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-mapping)| +|[ `maven-reporting-api`](/shared/maven\-reporting\-api/)|4\.0\.0|2024\-10\-01|API to manage report generation\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-reporting\-api\.git) / [GitHub](https://github\.com/apache/maven\-reporting\-api/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-reporting\-api)| +|[ `maven-reporting-exec`](/shared/maven\-reporting\-exec/)|2\.0\.0|2024\-10\-15|API to manage report plugins preparation with Maven 3\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-reporting\-exec\.git) / [GitHub](https://github\.com/apache/maven\-reporting\-exec/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-reporting\-exec)| +|[ `maven-reporting-impl`](/shared/maven\-reporting\-impl/)|4\.0\.0|2024\-10\-12|Abstract classes to manage report generation\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-reporting\-impl\.git) / [GitHub](https://github\.com/apache/maven\-reporting\-impl/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-reporting\-impl)| +|[ `maven-script-interpreter`](/shared/maven\-script\-interpreter/)|1\.6|2024\-04\-29|Utilities to interpret/execute some scripts for various implementations: groovy or beanshell\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-script\-interpreter\.git) / [GitHub](https://github\.com/apache/maven\-script\-interpreter/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-script\-interpreter)| +|[ `maven-shared-incremental`](/shared/maven\-shared\-incremental/)|1\.1|2013\-04\-08|Various utility classes and plexus components for supporting incremental build functionality in Maven plugins\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shared\-incremental\.git) / [GitHub](https://github\.com/apache/maven\-shared\-incremental/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-shared\-incremental)| +|[ `maven-shared-jar`](/shared/maven\-shared\-jar/)|3\.1\.1|2024\-06\-20|Utilities which help identify the contents of a JAR, including Java class analysis and Maven metadata analysis\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shared\-jar\.git) / [GitHub](https://github\.com/apache/maven\-shared\-jar/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-shared\-jar)| +|[ `maven-shared-resources`](/shared/maven\-shared\-resources/)|6|2024\-06\-08|This is a collection of templates that are specific to the Maven project\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shared\-resources\.git) / [GitHub](https://github\.com/apache/maven\-shared\-resources/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-shared\-resources)| +|[ `maven-shared-utils`](/shared/maven\-shared\-utils/)|3\.4\.2|2023\-05\-11|Utilities functions for use within Maven\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shared\-utils\.git) / [GitHub](https://github\.com/apache/maven\-shared\-utils/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-shared\-utils)| +|[ `maven-shared-io`](/shared/maven\-shared\-io/)|3\.0\.0|2015\-12\-23|API for I/O support like logging, download or file scanning\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-shared\-io\.git) / [GitHub](https://github\.com/apache/maven\-shared\-io/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-shared\-io)| +|[ `maven-verifier`](/shared/maven\-verifier/)|2\.0\.0\-M1|2022\-09\-22|Used to run Maven builds as part of tests\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-verifier\.git) / [GitHub](https://github\.com/apache/maven\-verifier/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSHARED AND status \!= Closed AND component = maven\-verifier)| +|[ `maven-scm`](/scm/)|2\.1\.0|2024\-04\-11|Generic API to SCM systems\.|[Git](https://gitbox\.apache\.org/repos/asf/maven\-scm\.git) / [GitHub](https://github\.com/apache/maven\-scm/)|[JIRA](https://issues\.apache\.org/jira/browse/SCM)| + +Archived version of shared libraries reference documentations are [located here](\.\./shared\-archives/)\. + diff --git a/content/markdown/skins/index.md b/content/markdown/skins/index.md new file mode 100644 index 0000000000..92e4a91e77 --- /dev/null +++ b/content/markdown/skins/index.md @@ -0,0 +1,69 @@ +--- +title: Available Skins +author: + - Dennis Lundberg + - Karl Heinz Marbaise + - Michael Osipov +date: 2012-04-05 +--- + + + + + + + + + + + + + + + + + + +# Available Skins + +The following table lists skins that are available for you to use in your Maven generated site\. + +## Maintained By The Maven Project + +|**Skin**|**Version**|Site Plugin Version|**Description**|**Source Repository**|**Issue Tracking**| +|---|---|---|---|---|---| +|[ `Maven Fluido Skin`](/skins/maven\-fluido\-skin/)|2\.0\.0\-M11|\[3\.20\.0,\)|Skin based on Bootstrap CSS\.|[Git](http://gitbox\.apache\.org/repos/asf/maven\-fluido\-skin\.git) / [GitHub](https://github\.com/apache/maven\-fluido\-skin/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSKINS AND status \!= Closed AND component = "Fluido\+Skin")| +|[ `Maven Fluido Skin`](/skins/maven\-fluido\-skin/)|1\.12\.0|\[3\.10\.0,3\.20\.0\)|Skin based on Bootstrap CSS\.|[Git](http://gitbox\.apache\.org/repos/asf/maven\-fluido\-skin\.git/) / [GitHub](https://github\.com/apache/maven\-fluido\-skin/)|[JIRA](https://issues\.apache\.org/jira/issues/?jql=project = MSKINS AND status \!= Closed AND component = "Fluido\+Skin")| +### Retired + +|**Skin**|**Version**|Site Plugin Version|**Retired Date**|**Description**| +|---|---|---|---|---| +|[ `Maven Default Skin`](/skins/maven\-default\-skin/) \(unofficially\)|1\.3|\[3\.5,3\.20\.0\)|You get this skin if you don't specify any skin or template\.|[Git](http://gitbox\.apache\.org/repos/asf/maven\-default\-skin\.git/) / [GitHub](https://github\.com/apache/maven\-default\-skin/)| +|[ `Maven Application Skin`](/skins/maven\-application\-skin/)|1\.0|\(,3\.4\]|2015\-12\-28|A skin used by applications like Continuum\.| +|[ `Maven Classic Skin`](/skins/maven\-classic\-skin/)|1\.1|\(,3\.4\]|2015\-12\-28|This skin resembles the look of a site generated by Maven 1\.| +|[ `Maven Stylus Skin`](/skins/maven\-stylus\-skin/)|1\.5|\(,3\.4\]|2015\-12\-28|The skin used for the website of Maven itself\.| +## Outside The Maven Land + +|**Skin**|**Maintainer**|**Description**| +|---|---|---| +|[ `Reflow Maven Skin`](https://olamy\.github\.io/reflow\-maven\-skin/)|[ Olivier Lamy](https://github\.com/olamy)|Responsive Apache Maven skin to reflow the standard Maven site with a modern feel\.| +|[ `Reflow 2 Maven Skin`](https://devacfr\.github\.io/reflow\-maven\-skin/)|[ Friederich Christophe](https://github\.com/devacfr)|Responsive 2 Apache Maven skin to reflow the standard Maven site with a modern feel\.| +|[ `Docs Maven Skin`](http://docs\.bernardomg\.com/maven/docs\-maven\-skin/)|[ Bernardo Martínez Garrido](https://github\.com/Bernardo\-MG)|A minimalist and responsive Bootstrap\-based HTML5 skin for Maven Site, which will help to use it as a documentation site\.| +|[ `Bootstrap Site Skin`](https://stevecrox\.github\.io/maven\-site\-bootstrap\-skin//)|[ Stephen Crocker](https://github\.com/stevecrox/maven\-site\-bootstrap\-skin)|Responsive Maven Bootstrap Skin which has toggleable elements implemented based on the boostrap reference layouts\.| +|[ `Sentry Maven Skin`](https://sentrysoftware\.org/sentry\-maven\-skin/)|[ Sentry Software](https://github\.com/sentrysoftware/sentry\-maven\-skin)|Responsive skin, Bootstrap\-based, with local search, light/dark colors switch, WEBP conversion, etc\.| +## Instructions + +To use one of these skins in your project, you use the `skin` element of the [site descriptor](/plugins/maven\-site\-plugin/examples/sitedescriptor\.html)\. This is a regular artifact or dependency\-like element\. For example, to use the Maven Fluido Skin, you would include the this in your `site.xml` file: + +``` + + ... + + org.apache.maven.skins + maven-fluido-skin + 1.12.0 + + ... + +``` + diff --git a/content/markdown/users/getting-help.md b/content/markdown/users/getting-help.md new file mode 100644 index 0000000000..c659e08d3f --- /dev/null +++ b/content/markdown/users/getting-help.md @@ -0,0 +1,88 @@ +--- +title: Getting Help +author: + - Dennis Lundberg + - Karl Heinz Marbaise +date: 2007-07-24 +2015-06-17 +--- + + + + + + + + + + + + + + + + + + +# Getting Help + +So something didn't work as you expected it to? You think that _Maven is broken_\. What should you do? + +Here's a list of actions that you can take: + +## You did check the documentation, didn't you? + +Apart from the central Maven site, each of our plugins has a website\. Go to the [plugins page](\.\./plugins/index\.html) and follow the link to the plugin you are having problems with\. + +## Try the latest version of Maven or the plugin in question + +Before you start intensive investigations on your problem, you should try to update Maven and/or the plugins in question to the latest stable release\. After all, the issue you encounter might have been fixed already\. To find out what is the latest stable release version, consult [Maven's download section](\.\./download\.html) and the [plugin index](\.\./plugins/index\.html)\. + +## Search the user\-list archives + +Someone else might have experienced the same problem as you before\. A list of mail\-archives can be found on [mailing list index page](https://maven\.apache\.org/mailing\-lists\.html)\. Please search one of them before going any further\. + +## Ask on the user list + +Our community is very helpful, just ask it the right way\. See the references section, at the end of this page, for info on how to do that\. Subscribe to the [users\-list](https://maven\.apache\.org/mailing\-lists\.html) and describe your problem there\. Don't expect to get an answer right away\. Sometimes it takes a couple of days\. + +## Submit an issue + +If it turns out that there is indeed something wrong with Maven or one of the plugins, you should report it to our issue management system JIRA\. + +You don't need create JIRA issue only to ask us something \- in such case please first ask on [users\-list](https://maven\.apache\.org/mailing\-lists\.html) + +### Request new JIRA account + +Requesting for JIRA account is preferred if you plan to contribute to project by coding or testing by longer time\. + +This is so that we can communicate with you while we work together on the issue\. + +- please use your real name and surname if possible in public name field +- links to your public projects, social or professional profile can be appreciated +- you can also tell us a little about yourself and what you intend to use this account for + +Such information is useful to verify that account is requested for real user not a bot\. + +Go to the [Request a JIRA account](https://selfserve\.apache\.org/jira\-account\.html?project=maven) to request for a new account if you don't already have one\. + +### Where? + +If the problem is in one of the plugins, check the site of that plugin to get the correct link\. Each plugin has its own section in JIRA, so using the correct link is important\. Click on _Project Information_ and then _Issue Management_\. On that page you will find the correct link\. + +If the problem is in Maven itself you can find the appropriate link on the [issue management](https://maven\.apache\.org/issue\-management\.html) page\. + +### How? + +Just describing the problem is not enough\. It takes a developer a lot of time to make a usable POM to even attempt to assess the problem\. Issues that states problems without something usable to try out will be closed as incomplete\. + +Please attach a working POM, or a set of POMs, that we can download and run\. We appreciate reports, but if you don't have something usable for us it's incredibly hard for us to manage the issues\. A POM goes a long way to helping us resolve problems\. + +Create a POM that can be used to verify that it is a bug\. If your pom uses plugins, make sure that you have specified the version for each and every plugin\. If you don't, then we might not be using the same version as you are when we test it\. + +What we like best are patches that fixes the problem\. If you want to create a patch for an issue please read the [Maven Developer Guide](\.\./guides/development/guide\-maven\-development\.html) first\. + +## References + +- [How To Ask Questions The Smart Way](http://www\.catb\.org/~esr/faqs/smart\-questions\.html) +- [How to Get Support from Open Source Mailing Lists](http://opensourcestrategies\.blogspot\.com/2005/09/how\-to\-get\-support\-from\-open\-source\.html) diff --git a/content/markdown/users/index.md b/content/markdown/users/index.md new file mode 100644 index 0000000000..b347acd88e --- /dev/null +++ b/content/markdown/users/index.md @@ -0,0 +1,39 @@ +--- +title: Users Centre +author: + - Brett Porter +date: 2006-11-03 +--- + + + + + + + + + + + + + + + + + + +# Maven Users Centre + +This documentation centre is for those that have decided to use Maven to build their project, and would like to get started quickly, or are already using Maven and would like to add new functionality or fix a problem in their build\. + + +- [ Download Maven](\.\./download\.html) \- Download the latest version of Maven +- [ The 5 minute test](\.\./guides/getting\-started/maven\-in\-five\-minutes\.html) \- Learn how to use Maven in 5 minutes +- [ Getting Started Tutorial](\.\./guides/getting\-started/index\.html) \- An in depth tutorial once you've learned the basics +- [ Getting Help](\./getting\-help\.html) \- How to get help with Maven + + +## Reference + +- [ POM Reference](\.\./pom\.html) +- [ Settings Reference](\.\./settings\.html)