more doc work
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index fd96853..d3b07f6 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -328,6 +328,92 @@
Each modules `<module>/target/site` directory will then contain the generated
Module documentation.
+## More Build Tooling Miscellenea
+
+There is a lot of surface area to the maven build tooling. The following
+information may help to better understand it.
+
+* `pom.xml/maven-surefile-plugin` - unit test execution
+* `pom.xml/maven-failsafe-plugin` - integration test execution
+* `pom.xml/jacoco-maven-plugin` - jacoco code coverage reports
+* `pom.xml/animal-sniffer-maven-plugin` - retrolambda results checker
+* `pom.xml/org.codehaus.sonar-plugins` - SonarQube code quality reports
+* `pom.xml/maven-javadoc-plugin` - javadoc generation and the config
+ for all of the "grouping" control.
+* `pom.xml/apache-rat-plugin` - builds automatically run Apache RAT
+ (Release Audit Tool) for checking for appropriate content.
+ The build fails if the checking fails.
+ See configuration info for controlling excluded artifacts.
+* `pom.xml/maven-assembly-plugin` - used in a couple places for configuring
+ and generating "assemblies" => source release bundle, distribution bundles
+* `pom.xml/maven-site-plugin` - things related to website generation that includes
+ a number of interesting things, including html reports from various things
+ above plus aggregated javadoc. How / if this untimately relates to the
+ public website is TDB.
+* `platforms/java7/pom.xml/retrolambda-maven-plugin`
+ and `platforms/android/android/pom.xml/retrolambda-maven-plugin` - where
+ retrolambda is enabled
+* As mentioned earlier the current scheme for generating Java7 and Android
+ Edgent jars, is achieved by replicating the java8 project structure in
+ platforms/{java7,android}. <b>Manual synchronization of the corresponding
+ info in the alternate platform poms and other configuration files
+ is required.</b>
+* LICENSE and NOTICE: it's a requirement that released bundles
+ (source release bundle, released jars) contain accurate LICENSE, NOTICE
+ and DISCLAIMER files. Some of the Edgent projects contain code that
+ that was contributed by IBM, some of the generated jars/war bundle
+ external components. The build tooling is configured to automatically
+ include standard ALv2.0 LICENSE and NOTICE files in the jars.
+ The non-default cases are handled in a variety of ways:
+ * `pom.xml/maven-remote-resources-plugin` config plays a role in all of this
+ * `src/main/appended-resources` - contains copies of license text for
+ artifacts that are bundled in Edgent bundles. For the most part
+ this means the Edgent Console jar/war. These are incorporated
+ into a jar by including a declaration like the following in the
+ project's pom:
+``` xml
+ <resource>
+ <directory>${project.basedir}/../../src/main/appended-resources/licenses</directory>
+ <targetPath>${project.build.directory}/${project.artifactId}-${project.version}/META-INF/licenses</targetPath>
+ </resource>
+```
+ * `src/main/ibm-remote-resources` - contains the NOTICE fragment for
+ projects containing IBM contributed code. Applicable project's
+ define the following in their pom to ensure a correct
+ NOTICE is included in the project's jar:
+``` xml
+ <properties>
+ <remote-resources-maven-plugin.remote-resources.dir>../../src/main/ibm-remote-resources</remote-resources-maven-plugin.remote-resources.dir>
+ </properties>
+```
+ * `edgent-console-servlets:war` contains bundled code (downloaded and
+ incorporated by the build tooling). It includes the bundled code's
+ license text as described above. Its own LICENSE and NOTICE is
+ copied from the respective files in its `src/main/remote-resources/META-INF`.
+ <b>There are copies of those in under the java7 platform as well.</b>
+ * `edgent-console-server:jar` bundles the console-servlets war and as such
+ requires the same LICENSE/NOTICE/licenses treatment as the servlets war.
+ <b>There are copies of its LICENSE/NOTICE in its `src/main/remote-resources/META-INF`.
+ There are copies of those in under the java7 platform as well.</b>
+* source-release bundle
+ * `src/assembly/source-release.xml` - configuration information
+ controlling source-release bundle and distribution bundle names,
+ included/excluded files, etc.
+* distribution bundles:
+ Each platform has a "distribution" project.
+ We don't release these bundles hence they aren't obligated to
+ strictly conform to the ASF LICENSE/NOTICE file requirements.
+ That said, much of the same information is provided via an
+ automatically generated DEPENDENCIES file in the bundle.
+ <b>There are copies of the following information in the java7 and android platforms.</b>
+ Related, `samples/get-edgent-jars-project` uses the same scheme and has
+ its own copies of the files.
+ * the name of the bundle is inherited from the source-release bundle's
+ configuration file noted above.
+ * src/assembly/distribution.xml - additional configuration info
+ * src/main/resources/README - source of the file in the bundle
+
+
## Testing the Kafka Connector
The kafka connector tests aren't run by default as the connector must
diff --git a/pom.xml b/pom.xml
index c020e66..52a71de 100644
--- a/pom.xml
+++ b/pom.xml
@@ -101,20 +101,7 @@
<module>console</module>
<module>providers</module>
<module>runtime</module>
- <!-- <module>samples</module>
-
- TODO figure out what to do with samples.
- On one hand we want them to be self-standing and not
- part of the "core" edgent source bundle.
- We want the samples to have their own released source bundle
- and not release any sample binary jars or samples binary bundle.
- The samples don't depend on this ~edgent-core pom.xml.
- On the other hand, we need to understand how the overall
- release flow will work.
- At this moment, with this pom and the current sample poms,
- you "cd samples; mvn clean install -Papache-release"
- to create the samples source bundles.
- -->
+ <!-- <module>samples</module> intentionally omitted -->
<module>spi</module>
<module>test</module>
<module>utils</module>
diff --git a/samples/APPLICATION_DEVELOPMENT.md b/samples/APPLICATION_DEVELOPMENT.md
index 3166931..92f0099 100644
--- a/samples/APPLICATION_DEVELOPMENT.md
+++ b/samples/APPLICATION_DEVELOPMENT.md
@@ -38,6 +38,8 @@
See `JAVA_SUPPORT.md` for more information on artifact coordinates, etc.
+## Writing Your Application
+
The Edgent API is most easily used by using Java8 lambda expressions.
If you only want to deploy your Edgent application to a java8 environment
then your application may use any java8 features it chooses. You compile
@@ -63,22 +65,20 @@
required Edgent jars from the maven repository if they aren't
already present in your local maven repository.
-The supplied Edgent samples poms include support for building for
-a java8, java7 or android execution environment. The poms are
-configured for the generation of a standard jar as well as an
-uber jar for a sample application.
-
-You can clone the `samples/template` project as a starting point
-for your Edgent application. See `samples/template/README.md`.
+### Edgent Application Template
+
+You can clone the `template` project as a starting point for your
+Edgent application. See [samples/template/README.md](template/README.md).
TODO: we would like to provide a maven Edgent Application archetype
that users can use to create an application project template.
+### Using Non-maven-integrated Tooling
+
If you can't or don't want to use maven-repository-enabled tooling
you will need to get a local copy of the Edgent jars and their
dependencies and add them to your compile classpath. This case
-is covered in the following sections.
-
+is covered in subsequent sections.
## Packaging and Execution
@@ -106,11 +106,26 @@
the application's dependent Edgent classes and their
transitive dependencies.
-The Edgent samples template project's pom and
+The template project's pom and
the Edgent samples poms contain configuration information
that generates an uber jar in addition to the standard
application jar. Eclipse can also export an uber jar.
+### Separately manage the application and Edgent jars
+
+Copy the application's jars to the device.
+Get a copy of the Edgent jars and their dependencies
+onto the device. It's possible for multiple Edgent
+applications to share the Edgent jars.
+
+The Apache Edgent project does not release a
+binary bundle containing all of the Edgent jars
+and their dependencies. The binary artifacts
+are only released to maven central.
+
+See [samples/get-edgent-jars-project](get-edgent-jars-project/README.md)
+for a tool to get a copy of the Edgent jars.
+
### Create an application package bundle
The bundle is a standalone entity containing
@@ -124,37 +139,15 @@
A run script forms the appropriate `CLASSPATH`
to the package's jars and starts the application.
-The Edgent supplied `package-app.sh` tool supports this mode.
-Eclipse can also export a similar collection
-of information.
-
-### Separately manage the application and Edgent jars
-
-Copy the application's jars to the device.
-Get a copy of the Edgent jars and their dependencies
-onto the device to be shared by any Edgent applications
-that want to use them.
-
-The Apache Edgent project does not release a
-binary bundle containing all of the Edgent jars
-and their dependencies. The binary artifacts
-are only released to maven central.
-
-See `samples/get-edgent-jars-project` for a tool
-to get a copy of the Edgent jars.
-
-## package-app.sh
-
-The `package-app.sh` script creates an application bundle.
-The application bundle can be copied to an edge-device,
-unpacked and then used to run the application.
+The supplied `package-app.sh` script creates an
+application bundle.
The application bundle contains the application's jar,
the application's dependent Edgent jars (as specified in
the application's pom) and the Edgent jars' dependencies,
and a run-app.sh script.
-The application's pom specified Edgent runtime jars and
+The application's dependent Edgent runtime jars and
their dependencies are retrieved from a local or remote
maven repository.
@@ -185,5 +178,5 @@
For more usage information:
``` sh
-package-app.sh -h
+./package-app.sh -h
```
diff --git a/samples/README.md b/samples/README.md
index b78b6e2..97adf54 100644
--- a/samples/README.md
+++ b/samples/README.md
@@ -105,7 +105,7 @@
## Running the samples
-See the README.md in each sample category directory for information
+See the `README.md` in each sample category directory for information
on running the samples.
diff --git a/samples/pom.xml b/samples/pom.xml
index 60c3d06..7e4efdc 100644
--- a/samples/pom.xml
+++ b/samples/pom.xml
@@ -56,7 +56,9 @@
<module>apps</module>
<module>connectors</module>
<module>console</module>
+ <!-- <module>get-edgent-jars-project</module> intentionally omitted -->
<module>scenarios</module>
+ <!-- <module>template</module> intentionally omitted -->
<module>topology</module>
<module>utils</module>
</modules>
