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.

Sign up for GitHub

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

Jump to bottom

[MNG-8395] Add a <Source> element in the model. #1936

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

[MNG-8395] Add a <Source> element in the model. #1936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f2aae0
Add a <Source> element in the model. Properties are:
desruisseaux Aug 11, 2024
fce3d38
Resolve an ambiguity in the description of `target` behavior.
desruisseaux Nov 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 190 additions & 0 deletions api/maven-api-model/src/main/mdo/maven.mdo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -775,6 +775,7 @@
<type>String</type>
</field>
<field>
<!-- TODO: replaced by <Source> with "resource" scope. -->
<name>resources</name>
<version>3.0.0+</version>
<description>
Expand All @@ -789,6 +790,7 @@
</association>
</field>
<field>
<!-- TODO: replaced by <Source> with "testResource" scope. -->
<name>testResources</name>
<version>4.0.0+</version>
<description>
Expand Down Expand Up @@ -857,6 +859,22 @@
</description>
<fields>
<field>
<name>sources</name>
<version>4.1.0+</version>
<description>
All the sources to compile and resources files to copy for a project or it's unit tests.
The sources can be Java source files, generated source files, scripts or resources for examples.
Each source is specified by a mandatory {@code directory} element, which is relative to the POM.
The kind of sources (codes to compile or resources to copy) and their usage (for the main code
or for the tests) is specified by the {@code scope} element together with each source directory.
</description>
<association>
<type>Source</type>
<multiplicity>*</multiplicity>
</association>
</field>
<field>
<!-- TODO: replaced by <Source> with "main" scope. -->
<name>sourceDirectory</name>
<version>3.0.0+</version>
<required>true</required>
Expand All @@ -869,6 +887,7 @@
<type>String</type>
</field>
<field>
<!-- TODO: replaced by <Source> with "script" scope. -->
<name>scriptSourceDirectory</name>
<version>4.0.0+</version>
<required>true</required>
Expand All @@ -882,6 +901,7 @@
<type>String</type>
</field>
<field>
<!-- TODO: replaced by <Source> with "test" scope. -->
<name>testSourceDirectory</name>
<version>4.0.0+</version>
<required>true</required>
Expand Down Expand Up @@ -1945,6 +1965,176 @@
</codeSegments>
</class>
<class>
<name>Source</name>
<description>
<![CDATA[
Description of the sources associated with a project main code or unit tests.
The sources can be Java source files, generated source files, scripts or resources for examples.
A source is specified by a mandatory {@code directory} element, which is relative to the POM.
The directory content can optionally by reduced to a subset with the {@code includes} and
{@code excludes} elements. The kind of sources (codes, resources, <i>etc.</i>) and their
usage (main code, tests, <i>etc.</i>) is specified by the {@code scope} element.

<h2>Default source directories</h2>
If no source directories are specified, the defaults are {@code src/${scope}/${lang}} where
{@code ${scope}} is the value of the {@link #scope} element (typically {@code main} or {@code test}) and
{@code ${lang}} is the value of the {@link #lang} element (typically {@code java} or {@code resources}).
]]>
</description>
<version>4.1.0+</version>
<superClass>FileSet</superClass>
<fields>
<field>
<name>scope</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Specifies in which context the source files will be used - typically {@code main} or {@code test}.

<p>The <b>main</b> scope is used for specifying a directory containing the source of the project.
The generated build system will compile the sources from this directory when the project is built.
The path given in the {@code directory} field is relative to the project descriptor.
The default directory for the default language (Java) is {@code "src/main/java"}.</p>

<p>The <b>test</b> scope is used for specifying a directory containing the unit test source of the project.
The generated build system will compile these directories when the project is being tested.
The path given in the {@code directory} field is relative to the project descriptor.
The default directory for the default language (Java) is {@code "src/test/java"}.</p>

<p>If no scope is specified, the default is {@code main}.</p>
]]>
</description>
<type>String</type>
<defaultValue>main</defaultValue>
</field>
<field>
<name>lang</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Specifies the language of the source files - typically {@code java} or {@code resources}.
Resources is used as a generic term for scripting languages (e.g., JavaScript or Python)
or markup languages (e.g. properties file, <abbr>JSON</abbr> or <abbr>XML</abbr>).

<p>The <b>java</b> language is used for specifying a directory containing the Java sources of the project.
The generated build system will compile the sources from this directory using the Java compiler when the
project is built. The path given in the {@code directory} field is relative to the project descriptor.
The default directory for the main Java sources is {@code "src/main/java"}.</p>

<p>The <b>resources</b> language is used for specifying a directory containing the class-path
or module-path resources such as properties files or scripts associated with a project.
This directory is meant to be different from the main source directory,
in that its contents will be copied to the output directory in most cases
(since scripts are interpreted rather than compiled).
The default directory for the main resources is {@code "src/main/resources"}.</p>

