From 3dccdf802184dc0749cd7437d4a11181780d74d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lennart=20Jo=CC=88relid?= Date: Sat, 10 Aug 2013 10:18:51 +0200 Subject: [PATCH 1/2] FORGE-1030: Added documentation about what needs to be done to utilize multi-module reactors for Forge plugins. --- .../reference-libraries.textile | 32 ++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/plugin_development/reference-libraries.textile b/docs/plugin_development/reference-libraries.textile index 1689148..808edb4 100644 --- a/docs/plugin_development/reference-libraries.textile +++ b/docs/plugin_development/reference-libraries.textile @@ -18,7 +18,37 @@ bc(prettyprint linenums).. p. This will cause Forge to bundle all dependencies for your Plugin in the Plugin module itself, instead of creating a separate "dependencies" module, with a separate ClassLoader. -p. *Note!* When you configure Forge to use the "dependencies-as-resource-root" option, your project must explicitly import any transitive Maven dependencies, as the Forge ClassLoader structure prevents transitive dependencies to be "seen" by your plugin. A good help to find all transitive dependencies is the "mvn dependency:tree" command, which should be run in your Plugin's Maven project. +h3. Multi-module reactors and Forge plugins + +p. If your Forge plugin resides in a reactor consisting of multiple Maven projects, you need to do the following to ensure that the Forge plugin can be correctly installed: + +# In the project holding the plugin implementation, add a META-INF/forge.xml file using the "dependencies-as-resource-root" option, as shown above. +# Any Maven projects in the using Forge APIs must explicitly import any transitive Maven dependencies, as the Forge ClassLoader structure prevents transitive dependencies to be "seen" by your plugin. A good help to find all transitive dependencies is the "mvn dependency:tree" command, which should be run in your Plugin's Maven project. To simplify the process of importing transitive Maven plugins in several projects, define those dependencies in the dependencyManagement section of the reactor root POM. Then supply explicit dependencies without version constants in other project POMs as needed. +# If your projects normally require unit tests to be run in order to pass the build (typically when your POMs define Maven plugins breaking the build if unit test coverage does not meet defined requirements): Add a Maven profile (called "install_forge" in the example below) which is activated by the Maven property "skipTests" being true. Since Forge runs the plugin installation without unit tests, your maven reactor must define a profile to ensure that the Forge installer does not fail due to your unit tests not being executed. + +p. A skeleton "install_forge" profile should look similar to the code snippet below. This is the standard behavior of the Maven Surefire Plugin, implying unit tests are not executed in the build. + +bc(prettyprint linenums).. + + + install_plugin + + + skipTests + true + + + + + ... + + + +h3. Using the Shade plugin As a last resort, you may also shade code into your plugin's JAR file; however, this is extremely discouraged, since you may cause ClassCastExceptions at runtime, and this increases the burden on Class scanning at boot time, because CDI will scan all classes in your Plugin JAR file. From 457502eb67827726bc7f38e1b6639f53111e49d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lennart=20Jo=CC=88relid?= Date: Sat, 10 Aug 2013 21:43:40 +0200 Subject: [PATCH 2/2] Changed the skipTests property to maven.test.skip, to comply with Forge behavior. --- docs/plugin_development/reference-libraries.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugin_development/reference-libraries.textile b/docs/plugin_development/reference-libraries.textile index 808edb4..73d9e95 100644 --- a/docs/plugin_development/reference-libraries.textile +++ b/docs/plugin_development/reference-libraries.textile @@ -24,7 +24,7 @@ p. If your Forge plugin resides in a reactor consisting of multiple Maven projec # In the project holding the plugin implementation, add a META-INF/forge.xml file using the "dependencies-as-resource-root" option, as shown above. # Any Maven projects in the using Forge APIs must explicitly import any transitive Maven dependencies, as the Forge ClassLoader structure prevents transitive dependencies to be "seen" by your plugin. A good help to find all transitive dependencies is the "mvn dependency:tree" command, which should be run in your Plugin's Maven project. To simplify the process of importing transitive Maven plugins in several projects, define those dependencies in the dependencyManagement section of the reactor root POM. Then supply explicit dependencies without version constants in other project POMs as needed. -# If your projects normally require unit tests to be run in order to pass the build (typically when your POMs define Maven plugins breaking the build if unit test coverage does not meet defined requirements): Add a Maven profile (called "install_forge" in the example below) which is activated by the Maven property "skipTests" being true. Since Forge runs the plugin installation without unit tests, your maven reactor must define a profile to ensure that the Forge installer does not fail due to your unit tests not being executed. +# If your projects normally require unit tests to be run in order to pass the build (typically when your POMs define Maven plugins breaking the build if unit test coverage does not meet defined requirements): Add a Maven profile (called "install_forge" in the example below) which is activated by the user property "maven.test.skip" being true. Since Forge runs the plugin installation without unit tests, your maven reactor must define a profile to ensure that the Forge installer does not fail due to your unit tests not being executed. p. A skeleton "install_forge" profile should look similar to the code snippet below. This is the standard behavior of the Maven Surefire Plugin, implying unit tests are not executed in the build. @@ -38,7 +38,7 @@ bc(prettyprint linenums).. install_plugin - skipTests + maven.test.skip true