diff --git a/spring-boot-docs/pom.xml b/spring-boot-docs/pom.xml index 5f9c4e1a8b..9918f200d1 100644 --- a/spring-boot-docs/pom.xml +++ b/spring-boot-docs/pom.xml @@ -223,6 +223,31 @@ + + org.apache.maven.plugins + maven-dependency-plugin + + + unpack-maven-plugin + generate-resources + + unpack + + + + + org.springframework.boot + spring-boot-maven-plugin + ${project.version} + site + zip + ${project.build.directory}/contents + + + + + + org.apache.maven.plugins maven-antrun-plugin diff --git a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc index 7bc34672de..1613aecc0d 100644 --- a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc +++ b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc @@ -15,7 +15,7 @@ unsupported build system. If you are just getting started, you might want to rea [[build-tool-plugins-maven-plugin]] == Spring Boot Maven plugin -The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to +The {mp-root}/[Spring Boot Maven Plugin] provides Spring Boot support in Maven, allowing you to package executable jar or war archives and run an application ``in-place''. To use it you must be using Maven 3 (or better). @@ -151,145 +151,7 @@ need to mark the embedded container dependencies as ``provided'', e.g: ---- - - -[[build-tool-plugins-maven-packaging-configuration]] -=== Repackage configuration -The following configuration options are available for the `spring-boot:repackage` goal: - - - -[[build-tool-plugins-maven-packaging-required-params]] -==== Required parameters -[cols="2,4"] -|=== -|Name |Description - -|`outputDirectory` -|Directory containing the generated archive (defaults to `${project.build.directory}`). - -|`finalName` -|Name of the generated archive (defaults to `${project.build.finalName}`). -|=== - - - -[[build-tool-plugins-maven-packaging-optional-params]] -==== Optional parameters -[cols="2,4"] -|=== -|Name |Description - -|`classifier` -|Classifier to add to the generated artifact. If given, the artifact will be attached. If - this is not given, it will merely be written to the output directory according to the - `finalName`. Attaching the artifact allows to deploy it alongside to the original one, - see http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-with-classifiers.html[ - the maven documentation for more details] - -|`mainClass` -|The name of the main class. If not specified will search for a single compiled class - that contains a `main` method. - -|`layout` -|The type of archive (which corresponds to how the dependencies are laid out inside it). - Defaults to a guess based on the archive type. -|=== - -The plugin rewrites your manifest, and in particular it manages the `Main-Class` and -`Start-Class` entries, so if the defaults don't work you have to configure those there -(not in the jar plugin). The `Main-Class` in the manifest is actually controlled by the -`layout` property of the boot plugin, e.g. - -[source,xml,indent=0,subs="verbatim,attributes"] ----- - - org.springframework.boot - spring-boot-maven-plugin - {spring-boot-version} - - ${start-class} - ZIP - - - - - repackage - - - - ----- - -The layout property defaults to a guess based on the archive type (jar or war). For the -`PropertiesLauncher` the layout is ``ZIP'' (even though the output might be a jar file). - -TIP: The executable jar format is <>. - -[[build-tool-plugins-maven-running-applications]] -=== Running applications -The Spring Boot Maven Plugin includes a `run` goal which can be used to launch your -application from the command line. Type the following from the root of your Maven -project: - -[indent=0] ----- - $ mvn spring-boot:run ----- - -By default, any `src/main/resources` folder will be added to the application classpath -when you run via the maven plugin. This allows hot refreshing of resources which can be -very useful when developing web applications. For example, you can work on HTML, CSS or -JavaScipt files and see your changes immediately without recompiling your application. It -is also a helpful way of allowing your front end developers to work without needing to -download and install a Java IDE. - - - -[[build-tool-plugins-maven-run-configuration]] -=== Run configuration -The following configuration options are available for the `spring-boot:run` goal: - - - -[[build-tool-plugins-maven-run-configuration-required-params]] -=== Required parameters -[cols="2,4"] -|=== -|Name |Description - -|`classesDirectrory` -|Directory containing the classes and resource files that should be packaged into the - archive (defaults to `${project.build.outputDirectory}`). -|=== - - - -[[build-tool-plugins-maven-run-configuration-optional-params]] -=== Optional parameters -[cols="2,4"] -|=== -|Name |Description - -|`arguments` or `-Drun.arguments` -|Arguments that should be passed to the application (comma-separated). - -|`addResources` or `-Drun.addResources` -|Add Maven resources to the classpath directly, this allows live in-place editing or - resources. Since resources will be added directly, and via the target/classes folder - they will appear twice if `ClassLoader.getResources()` is called. In practice, however, - most applications call `ClassLoader.getResource()` which will always return the first - resource (defaults to `true`). - -|`mainClass` -|The name of the main class. If not specified the first compiled class found that - contains a 'main' method will be used. - -|`folders` -|Folders that should be added to the classpath (defaults to - `${project.build.outputDirectory}`). -|=== +Advanced configuration options and examples are available in the {mp-root}/[plugin info page]. diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index e6f5d977c2..0b0bf75bcf 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/spring-boot-docs/src/main/asciidoc/index.adoc @@ -25,6 +25,7 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson; :dc-spring-boot: {dc-root}/org/springframework/boot :dc-spring-boot-autoconfigure: {dc-root}/org/springframework/boot/autoconfigure :dc-spring-boot-actuator: {dc-root}/org/springframework/boot/actuate +:mp-root: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin :spring-reference: http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle :spring-security-reference: http://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle :spring-javadoc: http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework diff --git a/spring-boot-parent/pom.xml b/spring-boot-parent/pom.xml index 683e2dce80..8165fa3cad 100644 --- a/spring-boot-parent/pom.xml +++ b/spring-boot-parent/pom.xml @@ -31,6 +31,14 @@ scm:git:git://github.com/spring-projects/spring-boot.git scm:git:ssh://git@github.com/spring-projects/spring-boot.git + + Github + https://github.com/spring-projects/spring-boot/issues + + + Bamboo + https://build.spring.io/browse/BOOT-PUB + @@ -120,27 +145,52 @@ maven-jar-plugin + org.apache.maven.plugins maven-plugin-plugin spring-boot + true - default-descriptor + generate-descriptor descriptor - process-classes - help-descriptor + generated-helpmojo helpmojo - process-classes + + + + org.apache.maven.plugins + maven-plugin-plugin + + + org.apache.maven.plugins + maven-project-info-reports-plugin + 2.7 + + + + index + cim + issue-tracking + license + scm + + + + + + + diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/assemble/site.xml b/spring-boot-tools/spring-boot-maven-plugin/src/assemble/site.xml new file mode 100644 index 0000000000..cadc42520a --- /dev/null +++ b/spring-boot-tools/spring-boot-maven-plugin/src/assemble/site.xml @@ -0,0 +1,15 @@ + + site + maven-plugin + + zip + + + + ${project.build.directory}/site + / + + + \ No newline at end of file diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RepackageMojo.java b/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RepackageMojo.java index 36fa4cc18e..c7769f55f3 100644 --- a/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RepackageMojo.java +++ b/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RepackageMojo.java @@ -37,39 +37,46 @@ import org.springframework.boot.loader.tools.Libraries; import org.springframework.boot.loader.tools.Repackager; /** - * MOJO that can can be used to repackage existing JAR and WAR archives so that they can - * be executed from the command line using {@literal java -jar}. With - * layout=NONE can also be used simply to package a JAR with nested - * dependencies (and no main class, so not executable). + * Repackages existing JAR and WAR archives so that they can be executed from + * the command line using {@literal java -jar}. With layout=NONE + * can also be used simply to package a JAR with nested dependencies (and + * no main class, so not executable). * * @author Phillip Webb * @author Dave Syer + * @author Stephane Nicoll */ -@Mojo(name = "repackage", defaultPhase = LifecyclePhase.PACKAGE, requiresProject = true, threadSafe = true, requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME, requiresDependencyCollection = ResolutionScope.COMPILE_PLUS_RUNTIME) +@Mojo(name = "repackage", defaultPhase = LifecyclePhase.PACKAGE, requiresProject = true, + threadSafe = true, requiresDependencyResolution = ResolutionScope.COMPILE_PLUS_RUNTIME, + requiresDependencyCollection = ResolutionScope.COMPILE_PLUS_RUNTIME) public class RepackageMojo extends AbstractMojo { private static final long FIND_WARNING_TIMEOUT = TimeUnit.SECONDS.toMillis(10); /** * The Maven project. + * @since 1.0 */ @Parameter(defaultValue = "${project}", readonly = true, required = true) private MavenProject project; /** * Maven project helper utils. + * @since 1.0 */ @Component private MavenProjectHelper projectHelper; /** * Directory containing the generated archive. + * @since 1.0 */ @Parameter(defaultValue = "${project.build.directory}", required = true) private File outputDirectory; /** * Name of the generated archive. + * @since 1.0 */ @Parameter(defaultValue = "${project.build.finalName}", required = true) private String finalName; @@ -77,7 +84,10 @@ public class RepackageMojo extends AbstractMojo { /** * Classifier to add to the artifact generated. If given, the artifact will be * attached. If this is not given, it will merely be written to the output directory - * according to the finalName. + * according to the finalName. Attaching the artifact allows to deploy it alongside + * to the original one, see + * the maven documentation for more details. + * @since 1.0 */ @Parameter private String classifier; @@ -85,12 +95,16 @@ public class RepackageMojo extends AbstractMojo { /** * The name of the main class. If not specified the first compiled class found that * contains a 'main' method will be used. + * @since 1.0 */ @Parameter private String mainClass; /** - * The layout to use (JAR, WAR, ZIP, DIR, NONE) in case it cannot be inferred. + * The type of archive (which corresponds to how the dependencies are laid out + * inside it). Possible values are JAR, WAR, ZIP, DIR, NONE. Defaults to a + * guess based on the archive type. + * @since 1.0 */ @Parameter private LayoutType layout; diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RunMojo.java b/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RunMojo.java index e29af53da4..5133f7d395 100644 --- a/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RunMojo.java +++ b/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/RunMojo.java @@ -43,11 +43,13 @@ import org.springframework.boot.loader.tools.RunProcess; import edu.emory.mathcs.backport.java.util.Arrays; /** - * MOJO that can be used to run a executable archive application directly from Maven. + * Run an executable archive application. * * @author Phillip Webb + * @author Stephane Nicoll */ -@Mojo(name = "run", requiresProject = true, defaultPhase = LifecyclePhase.VALIDATE, requiresDependencyResolution = ResolutionScope.TEST) +@Mojo(name = "run", requiresProject = true, defaultPhase = LifecyclePhase.VALIDATE, + requiresDependencyResolution = ResolutionScope.TEST) @Execute(phase = LifecyclePhase.TEST_COMPILE) public class RunMojo extends AbstractMojo { @@ -55,25 +57,32 @@ public class RunMojo extends AbstractMojo { /** * The Maven project. + * @since 1.0 */ @Parameter(defaultValue = "${project}", readonly = true, required = true) private MavenProject project; /** * Add maven resources to the classpath directly, this allows live in-place editing or - * resources. + * resources. Since resources will be added directly, and via the target/classes folder + * they will appear twice if {@code ClassLoader.getResources()} is called. In practice, + * however, most applications call {@code ClassLoader.getResource()} which will always + * return the first resource. + * @since 1.0 */ @Parameter(property = "run.addResources", defaultValue = "true") private boolean addResources; /** * Path to agent jar. + * @since 1.0 */ @Parameter(property = "run.agent") private File[] agent; /** * Flag to say that the agent requires -noverify. + * @since 1.0 */ @Parameter(property = "run.noverify") private Boolean noverify; @@ -81,6 +90,7 @@ public class RunMojo extends AbstractMojo { /** * Arguments that should be passed to the application. On command line use commas to * separate multiple arguments. + * @since 1.0 */ @Parameter(property = "run.arguments") private String[] arguments; @@ -88,12 +98,15 @@ public class RunMojo extends AbstractMojo { /** * The name of the main class. If not specified the first compiled class found that * contains a 'main' method will be used. + * @since 1.0 */ @Parameter private String mainClass; /** - * Folders that should be added to the classpath. + * Additional folders besides the classes directory that should be added to + * the classpath. + * @since 1.0 */ @Parameter private String[] folders; @@ -101,6 +114,7 @@ public class RunMojo extends AbstractMojo { /** * Directory containing the classes and resource files that should be packaged into * the archive. + * @since 1.0 */ @Parameter(defaultValue = "${project.build.outputDirectory}", required = true) private File classesDirectory; diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/examples/repackage-classifier.apt b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/examples/repackage-classifier.apt new file mode 100644 index 0000000000..5f3ebcfb66 --- /dev/null +++ b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/examples/repackage-classifier.apt @@ -0,0 +1,49 @@ + ----- + Repackage classifier + ----- + Stephane Nicoll + ----- + 2014-05-02 + ----- + + By default, the <<>> goal will replace the original artifact with the + executable one. If you prefer to keep the original artifact and attach the executable + one with a different classifier, configure the plugin as follows: + +--- + + ... + + ... + + ... + + ${project.groupId} + ${project.artifactId} + ${project.version} + + + + repackage + + + exec + + + + ... + + ... + + ... + + ... + +--- + + This configuration will generate two artifacts: the original one and the executable counter + part produced by the repackage goal. Both will be installed/deployed accordingly. + + + + diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/index.apt b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/index.apt new file mode 100644 index 0000000000..c820748c17 --- /dev/null +++ b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/index.apt @@ -0,0 +1,44 @@ + ----- + Spring Boot + ----- + Stephane Nicoll + ----- + 2014-05-02 + ----- + +Spring Boot Maven Plugin + + The Spring Boot Maven Plugin provides Spring Boot support in Maven, allowing you to package executable + jar or war archives and run an application “in-place”. + +* Goals Overview + + The Spring Boot Plugin has the following goals. + + * {{{./run-mojo.html}spring-boot:run}} runs your Spring Boot application. + + * {{{./repackage-mojo.html}spring-boot:repackage}} repackages your jar/war to be executable. + +* Usage + + General instructions on how to use the Spring Boot Plugin can be found on the {{{./usage.html}usage page}}. Some + more specific use cases are described in the examples given below. + + In case you still have questions regarding the plugin's usage, please have a look at the existing + {{{http://stackoverflow.com/questions/tagged/spring-boot}stack overflow issue}}. If you still don't get an + answer, feel free to create a new thread with the <<<#spring-boot>>> tag. + + If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report + in our {{{./issue-tracking.html}issue tracker}}. + +* Examples + + To provide you with better understanding of some usages of Spring Boot, you can take a look into + the following examples: + + * {{{./examples/repackage-classifier.html}Custom repackage classifier}} + + [] + + + diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/usage.apt.vm b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/usage.apt.vm new file mode 100644 index 0000000000..7b3e5c0d48 --- /dev/null +++ b/spring-boot-tools/spring-boot-maven-plugin/src/site/apt/usage.apt.vm @@ -0,0 +1,123 @@ + + ----- + Usage + ----- + Stephane Nicoll + ----- + 2014-05-02 + ----- + +Usage + + The plugin offers a goal for repackaging an application as an executable JAR/WAR as well as a goal + for running the application. + +* Repackaging an application + + In order to repackage your application, you simply need to add a reference to the + plugin in your <<>>: + +--- + + ... + + ... + + ${project.groupId} + ${project.artifactId} + ${project.version} + + + + repackage + + + + + ... + + ... + +--- + + The example above repackages a jar or war that is built during the package phase of the Maven lifecycle. The + original (i.e. non exectuable) artifact is renamed to <<<.original>>> by default but it is also possible to + keep the original artifact using a custom classifier. + + The plugin rewrites your manifest, and in particular it manages the <> and <> + entries, so if the defaults don't work you have to configure those there (not in the jar plugin). The + <> in the manifest is actually controlled by the <> property of the boot plugin, e.g. + +--- + + ... + + ... + + ${project.groupId} + ${project.artifactId} + ${project.version} + + ${start-class} + ZIP + + + + + repackage + + + + + ... + + ... + +--- + + The layout property defaults to a guess based on the archive type (jar or war). For the + <<>> the layout is <<>> (even though the output might be a jar file). + + For more detailed examples of how to configure this goal see: + + * {{{./examples/repackage-classifier.html}Custom repackage classifier}} + + [] + +* Running the application + + The plugin includes a run goal which can be used to launch your application from the command + line: + +--- +mvn spring-boot:run +--- + + By default, any <> folder will be added to the application classpath + when you run the application. This allows hot refreshing of resources which can be very + useful when developing web applications. For example, you can work on HTML, CSS or JavaScipt + files and see your changes immediately without recompiling your application. It is also a + helpful way of allowing your front end developers to work without needing to download and + install a Java IDE. + + Of course, if your resources are using tokens that are filtered by Maven, you may want + to disable that feature as follows: + +--- + + ... + + ... + + ${project.groupId} + ${project.artifactId} + ${project.version} + + false + + + ... + + ... + +--- \ No newline at end of file diff --git a/spring-boot-tools/spring-boot-maven-plugin/src/site/site.xml b/spring-boot-tools/spring-boot-maven-plugin/src/site/site.xml new file mode 100644 index 0000000000..73c82ec306 --- /dev/null +++ b/spring-boot-tools/spring-boot-maven-plugin/src/site/site.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + org.apache.maven.skins + maven-fluido-skin + 1.3.1 + +