michael-o commented on code in PR #308:
URL: https://github.com/apache/maven-site/pull/308#discussion_r912527357
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
Review Comment:
not port, address!
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
Review Comment:
en dash, not hyphen
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
+
+### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
Review Comment:
same here
##########
content/markdown/configure.md:
##########
@@ -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,
Review Comment:
directory
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
Review Comment:
colon, not hyphen
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
Review Comment:
Applies to both Windows and POSIX-like
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
Review Comment:
Slash, not hyphen
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
Review Comment:
same here
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
Review Comment:
No, this one is not offcially documented and gone in Maven 4.
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
Review Comment:
same here
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
Review Comment:
```
D:\Entwicklung\Projekte\maven-project-info-reports-plugin [holy-moly ≡ +1 ~0
-0 !]> java --help
Unrecognized option: --help
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.
```
One hyphen, not two
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
Review Comment:
This wording is confusing, people would understand that files in `.mvn` or
`settings.xml` are to to read which is wrong. It solely skips the run command
scripts.
##########
content/markdown/configure.md:
##########
@@ -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.
-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.
Review Comment:
en dash
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
+
+### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
+
+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
Review Comment:
Impl detail
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
+
+### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
+
+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
+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`
Review Comment:
Both variables are wrong.
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
Review Comment:
executable
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
+
+### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
+
+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
+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`
-## `.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.
-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
Review Comment:
This must tell that is is per project
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
Review Comment:
same here
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
Review Comment:
executable
##########
content/markdown/configure.md:
##########
@@ -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.
-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.
-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`
Review Comment:
These are deprecated and superseded with new files.
##########
content/markdown/configure.md:
##########
@@ -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,
+which - based on several environment variables, project files and system files
as described below
+- constructs and runs the appropriate `java ...` command line which then
invokes the Java Virtual Machine (JVM)
+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.
+* `mvnDebug` - launches `mvn` in debug mode, waiting for a Java debugger to
attach to port `$MAVEN_DEBUG_ADDRESS` (default 8000).
-## `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%`
+
+The contents of this variable is placed in the `java` command _before_ the
class name, and
+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
+
+Use `java --help` and `java -X` to see what is possible in this particular JVM.
+
+<!--
+### `$MAVEN_ARGS`
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%`
+
+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.
+This is useful to get standard behaviour.
+
+### `$JAVA_HOME` - `%JAVA_HOME%`
+
+If set, the Java binary to be used must be found at `$JAVA_HOME/bin/java` or
an error will
+be reported. If not set, the Java binary is found in the `$PATH`.
+
+### `$MAVEN_DEBUG_OPTS` - `%MAVEN_DEBUG_OPTS%`
+
+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
+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`
-## `.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.
-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
+`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
+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`
Review Comment:
Same here
##########
content/markdown/configure.md:
##########
@@ -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.
-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.
-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`
-### `.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:
Review Comment:
Not a good tip because on a shared system everyone can see this command line.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@maven.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
