Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MNGSITE-414] clean up https /maven.apache.org/configure.html #308

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
142 changes: 108 additions & 34 deletions content/markdown/configure.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,42 +17,107 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
The configuration for Apache Maven usage itself and projects built with resides
in a number of places:

## `MAVEN_OPTS` environment variable:
Apache Maven ships with two launcher commands in the `${MAVEN_HOME}/bin` folder,
ravn marked this conversation as resolved.
Show resolved Hide resolved
which - based on several environment variables, project files and system files as described below
michael-o marked this conversation as resolved.
Show resolved Hide resolved
- constructs and runs the appropriate `java ...` command line which then invokes the Java Virtual Machine (JVM)
michael-o marked this conversation as resolved.
Show resolved Hide resolved
that actually runs Maven.

This variable contains parameters used to start up the JVM running Maven and
can be used to supply additional options to it. E.g. JVM memory
settings could be defined with the value `-Xms256m -Xmx512m`.
* `mvn` - normal way to run from the command line.
ravn marked this conversation as resolved.
Show resolved Hide resolved
* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
michael-o marked this conversation as resolved.
Show resolved Hide resolved
michael-o marked this conversation as resolved.
Show resolved Hide resolved

## `MAVEN_ARGS` environment variable:

## Environment variables

In the following the Unix syntax for environment variables is used in the text.

For Windows the syntax is slightly different, for `$A` use `%A%`.

### `$MAVEN_OPTS` - `%MAVEN_OPTS%`
ravn marked this conversation as resolved.
Show resolved Hide resolved

The contents of this variable is placed in the `java` command _before_ the class name, and
ravn marked this conversation as resolved.
Show resolved Hide resolved
can therefore be used to provide additional arguments to the Java Virtual Machine (JVM) without
having to specify them on the command line every time.

Examples include garbage collector and memory configuration, but _not_ options to Maven itself
ravn marked this conversation as resolved.
Show resolved Hide resolved

Use `java --help` and `java -X` to see what is possible in this particular JVM.
michael-o marked this conversation as resolved.
Show resolved Hide resolved

<!--
### `$MAVEN_ARGS`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applies to both Windows and POSIX-like


Starting with Maven 4, this variable contains arguments passed to Maven before
CLI arguments. E.g., options and goals could be defined with the value
`-B -V checkstyle:checkstyle`.
-->

### `$MAVEN_BASEDIR` - `%MAVEN_BASEDIR%`
ravn marked this conversation as resolved.
Show resolved Hide resolved

If set, this is considered the base directory of the Maven project. If not set,
the launcher scripts search for a `.mvn` folder towards the root of the drive, and if
found consider that the base directory.


### `$MAVEN_SKIP_RC` - `%MAVEN_SKIP_RC%`

If set, tells the launcher scripts _not_ to read the various Maven configuration files.
michael-o marked this conversation as resolved.
Show resolved Hide resolved
This is useful to get standard behaviour.

### `$JAVA_HOME` - `%JAVA_HOME%`
michael-o marked this conversation as resolved.
Show resolved Hide resolved

If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or an error will
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

executable

be reported. If not set, the Java binary is found in the `$PATH`.
ravn marked this conversation as resolved.
Show resolved Hide resolved

### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
michael-o marked this conversation as resolved.
Show resolved Hide resolved

Additional options for the JVM if needed.
They are put after `$MAVEN_OPTS` and before the `-classpath` argument.

## Files

## `settings.xml` file:
Files in `$MAVEN_BASEDIR` and below are part of your project and may be checked
michael-o marked this conversation as resolved.
Show resolved Hide resolved
into source control.

Located in USER_HOME/.m2 the settings files is designed to contain any
configuration for Maven usage across projects.
### `$USER/.m2/settings.xml` - `%USER_HOME%\.m2\settings.xml`
michael-o marked this conversation as resolved.
Show resolved Hide resolved

## `.mvn` directory:
This contains the user-specific Maven setup used across projects.
Often this is used to tell Maven to use an internal repository instead of Maven Central if behind a firewall,
various profiles, and passwords.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

something looks missing here?


Located within the project's top level directory, the files `maven.config`, `jvm.config`, and `extensions.xml`
contain project specific configuration for running Maven.
<!--

This directory is part of the project and may be checked in into your version control.
### `$MAVEN_BASEDIR/.mvn/maven.config`:

### `.mvn/extensions.xml` file:
FIXME: IS THIS STILL THE CASE? LAUNCHER SCRIPTS DOES NOT LOOK FOR IT?!?

