From bffcb1aad297ca60a122d42e2d67eed7523accae Mon Sep 17 00:00:00 2001
From: Stephane Nicoll <snicoll@pivotal.io>
Date: Tue, 21 Jun 2016 11:41:43 +0200
Subject: [PATCH] Document available layouts

Closes gh-5524
---
 .../src/main/asciidoc/build-tool-plugins.adoc | 41 ++++++++++++++++++-
 .../src/site/apt/usage.apt.vm                 | 18 +++++++-
 2 files changed, 56 insertions(+), 3 deletions(-)

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 aa5fb449a0b..aed0c522274 100644
--- a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc
+++ b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc
@@ -485,7 +485,8 @@ The following configuration options are available:
 
 |`layout`
 |The type of archive, corresponding to how the dependencies are laid out inside
- (defaults to a guess based on the archive type).
+ (defaults to a guess based on the archive type). See
+ <<build-tool-plugins-gradle-configuration-layouts,available layouts for more details>>.
 
 |`requiresUnpack`
 |A list of dependencies (in the form "`groupId:artifactId`" that must be unpacked from
@@ -495,6 +496,44 @@ The following configuration options are available:
 
 
 
+[[build-tool-plugins-gradle-configuration-layouts]]
+==== Available layouts
+
+The `layout` attribute configures the format of the archive and whether the bootstrap
+loader should be included or not. The following layouts are available:
+
+[cols="2,4,1"]
+|===
+|Name |Description |Executable
+
+|`JAR`
+|Regular executable
+ <<appendix-executable-jar-format.adoc#executable-jar-jar-file-structure,JAR layout>>.
+|Yes
+
+|`WAR`
+|Executable
+ <<appendix-executable-jar-format.adoc#executable-jar-war-file-structure,WAR layout>>.
+ `provided` dependencies are placed in `WEB-INF/lib-provided` to avoid any clash when
+ the `war` is deployed in a servlet container.
+|Yes
+
+|`ZIP` (alias to `DIR`)
+|Similar to `JAR` layout, using
+ <<appendix-executable-jar-format.adoc#executable-jar-property-launcher-features,`PropertiesLauncher`>>.
+| Yes
+
+|`MODULE`
+|Bundle dependencies (excluding those with `provided` scope) and project resources.
+|No
+
+|`NONE`
+|Bundle all dependencies and project resources.
+|No
+|===
+
+
+
 [[build-tool-plugins-understanding-the-gradle-plugin]]
 === Understanding how the Gradle plugin works
 When `spring-boot` is applied to your Gradle project a default task named `bootRepackage`
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
index b876ad9dc16..dbc9c88d589 100644
--- 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
@@ -90,8 +90,22 @@ Usage
 </build>
 ---
 
-  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).
+  The <<<layout>>> property defaults to a guess based on the archive type (<<<jar>>> or <<<war>>>). The
+  following layouts are available:
+
+    * <<<JAR>>>: regular executable JAR layout.
+
+    * <<<WAR>>>: executable WAR layout. <<<provided>>> dependencies are placed in <<<WEB-INF/lib-provided>>>
+      to avoid any clash when the <<<war>>> is deployed in a servlet container.
+
+    * <<<ZIP>>> (alias to <<<DIR>>>): similar to the <<<JAR>>> layout using <<<PropertiesLauncher>>>.
+
+    * <<<MODULE>>>: Bundle dependencies (excluding those with <<<provided>>> scope) and project resources.
+      Does not bundle a bootstrap loader.
+
+    * <<<NONE>>>: Bundle all dependencies and project resources. Does not bundle a bootstrap loader.
+
+    []
 
   For more detailed examples of how to configure this goal see: