Improvement: Extended (and commented) POM for the case "Intellij IDEA, Maven project, Java modules"

[dtonhofer]

I was quite dissatisfied with the POM that comes with the examples, in particular because it didn't work out of the box and the plugin/java versions used were a bit old, so here is a completely new one. I tested running the sample program from the IDE and with maven, and in the latter case, both with the javafx-maven-plugin and the more standard exec-maven-plugin. Goals to download JavaDoc and Source jars has been added. Quite an experience.

(With maven, practically nothing that one finds on the Internet really works, documentation is incomplete, warnings and errors are obscure and lacking context, and one has to guess at the meaning of this or that configuration and debugging on the command line is a must. What's up with that?)

Anyway, here we go:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.openjfx</groupId>
    <artifactId>hellofx</artifactId>
    <version>1.0-SNAPSHOT</version>

    <!-- You don't need to install the OpenJFX SDK as all you need is in the Maven repository, -->
    <!-- although if you want to run the program in Intellij IDEA (rather than via maven), installing -->
    <!-- allows you to just set the "module path" to the SDK's "lib" directory. -->

    <!-- In IntellijIDEA 2024: -->

    <!-- COMPILING: -->
    <!--   Select 'right-mouse-button menu' > 'run maven' > 'clean install' or 'clean' then 'compile' -->

    <!-- RUNNING IN IDE if you have installed OpenJDX SDK with correct version number (for shorter command line): -->
    <!--   First, in 'Run' > 'Edit Configuration' > 'Modify Options' > 'Add VM options' -->
    <!--   add the following: -->
    <!--   ++module-path ${JAVAFXLIBDIR} ++add-modules javafx.base,javafx.controls,javafx.fxml,javafx.graphics -->
    <!--   where '++' should be replaced by two hyphen (used here because we are inside an XML comment) -->
    <!--   and ${JAVAFXLIBDIR} is the directory where the OpenJFX SDK .jar, .dll and .so files can be found. -->

    <!-- RUNNING VIA MAVEN + JAVAFX PLUGIN IN IDE: -->
    <!--   'Main Menu' > 'Run' > 'Run Maven Goal' > 'Plugins' > 'JavaFx Maven Plugin' > 'javafx:run' -->
    <!--   This will invoke the goal "javafx:run" of the "javafx-maven-plugin". -->
    <!--   With the 'Run New Maven Goal' menu entry, you can define that goal, and it will appear in the -->
    <!--   context menu as 'right-mouse-button menu' > 'run maven' > 'javafx:run' -->

    <!-- RUNNING VIA MAVEN + EXEC PLUGIN IN IDE: -->
    <!--   'Main Menu' > 'Run' > 'Run Maven Goal' > 'Plugins' > 'Exec Maven Plugin' > 'exec:exec' -->
    <!--   This will invoke the goal "exec:exec" of the "exec-maven-plugin". -->
    <!--   Note that the goal 'exec:java' will try to run the program in the VM of Maven, which won't work. -->
    <!--   With the 'Run New Maven Goal' menu entry, you can define that goal, and it will appear in the -->
    <!--   context menu as 'right-mouse-button menu' > 'run maven' > 'exec:exec' -->

    <!-- RUNNING VIA MAVEN IN COMMAND LINE w/o leaving the IDE (no need for OpenJDX SDK): -->
    <!-- Right-click on the project window and select "Open Terminal at the current Maven module path". -->
    <!-- Enter the command "mvn javafx:run" or for debugging output "mvn -X javafx:run". -->
    <!-- This will invoke the goal "javafx:run" of the "javafx-maven-plugin". -->

    <properties>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <!-- This is the latest OpenJavaFX version on 2024-09-26 (version of 2024-09-16) -->
        <!-- https://mvnrepository.com/artifact/org.openjfx/javafx-controls -->

        <javafx.version>23</javafx.version>

        <javafx.plugin.version>0.0.8</javafx.plugin.version>
        <compiler.plugin.version>3.13.0</compiler.plugin.version>
        <exec.plugin.version>3.4.1</exec.plugin.version>
        <dependency.plugin.version>3.8.0</dependency.plugin.version>

        <!-- If the Java target version is higher than the one used for the -->
        <!-- JavaFX libraries, the dependencies will be properly listed in -->
        <!-- "Project Structure" but the import statements won't work! -->

        <java.compiler.source.version>21</java.compiler.source.version>
        <java.compiler.target.version>21</java.compiler.target.version>

    </properties>

    <!-- To generate the dependency tree, use                               -->
    <!-- "View | Tool Windows | Maven" in IntelliJ IDEA                     -->
    <!-- or run "mvn dependency:tree" in the project directory.             -->
    <!-- We get:                                                            -->
    <!--                                                                    -->
    <!-- [INFO] org.openjfx:hellofx:jar:1.0-SNAPSHOT                        -->
    <!-- [INFO] +- org.openjfx:javafx-controls:jar:23:compile               -->
    <!-- [INFO] |  +- org.openjfx:javafx-controls:jar:linux:23:compile      -->
    <!-- [INFO] |  \- org.openjfx:javafx-graphics:jar:23:compile            -->
    <!-- [INFO] |     +- org.openjfx:javafx-graphics:jar:linux:23:compile   -->
    <!-- [INFO] |     \- org.openjfx:javafx-base:jar:23:compile             -->
    <!-- [INFO] |        \- org.openjfx:javafx-base:jar:linux:23:compile    -->
    <!-- [INFO] \- org.openjfx:javafx-fxml:jar:23:compile                   -->
    <!-- [INFO]    \- org.openjfx:javafx-fxml:jar:linux:23:compile          -->
    <!--                                                                    -->
    <!-- The topmost libraries appear also listed in the Intellij IDEA UI   -->
    <!-- "Project Structure" > "Project Settings" > "Libraries"             -->

    <dependencies>
        <!-- https://mvnrepository.com/artifact/org.openjfx/javafx-controls -->
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.openjfx/javafx-fxml -->
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>${javafx.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>

            <!-- Standard Java Compiler Plugin -->
            <!-- https://maven.apache.org/plugins/maven-compiler-plugin/ -->
            <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-compiler-plugin -->

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${compiler.plugin.version}</version>
                <configuration>
                    <source>${java.compiler.source.version}</source>
                    <target>${java.compiler.target.version}</target>
                </configuration>
            </plugin>

            <!-- We will use the dependency plugin to get the source and javadoc jars, too -->
            <!-- https://maven.apache.org/plugins/maven-dependency-plugin/ -->
            <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-dependency-plugin -->
            <!-- Source and javadoc jars will be obtained when phase "generate-sources" is run. -->
            <!-- This happens during compilation. -->
            <!-- For example, the following will appear in the local .m2 repository: -->
            <!-- .m2/repository/org/openjfx/javafx-graphics/23/javafx-graphics-23-javadoc.jar -->
            <!-- .m2/repository/org/openjfx/javafx-graphics/23/javafx-graphics-23-sources.jar -->
            <!-- Source and javadoc jars will be listed in Intellij IDEA's -->
            <!-- 'Project Structure' > 'Project Settings' > 'Libraries' -->
            <!-- and mouseover in the source code will work. -->

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>${dependency.plugin.version}</version>
                <executions>

                    <execution>
                        <id>get-source-jars</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <!-- https://maven.apache.org/plugins/maven-dependency-plugin/resolve-mojo.html -->
                            <goal>resolve</goal>
                        </goals>
                        <configuration>
                            <classifier>sources</classifier>
                        </configuration>
                    </execution>

                    <execution>
                        <id>get-javadoc-jars</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <!-- https://maven.apache.org/plugins/maven-dependency-plugin/resolve-mojo.html -->
                            <goal>resolve</goal>
                        </goals>
                        <configuration>
                            <classifier>javadoc</classifier>
                        </configuration>
                    </execution>

                </executions>
            </plugin>

            <!-- Special Plugin to run JavaFX programs -->
            <!-- To run non-JavaFX programs, one would use the "exec maven plugin" -->
            <!-- but it doesn't create the correct module path for JavaFX. -->
            <!-- https://github.com/openjfx/javafx-maven-plugin -->
            <!-- https://mvnrepository.com/artifact/org.openjfx/javafx-maven-plugin -->
            <!-- If you run the plugin's goal on the command line with the '-X' option like so: -->
            <!-- mvn -X javafx:run -->
            <!-- you will see the command line the plugin builds, which looks as follows, with ++ replaced by double dash -->

            <!-- ${JAVA_HOME}/bin/java -->
            <!-- ++module-path -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-base/23/javafx-base-23-linux.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-base/23/javafx-base-23.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-controls/23/javafx-controls-23-linux.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-controls/23/javafx-controls-23.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-fxml/23/javafx-fxml-23-linux.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-fxml/23/javafx-fxml-23.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-graphics/23/javafx-graphics-23-linux.jar -->
            <!-- ${HOME}/.m2/repository/org/openjfx/javafx-graphics/23/javafx-graphics-23.jar -->
            <!-- ++add-modules -->
            <!-- javafx.base,javafx.controls,javafx.fxml,javafx.graphics -->
            <!-- -classpath -->
            <!-- ${INTELLIJ_PROJECT_PATH}/target/classes -->
            <!-- org.openjfx.App -->

            <plugin>
                <groupId>org.openjfx</groupId>
                <artifactId>javafx-maven-plugin</artifactId>
                <version>${javafx.plugin.version}</version>
                <configuration>
                    <mainClass>org.openjfx.App</mainClass>
                </configuration>
            </plugin>

            <!-- Plugin to run non-JavaFX programs -->
            <!-- https://www.mojohaus.org/exec-maven-plugin/ -->
            <!-- https://www.mojohaus.org/exec-maven-plugin/examples/example-exec-for-java-programs.html -->
            <!-- The plugin provides 2 goals to help execute system and Java programs. -->
            <!-- https://mvnrepository.com/artifact/org.codehaus.mojo/exec-maven-plugin -->
            <!-- Use the goal 'exec:exec' not 'exec:java' as the latter runs Java programs in Maven's VM -->
            <!-- This plugin will create a file "target/modulepath" that contains the modulepath part -->
            <!-- of the command line. The java process will read it. -->

            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>${exec.plugin.version}</version>
                <configuration>
                    <executable>java</executable>
                    <arguments>
                        <argument>--module-path</argument> <!-- inject string into the command line -->
                        <modulepath/> <!-- inject the module path based on what's in the local maven .m2 repo  -->
                        <argument>--add-modules</argument> <!-- inject string into the command line -->
                        <argument>javafx.controls,javafx.fxml,javafx.graphics</argument> <!-- inject string into the command line -->
                        <argument>-classpath</argument> <!-- inject string into the command line -->
                        <classpath/> <!-- inject dependencies from the local maven .m2 repo  -->
                        <argument>org.openjfx.App</argument> <!-- the program -->
                    </arguments>
                </configuration>
            </plugin>

        </plugins>
    </build>
</project>