<p>If no language is specified, the default is {@code java}.</p>
]]>
</description>
<type>String</type>
<defaultValue>main</defaultValue>
</field>
<field>
<name>module</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Name of the Java module (or other language-specific module) which is built by the sources.
This element can be specified in a Maven project containing multiple Java modules.
It is generally not needed for non-modular projects, or for modular projects having only one module.

<p>If a module name is specified for resources or script files,
then this value modifies the directory where the files will be copied.
For example, if a Java module name is "foo.biz", then the {@code foo/bar.properties}
resource file will be copied as {@code foo.biz/foo/bar.properties}.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

Is that a Maven convention, a Java convention, or something imposed by the JVM ?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It is a Java compiler convention. In a multi-modules project, javac automatically inserts module names at the root of class directories. For example, if a module named my.foo.module contains a foo.bar.biz.Bla class, then in single-module project (as today), javac generates the following file in the Maven target/classes/ directory:

  • foo/bar/biz/Bla.class

But in a multi-modules project (would be optional and not the default), javac generates the same file at the following location instead:

  • my.foo.module/foo/bar/biz/Bla.class

Other Java tools such as java understand this directory hierarchy. I.e. the --module-path can be a directory of modules, with no need to enumerate on the path each module found in the directory. I'm not sure if it is a requirement that the directory names match module names, but this is what javac does at least by default.

Above documentation of module element tries to match what javac does. It could be rephrased as "During Java compilation, we let javac do whatever it wants. For resources, we try to copy them in the same directory as javac". The current wording tries to be more specific about what happens, but the goal is to match javac and the documentation would be updated if we find mismatches.


<p>This element can be combined with the {@code targetVersion} element for specifying sources,
scripts or resources that are specific to both a particular module and a target version.</p>
]]>
</description>
<type>String</type>
</field>
<field>
<name>targetVersion</name>
<version>4.1.0+</version>
<description>
<![CDATA[
The version of the platform where the code will be executed.
In a Java environment, this is the value of the {@code --release} compiler option.
If a Java project contains multiple main sources with different target versions,
then a multi-version <abbr>JAR</abbr> file will be created
with the lowest version taken as the <dfn>base version</dfn>.
If this element is omitted, then the default target version is the compiler default value,
which is usually the version of the Java environment running Maven.

<p>If a target version, different from the base version, is specified for resources or script files,
then this value modifies the directory where the files will be copied.
For example, if {@code targetVersion} is 17, then the {@code foo/bar.properties}
resource file will be copied as {@code META-INF/versions/17/foo/bar.properties}.</p>

<p>This element can be combined with the {@code module} element for specifying sources,
scripts or resources that are specific to both a particular module and a target version.</p>
]]>
</description>
<type>String</type>
</field>
<field>
<name>targetPath</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Specifies an explicit target path, overriding the default value.
The path is relative to the {@code ${project.build.outputDirectory}} directory,
which is typically {@code target/classes} in a Java project.

<p>When a target path is explicitly specified, the values of the {@code module} and {@code targetVersion}
elements are not used for inferring the path (they are still used as compiler options however).
It means that for scripts and resources, the files below the path specified by {@code directory}
are copied to the path specified by {@code targetPath} with the exact same directory structure.
It is user's responsibility to put module and version components in the {@code targetPath} if needed.</p>

<p>Note that for Java source files, a directory with the module name may still be generated despite
above statement about {@code module} being ignored, because that directory is generated by the Java
compiler rather than Maven.</p>
]]>
</description>
<type>String</type>
</field>
<field>
<name>stringFiltering</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Whether resources are filtered to replace tokens with parameterized values.
The values are taken from the {@code properties} element and from the properties
in the files listed in the {@code filters} element.

<p>The default value is {@code false}.</p>
]]>
</description>
<type>boolean</type>
<defaultValue>false</defaultValue>
</field>
<field>
<name>enabled</name>
<version>4.1.0+</version>
<description>
<![CDATA[
Whether the directory described by this source element should be included in the build.
Copy link
Contributor

Choose a reason for hiding this comment

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

Would it make sense to reuse the new condition syntax here ?
https://maven.apache.org/ref/4-LATEST/apidocs/org/apache/maven/api/model/Activation.html#condition-syntax-heading

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I guess so. I wasn't aware of that. How should we express that?

This flag provides an easy way to include or exclude some sources depending, for example,
o property values defined in profiles. A use case is including optional resources only
when the user confirmed a license agreement.

<p>The default value is {@code true}.</p>
]]>
</description>
<type>boolean</type>
<defaultValue>true</defaultValue>
</field>
</fields>
</class>
<class>
<!-- TODO: Replaced by <Source>. -->
<name>Resource</name>
<description>This element describes all of the classpath resources associated with a project
or unit tests.</description>
Expand Down
Loading