The old way (up to Maven 3.2.5) was to create a jar (must be shaded if you have other dependencies) which contains the extension and put
it manually into the `${MAVEN_HOME}/lib/ext` directory. This means you had to change the Maven installation. The consequence was that everyone
who likes to use this needed to change it’s installation and makes the on-boarding for a developer much more inconvenient. The other
option was to give the path to the jar on command line via `mvn -Dmaven.ext.class.path=extension.jar`. This has the drawback giving those
options to your Maven build every time you are calling Maven. Not very convenient as well.
This file contains additional command line arguments added to every invocation of Maven.

For example things like `-T3 -U --fail-at-end`.
So you only have to call Maven just by using `mvn clean package`
instead of `mvn -T3 -U --fail-at-end clean package`.

-->

### `$MAVEN_BASEDIR/.mvn/jvm.config`:

Allows a persistable alternative to `$MAVEN_OPTS` for providing
additional arguments to the JVM before the class name on the constructed
ravn marked this conversation as resolved.
Show resolved Hide resolved
`java ...` command line. Sample contents:

-Xmx2048m -Xms1024m -XX:MaxPermSize=512m -Djava.awt.headless=true

Word of caution: If you for any reason need to configure memory usage or the garbage collector - which should
michael-o marked this conversation as resolved.
Show resolved Hide resolved
be considered a last resort - be absolutely certain that the configuration you use
applies to the version of the JVM you are using, and that you understand what you are doing.


### `$MAVEN_BASEDIR/.mvn/extensions.xml`
ravn marked this conversation as resolved.
Show resolved Hide resolved

FIXME: WHERE IS THIS DONE? IS THIS MAVEN 4 FUNCTIONALITY?

If you for any reason needs additional artifacts put on the classpath used by Maven,
simply list them here with their usual Maven coordinates.

From now on this can be done much more simpler and in a more Maven like way. So you can define an `${maven.projectBasedir}/.mvn/extensions.xml` file which looks like the following:

```xml
<extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand All @@ -65,26 +130,35 @@ From now on this can be done much more simpler and in a more Maven like way. So
</extensions>
```

Now you can simply use an extension by defining the usual maven coordinates groupId, artifactId, version as any other artifact. Furthermore all transitive dependencies of those extensions will automatically being downloaded from your repository. So no need to create a shaded artifact anymore.
### `/usr/local/etc/mavenrc` + `/etc/mavenrc` + `$HOME/.mavenrc`

### `.mvn/maven.config` file:
Unix-like systems only:
Configuration files executed by the Unix launcher scripts first thing, unless
if the environment variable `$MAVEN_SKIP_RC` is set.
ravn marked this conversation as resolved.
Show resolved Hide resolved

It’s really hard to define a general set of options for calling the maven command line. Starting with Maven 3.3.1+, this can be solved by
putting this
options to a script but this can now simple being done by defining `${maven.projectBasedir}/.mvn/maven.config` file which contains the
configuration options for the `mvn` command line.
Typically environment variables - including `$PATH` - are set here.
michael-o marked this conversation as resolved.
Show resolved Hide resolved

For example things like `-T3 -U --fail-at-end`. So you only have to call Maven just by using `mvn
clean package` instead of `mvn -T3 -U --fail-at-end clean package` and not to miss the `-T3 -U --fail-at-end` options on every call. The
`${maven.projectBasedir}/.mvn/maven.config` is located in the `${maven.projectBasedir}/.mvn/` directory; also works if in the root of a multi module build.
### `%USERPROFILE%\mavenrc_pre.bat` + `%USERPROFILE%\mavenrc_pre.cmd`
ravn marked this conversation as resolved.
Show resolved Hide resolved

### `.mvn/jvm.config` file:
Windows systems only:
Configuration files executed by the Windows launcher scripts first thing _before_ launching the Maven JVM,
unless if the environment variable `%MAVEN_SKIP_RC%` is set.

Starting with Maven 3.3.1+ you can define JVM configuration via `${maven.projectBasedir}/.mvn/jvm.config` file which means you can define the options for your build on a per project base. This file will become part of your project and will be checked in along with your project. So no need anymore for `MAVEN_OPTS`, `.mavenrc` files. So for example if you put the following JVM options into the `${maven.projectBasedir}/.mvn/jvm.config` file
This can be used to provide secrets, like the password for a keystore:
ravn marked this conversation as resolved.
Show resolved Hide resolved

-Xmx2048m -Xms1024m -XX:MaxPermSize=512m -Djava.awt.headless=true
```
set MAVEN_OPTS=-Djavax.net.ssl.keyStore="<path to p12 file>" -Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStorePassword=<password>
```

### `%USERPROFILE%\mavenrc_post.bat` + `%USERPROFILE%\mavenrc_post.cmd`

Windows systems only:
Configuration files executed by the Windows launcher scripts _after_ the Maven JVM itself exits, unless
if the environment variable `%MAVEN_SKIP_RC%` is set.


---

You don't need to use these options in `MAVEN_OPTS` or switch between different configurations.

## Other guides

Expand Down