mthmulders commented on code in PR #598: URL: https://github.com/apache/maven-site/pull/598#discussion_r1965446022
########## content/markdown/whatsnewinmaven4.md: ########## @@ -0,0 +1,476 @@ +<!-- +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. +--> + +<head> + <title>What's new in Maven 4?</title> + <meta name="author" content="Matthias Bünger" /> +</head> + +# What's new in Maven 4? + +Maven is over 20 years old, and is the most widely used build tool in the Java world. +Throughout the years, Maven has maintained backward compatibility, especially of its [POM file][2] with Model version +4.0.0. + +The POM file fulfills two needs. +First, the POM holds all the information and configuration, which are needed to build the artifact. +After the artifact is created, this build information is not relevant anymore. +Second, the POM also contains information, for example dependencies, which are needed by projects which depend on the +artifact. +These dependent projects are called the "consumers". + +This made Maven more than a tool; it became a whole ecosystem with many dependencies on the POM, especially the +Maven Central repository, other build tools, and IDEs. +Thus, any change in the POM's schema forces each participant of the ecosystem to either adopt the change or drop +support. +Thus, the Maven POM syntax became fixed, unable to change. + +> "With the Maven build schema preserved in amber, we can’t evolve much: we’ll stay forever with Maven 3 minor releases, +> +>> unable to implement improvements that we imagine will require seriously updating the POM schema…" +>> — <cite>[Hervé Boutemy (in Javaadvent 2021)][1]</cite> + +In order for Maven to evolve, it's necessary to separate the information needed for the build from the information +needed by the consumers, but without breaking the ecosystem. +Maven 4 prepares for this and more. + +This article presents and explains major changes brought by Maven 4, grouped into several topics. + +## Required Java version + +The required Java version to run Maven 4 is Java 17. +This allows Maven (and its maintainers) to make use of newer language features and improvements brought by the +JDK. + +**Important note**: Java 17 is only needed to **run Maven**! +You can still compile against older Java versions using the same [compiler plugin configuration][6] as before. +If you need to compile against or use another JDK, see the [Guide to Using Toolchains][7] (or the +article [Introduction to Maven Toolchains][8] by Maven maintainer Maarten Mulders). + +## POM Changes + +### Build POM and consumer POM + +In Maven 3 both the build and consumers use the same POM file with model version 4.0.0. +However, several parts of the POM are only necessary for the build while others, like the dependencies, are also +needed by the consumers. +Maven 4 therefore differentiates between a build POM and a consumer POM. +As the names suggest, the build POM contains all information needed to build the artifact, for example applied plugins +and their configuration, while the consumer POM, which is created during the Maven build, only contains what is +necessary to use an artifact as a dependency. +This POM will only keep what is really needed to use the artifact, for example dependency information. + +**Note**: See below for a comparison of the content of both POMs. + +### Model version 4.1.0 + +Maven 4 introduces a new POM version 4.1.0. +With two types of POM, Maven 4 can make additions to the build POM as it is only be used by Maven. +Version 4.1.0 adds some new elements and attributes, while others are marked as deprecated. +To not break the ecosystem, this version is only available for the build POM, while the consumer POM will still use +version 4.0.0. +Maven generates the consumer POM during the build from the build POM. + +**Note**: Maven 4 will continue to build your model version 4.0.0 project. +There is no need to update your POMs to 4.1.0 if you don't need to use the new features. + +### Modules are now subprojects + +A Maven project is any Java project built with Maven. +The [root directory][32] of a Maven project contains at least the source folder `src` and the project's POM file +`pom.xml`. +A Maven project may have other Maven projects within subdirectories, each with its own `pom.xml` file. +Each project within a subdirectory is called a "subproject". + +Example: A project A contains a subdirectory which contains its own POM file for project B. +We say that B is a subproject of A. + +However, Maven does not build subprojects unless they are linked from the root POM file. +In the past this was done by listing each subproject in the `<modules>` section of the parent's POM. +Projects which have at least one subproject are called "multi-module projects", while those which have any subprojects +are called "single module projects". +Since the introduction of the [Java Platform Module System][3] in Java 9, the term "module" has raised additional +confusion inside the Maven community. + +Maven 4 gets rid of this by renaming modules to projects and submodules to subprojects. +Model version 4.1.0 contains a new `<subprojects>` element analogous to the now deprecated, but still usable, +`<modules>` element. + +**Note**: Use the terms `multi-project setup` and `single-project setup` to differentiate between a Maven project with +or without subprojects. + +### New packaging type: bom + +Maven 4 introduces a dedicated `bom` packaging type to provide a [Bill of Materials BOM][4]. +This now differentiates between parent POMs and dependency-managing BOMs. +The new type is only available as a build POM in Model Version 4.1.0 and later, but Maven generates a full Maven 3 +compatible consumer POM during the build. +For an example, see the link above or +the [live coding by Maven maintainer Karl Heinz Marbaise at IntelliJ IDEA Conf 2024][5]. + +**Note**: With Maven 4, it's also possible to exclude dependencies that are declared by BOMs using the existing +`<exclusions>` element. +Also note that in Maven 4, importing BOMs with a classifier is now possible. +Therefore, the Maven team suggests that project BOMs should be generated as classified artifacts, using the +`<bomClassifier>` element. +This means that an imported BOM must **not** come from the same reactor as the current build but be available outside +the project before the build. +In other words: you should only import external BOMs. +That's why Maven 4.0 will show a warning if a BOM comes from the same reactor. +In the future, this will most probably be changed to make the build fail. + +### Comparing build POM and consumer POM + +The following table shows a rough comparison of which content is available in which POM type when using Maven 4. + +**Notes**: + +* The column "consumer POM" does not apply to artifacts that are of type "pom", because "pom"-artifacts are designed to + contain build information, for example plugin configuration! +* Some of the build-related content which is (as of now) still available in the consumer POM might be available only in + the build POM in the future. + +| Content | Build POM | Consumer POM | +|:-------------------------------------------|:---------:|:------------:| +| Model version | 4.1.0 | 4.0.0 | +| 3rd party dependency information | ✅ | ✅ | +| POM properties | ✅ | ❌ | +| Plugin configuration | ✅ | ❌ | +| Repository information | ✅ | ✅ | +| Project information / environment settings | ✅ | ✅ | +| Deployment to remote repository | ✅ | ✅ | + +**Warning**: There are rare situations where Maven 4 will produce a consumer POM based on version 4.1.0, for example +when +condition-based profiles (see below) can't be transformed to version 4.0.0. +Maven will show a warning in such situations. + +### Declaring the root directory and directory properties + +Every time Maven executes a build, it has to determine the project's root to identify things like the parent project, +directory information, and so on. +To "help" Maven find the root folder, you can create a `.mvn` folder in your root directory. +This folder is intended to contain project-specific configuration to run Maven, for example a `maven.config` or +`jvm.config` +file, and therefore was also considered as the root folder. +With Maven 4, there is a second option to clearly define the root folder. +Model version 4.1.0, usable for the build POM, adds a boolean attribute called `root` in the `<project>` element. +When this attribute is set to true (default is false), the directory of this POM file is considered the root directory. + +Another pain point in relation to the root directory is that until Maven 4, there was no official property to make use +of the root folder in your POM files, for example when you want to define the path to a `checkstyle-suppressions.xml` +file for the checkstyle plugin. +Maven 4 now provides official properties to reference the root directory in your POM configuration. +The following table shows the official properties. + +| Property | Scope | Definition | Always | +|:---------------------------|:-------:|:------------------------------------------------------------------------|:------:| +| `${project.rootDirectory}` | Project | `.mvn` folder or `root` attribute in pom | No | +| `${session.topDirectory}` | Session | Current directory or `--file` argument | Yes | +| `${session.rootDirectory}` | Session | `.mvn` folder or `root` attribute in pom for the `topDirectory` project | No | + +As you can see, these properties differentiate by their scope, where `project` is always related to the Maven project's +definition (you could interpret this as the POM files) and `session` is the actual execution of a Maven build and is the +current working directory. Review Comment: AFAIK, "session" is the execution of Maven, not the current working directory. -- 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
