Add section about configuring the Groovy plugin to wire dependencies …

…correctly

subprojects/docs/src/docs/userguide/javaLibraryPlugin.xml

@@ -272,4 +272,17 @@
 
     </section>
 
+    <section id="sec:java_library_known_issues">
+    <title>Known issues</title>
+        <section id="sec:java_library_known_issues_compat">
+            <title>Compatibility with other plugins</title>
+            <para>At the moment the Java Library plugin is only wired to behave correctly with the <literal>java</literal> plugin. Other plugins, such as
+            the Groovy plugin, may not behave correctly. In particular, if the Groovy plugin is used in addition to the <literal>java-library</literal> plugin,
+            then consumers may not get the Groovy classes when they consume the library. To workaround this, you need to explicitly wire the Groovy compile
+            dependency, like this:</para>
+            <sample id="useGroovyPlugin" dir="java-library/with-groovy" title="Configuring the Groovy plugin to work with Java Library">
+                <sourcefile file="a/build.gradle" snippet="configure-groovy"/>
+            </sample>
+        </section>
+    </section>
 </chapter>

subprojects/docs/src/samples/java-library/with-groovy/a/build.gradle

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+apply plugin: 'java-library'
+apply plugin: 'groovy'
+
+dependencies {
+    compile localGroovy()
+}
+
+// START SNIPPET configure-groovy
+configurations {
+    apiElements {
+        outgoing.variants.getByName('classes').artifact(
+            file: compileGroovy.destinationDir,
+            type: JavaPlugin.CLASS_DIRECTORY,
+            builtBy: compileGroovy)
+    }
+}
+// END SNIPPET configure-groovy

subprojects/docs/src/samples/java-library/with-groovy/a/src/main/groovy/B.groovy

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+class B {}
+

subprojects/docs/src/samples/java-library/with-groovy/a/src/main/java/A.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+public class A {}
+

subprojects/docs/src/samples/java-library/with-groovy/b/build.gradle

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+apply plugin: 'java'
+
+dependencies {
+   implementation project(':a')
+}

subprojects/docs/src/samples/java-library/with-groovy/b/src/main/java/C.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+public class C {}

subprojects/docs/src/samples/java-library/with-groovy/settings.gradle

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+include 'a', 'b'