Restructure the README files for the examples.
diff --git a/README.md b/README.md
index 6ff24c0..a4c2abe 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Atomos [](https://github.com/apache/felix-atomos/actions?query=workflow%3A%22Java%20CI%22) [](https://join.slack.com/share/IV58N2A1L/2uiZ00qrH7wuBi1Dpgdv263g/enQtOTkxMjk0MDc4MDU0LWU3M2ZiYTczZGY5ZTNhZjI5M2NhMzNjYTdmN2VlMzg0NTU3NzEyOGI0MWJmYzU1YjI1ZjNhMTMzMzg4Y2RmNDk) [](https://gitpod.io/#https://github.com/apache/felix-atomos)
+# Atomos [](https://github.com/apache/felix-atomos/actions?query=workflow%3A%22Java%20CI%22) [](https://join.slack.com/share/IV58N2A1L/2uiZ00qrH7wuBi1Dpgdv263g/enQtOTkxMjk0MDc4MDU0LWU3M2ZiYTczZGY5ZTNhZjI5M2NhMzNjYTdmN2VlMzg0NTU3NzEyOGI0MWJmYzU1YjI1ZjNhMTMzMzg4Y2RmNDk) [](https://gitpod.io/#https://github.com/apache/felix-atomos)
Atomos - A Java Module Runtime using OSGi Connect
@@ -15,6 +15,7 @@
1. Module Path: Using the Java Platform Module System (JPMS) Atomos will discover the modules on the module path and will make any modules found available for installation into the Framework as connected bundles. This also allows for Atomos and a set of OSGi bundles to be packaged into a jlink image resulting in a small fit-for-purpose JVM.
1. Class Path: When loaded from the class path Atomos will discover the JARs on the class path and will make any OSGi bundles found available for installation into the Framework.
1. Graal Substrate Native Image: When compiled into a Substrate native image Atomos will discover the bundles that were included into the image. This requires configuration to enable the necessary reflection for things like bundle activators and declarative service components.
+1. Atomos Bundle Index: Allows a single executable JAR to contain multiple bundles. The bundles included in the executable JAR have their resources indexed to allow for duplicate resource names to be included in each bundle. For example, the `META-INF/MANIFEST.MF` bundle manifest file.
# Build
@@ -27,72 +28,6 @@
`./mvnw clean install -Pjava8 -Pfelix`
-If you build with no profile specified then the default will build with Equinox and the resulting Atomos runtime will only work with Java 11.
+If you build with no profile specified then the default will build with Equinox and the resulting Atomos runtime will only work with Java 11+. The build also includes a number of example projects that showcase how Atomos can be used in different modes. The Graal Substrate native-image examples are not built by default. For information on how to build the native-image examples see the substrate [README](atomos.examples/SUBSTRATE.md)
-This should create a jlink image under `atomos/atomos.examples/atomos.examples.jlink/target/atomos`. Executing the following command against the jlink image should produce a gogo shell prompt:
-
-`./bin/atomos`
-
-You should see the following output:
-
-```
-Registered Echo service from activator.
-____________________________
-Welcome to Apache Felix Gogo
-
-g!
-```
-
-In order to successfully build a jlink image all bundles included in the image must contain a `module-info.class`, they cannot be automatic modules. The `atomos/atomos.examples/atomos.examples.jlink` example uses the `1.0.0.Beta2` version of the `moditect-maven-plugin` to add `module-info.class` as necessary to the bundles used in the image.
-
-You can also load additional modules into atomos at:
-
- - System start
-by using the `atomos.modules` option when launching `atomos`. For example:
-
-```
-atomos/bin/atomos atomos.modules=/path/to/more/modules
-```
-
- - Runtime
-by using the gogo command `atomos:install`. For example:
-
-```
-atomos:install MyLayerName OSGI /path/to/more/modules
-```
-
-When doing that the additional modules will be loaded into a child layer where the Atomos OSGi Framework will control the class loaders. This will produce a class loader per module bundle installed. This has advantages because it allows the module class loader for the bundle to implement the `org.osgi.framework.BundleReference` interface.
-
-# Substrate
-
-There are two examples projects that build native images using Graal Substrate:
-1. `atomos/atomos.examples/atomos.examples.substrate.equinox` - Using Eclipse Equinox Framework
-1. `atomos/atomos.examples/atomos.examples.substrate.felix` - Using Apache Felix Framework
-
-These two example projects are not built as part of the main Atomos build because they require an installation of GraalVM CE 19.3.1 (Java 8 or Java 11 can be used) and the native-image tools for Substrate. The Java 11 version of Graal Substrate does not currently support full introspection at image runtime of the Java Platform Module System. Atomos Module support expects to have full introspection of the Java Platform Module System when running on Java versions greater than Java 8. Therefore the example will run in basic class path mode for both Java 8 and Java 11 when running with a native substrate image.
-
-To build the native image you must install the native image support for Graal (see https://www.graalvm.org/docs/reference-manual/native-image/). You need to run the `gu` command that comes with Graal VM:
-
-`gu install native-image`
-
-If you are using GraalVM CE 19.3.1 Java 11 then you can build all of Atomos, including the substrate examples for Equinox and Felix, with the following single maven build using the `substrate` profile:
-
-`./mvnw clean install -Pjava8 -Psubstrate -Pequinox`
-
-If using GraalVM CE 19.3.1 Java 8 then you must first use Java 11 for the main Atomos build using the Java 8 profile:
-
-`./mvnw clean install -Pjava8 -Pequinox`
-
-Note that `install` target must be used so that Atomos is installed into your local m2 repository. This still requires Java 11 to be used to build but the result allows the `atomos.framework` JAR to be used on Java 8. Next you must switch to a Java installation of Graal with the Substrate native-image tools installed and then run the following maven builds:
-
-`./mvnw clean install -Pjava8 -f atomos.examples/atomos.examples.substrate.equinox/pom.xml`
-
-`./mvnw clean install -Pjava8 -f atomos.examples/atomos.examples.substrate.felix/pom.xml`
-
-This will create a `target/atomos` executable in each substrate example project. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
-
-For the Felix and Equinox example a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
-
-Alternatively a substrate image can be created that does not rely on the directory `target/atomos_lib/` to discover the bundles. Instead the bundle entry resources can be placed in an `atomos/` folder which is placed on the classpath during native image compilation. The resources from the `atomos/` folder can then be included in the native image. The `atomos/` folder has a file `bundles.index` that contains information for Atomos to discover the bundles and their entries that are included in the native image. In order to use this approach effectively Atomos needs a maven plugin to assist in the generation of the Atomos `bundles.index`.
-
-If substrate adds full introspection to the Java Platform Module System in the future it could allow Atomos to discover the modules within the image and load them as bundles. If a proper module reader could be obtained and contain the necessary resources from the original bundle JARs then it would eliminate the need for the `atomos_lib/` or `atomos/` resource folder.
+For more information on each example see Atomos examples [README](atomos.examples/README.md)
diff --git a/atomos.examples/README.md b/atomos.examples/README.md
new file mode 100644
index 0000000..3550900
--- /dev/null
+++ b/atomos.examples/README.md
@@ -0,0 +1,9 @@
+# Atomos Examples
+
+The following examples are available:
+1. [Atomos Index example](atomos.examples.index/README.md) - Assembles an executable JAR which uses an Atomos index for bundle entry content.
+1. [Atomos jlink example](atomos.examples.jlink/README.md) - Assembles a jlink image that loads the framework and a set of bundles as modules included in a fit for purpose JVM image
+1. [Atomos Spring Loader example](atomos.examples.springloader/README.md) - Assembles an executable JAR that uses the Spring Jar loader to load bundle content from embedded JAR files.
+1. Atomos native-image example ([Equinox](atomos.examples.substrate.equinox/README.md) and [Felix](atomos.examples.substrate.felix/README.md)) - Assembles a native image using Graal Substrate to load the framework and a set of bundles
+1. Atomos native-image example ([atomos-maven-plugin](atomos.examples.substrate.maven.equinox/README.md)) - Assembles a native image using Graal Substrate with the atomos-maven-plugin
+1. [Atomos Android example](atomos.examples.android/README.md) - Uses the result of the [Atomos index example](atomos.examples.index/README.md) to build an Android application
\ No newline at end of file
diff --git a/atomos.examples/SUBSTRATE.md b/atomos.examples/SUBSTRATE.md
new file mode 100644
index 0000000..88c8621
--- /dev/null
+++ b/atomos.examples/SUBSTRATE.md
@@ -0,0 +1,25 @@
+# Building Substrate Examples
+
+The example projects that build Graal Substrate native-images are not built as part of the main Atomos build because they require an installation of GraalVM CE 19.3.1 (Java 8 or Java 11 can be used) and the native-image tools for Substrate. The Java 11 version of Graal Substrate does not currently support full introspection at image runtime of the Java Platform Module System. Atomos Module support expects to have full introspection of the Java Platform Module System when running on Java versions greater than Java 8. Therefore the example will run in basic class path mode for both Java 8 and Java 11 when running with a native substrate image.
+
+To build the native image examples you must install the native image support for Graal (see https://www.graalvm.org/docs/reference-manual/native-image/). You need to run the `gu` command that comes with Graal VM:
+
+`gu install native-image`
+
+If you are using GraalVM CE 19.3.1 Java 11 then you can build all of Atomos, including the substrate examples, with the following single maven build using the `substrate` profile:
+
+`./mvnw clean install -Pjava8 -Psubstrate -Pequinox`
+
+If using GraalVM CE 19.3.1 Java 8 then you must first use Java 11 for the main Atomos build using the Java 8 profile:
+
+`./mvnw clean install -Pjava8 -Pequinox`
+
+Note that `install` target must be used so that Atomos is installed into your local m2 repository. This still requires Java 11 to be used to build but the result allows the `atomos.framework` JAR to be used on Java 8. Next you must switch to a Java installation of Graal with the Substrate native-image tools installed and then run the maven builds for the substrate example projects:
+
+This will create a `target/atomos` executable in each substrate example project. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
+
+For the Felix and Equinox example a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
+
+Alternatively a substrate image can be created that does not rely on the directory `target/atomos_lib/` to discover the bundles. Instead the bundle entry resources can be placed in an `atomos/` folder which is placed on the classpath during native image compilation. The resources from the `atomos/` folder can then be included in the native image. The `atomos/` folder has a file `bundles.index` that contains information for Atomos to discover the bundles and their entries that are included in the native image. In order to use this approach effectively Atomos needs a maven plugin to assist in the generation of the Atomos `bundles.index`.
+
+If substrate adds full introspection to the Java Platform Module System in the future it could allow Atomos to discover the modules within the image and load them as bundles. If a proper module reader could be obtained and contain the necessary resources from the original bundle JARs then it would eliminate the need for the `atomos_lib/` or `atomos/` resource folder.
diff --git a/atomos.examples/atomos.examples.android/README.md b/atomos.examples/atomos.examples.android/README.md
new file mode 100644
index 0000000..56b4dcd
--- /dev/null
+++ b/atomos.examples/atomos.examples.android/README.md
@@ -0,0 +1,10 @@
+# Atomos Android Example
+
+This is a very simple Android example project that can be loaded by Android Studio and/or built with `gradlew` from command line:
+
+`gradlew build`
+
+Before building the example a JAR file containing an Atomos index and set of bundles must be copied to the `app/libs` folder. For this example it is assumed you copy the executable JAR produced by the [Atomos Index example](../atomos.examples.index/README.md) into the `app/libs` folder.
+
+The build will produce an APK andoid application at `app/build/outputs/apk/debug/app-debug.apk`. This application can then be installed on an emulator or an android device. The resulting application is very simple. It has a single `Launch Atomos` button. When clicked it will launch Atomos which will automatically install and start all the bundles included in the Atomos index JAR that got copied to the `app/libs` folder. The display should indicate when Atomos has launched and give a status of all the bundles that got started with the application. If using the [Atomos Index example](../atomos.examples.index/README.md) then you can bring up the browser on Android and access the web console with the URL [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles) with the id/password of admin/admin.
+
diff --git a/atomos.examples/atomos.examples.index/README.md b/atomos.examples/atomos.examples.index/README.md
new file mode 100644
index 0000000..60473dc
--- /dev/null
+++ b/atomos.examples/atomos.examples.index/README.md
@@ -0,0 +1,15 @@
+# Atomos Index Example
+
+This example uses the `atomos-maven-plugin` to create an Atomos index. An Atomos index contains all the bundle entry resources of the bundles that are required by the example. For this example the necessary bundles are included to have a functional Felix Gogo console and a Felix WebConsole. The Atomos index can then be included into the final JAR along with all the required packages from all the bundles included in the JAR.
+
+This example uses `maven-assembly-plugin` to package all the dependent bundles into a single executable JAR which also includes the Atomos index. The Atomos launcher class `org.apache.felix.atomos.launch.AtomosLauncher` is used as the `main-class` for the executable JAR. If you introspect the JAR produced by this example you will notice it includes an `atomos/` folder which includes all the bundle entry resources for all the dependent bundles. This allows for duplicate bundle entry paths to be included in the JAR which Atomos can discover for each bundle included in the single JAR.
+
+The following command should produce a gogo shell prompt:
+
+`java -jar target/org.apache.felix.atomos.examples.index-<version>.jar`
+
+Where `<version>` is the current version of this example. When executed all the bundles are loaded using the single application class loader provided by the JVM. Additional bundles can be installed, but these additional bundles will be loaded by the typical bundle class loader provided by the OSGi Framework.
+
+Once the example is launched you can access the web console with the URL [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles) with the id/password of admin/admin.
+
+On its own the Atomos Index example is not that interesting. But it does open the possibility to include it in other examples that need to compose the bundles into a single artifact. For example, to produce an Android application or a native-image which includes all the bundles of your application.
\ No newline at end of file
diff --git a/atomos.examples/atomos.examples.jlink/README.md b/atomos.examples/atomos.examples.jlink/README.md
new file mode 100644
index 0000000..f41bc55
--- /dev/null
+++ b/atomos.examples/atomos.examples.jlink/README.md
@@ -0,0 +1,37 @@
+# Atomos jlink Example
+
+This example uses `jlink` in order to build a Java image that includes a set of bundle and the modules they require from the base JVM installation. This allows for a set of bundle modules to be used to build a fit for purpose Java image that only includes the required modules from the JVM.
+
+In order to successfully build a jlink image all bundles included in the image must contain a `module-info.class`, they cannot be automatic modules. This example uses the `1.0.0.Beta2` version of the `moditect-maven-plugin` to add `module-info.class` as necessary to the bundles used in the image.
+
+When this example is built a jlink image will be created under `target/atomos`. Executing the following command against the jlink image should produce a gogo shell prompt:
+
+`./bin/atomos`
+
+You should see the following output:
+
+```
+Registered Echo service from activator.
+____________________________
+Welcome to Apache Felix Gogo
+
+g!
+```
+
+You can also load additional modules into atomos at:
+
+ - System start
+by using the `atomos.modules` option when launching `atomos`. For example:
+
+```
+atomos/bin/atomos atomos.modules=/path/to/more/modules
+```
+
+ - Runtime
+by using the gogo command `atomos:install`. For example:
+
+```
+atomos:install MyLayerName OSGI /path/to/more/modules
+```
+
+When doing that the additional modules will be loaded into a child layer where the Atomos OSGi Framework will control the class loaders. This will produce a class loader per module bundle installed. This has advantages because it allows the module class loader for the bundle to implement the `org.osgi.framework.BundleReference` interface.
\ No newline at end of file
diff --git a/atomos.examples/atomos.examples.springloader/README.md b/atomos.examples/atomos.examples.springloader/README.md
new file mode 100644
index 0000000..920992f
--- /dev/null
+++ b/atomos.examples/atomos.examples.springloader/README.md
@@ -0,0 +1,15 @@
+# Atomos Spring Loader Example
+
+This example uses the `spring-boot-maven-plugin` to create an executable JAR that includes each required bundle as embedded JAR files inside the single executable JAR. This executable JAR includes the `org.springframework.boot.loader` which is then used to load all the bundles included in the JAR. For this example the necessary bundles are included to have a functional Felix Gogo console and a Felix WebConsole. The Atomos index can then be included into the final JAR along with all the required packages from all the bundles included in the JAR.
+
+This is not a Spring Boot example itself. It only Spring Boot loader which understands how to discover and load all the included JAR files with a single class loader. This class loader is able to load content from the embedded JAR files without requiring them to be extracted to disk first.
+
+The Atomos launcher class `org.apache.felix.atomos.launch.AtomosLauncher` is used as the `Start-Class` for the executable JAR. If you introspect the JAR produced by this example you will notice it includes a `BOOT-INF/lib/` folder which includes all the embedded JARs for all the dependent bundles. Atomos is able to discover all the included JARs and load the bundle entry resources from them.
+
+The following command should produce a gogo shell prompt:
+
+`java -jar target/org.apache.felix.atomos.examples.springloader-<version>.jar`
+
+Where `<version>` is the current version of this example. When executed all the bundles are loaded using the single class loader provided by the Spring loader. Additional bundles can be installed, but these additional bundles will be loaded by the typical bundle class loader provided by the OSGi Framework.
+
+Once the example is launched you can access the web console with the URL [http://localhost:8080/system/console/bundles](http://localhost:8080/system/console/bundles) with the id/password of admin/admin.
diff --git a/atomos.examples/atomos.examples.substrate.equinox/README.md b/atomos.examples/atomos.examples.substrate.equinox/README.md
new file mode 100644
index 0000000..8cf6c81
--- /dev/null
+++ b/atomos.examples/atomos.examples.substrate.equinox/README.md
@@ -0,0 +1,8 @@
+# Atomos Substrate Equinox Example
+
+This example builds a native image that includes the Equinox Framework implementation with a set of bundles using Graal Substrate. See the substrate [README](../SUBSTRATE.md) for instructions on building the Substrate examples.
+
+Buiding this example will create a `target/atomos` executable. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
+
+For this example a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
+
diff --git a/atomos.examples/atomos.examples.substrate.felix/README.md b/atomos.examples/atomos.examples.substrate.felix/README.md
new file mode 100644
index 0000000..15be9d8
--- /dev/null
+++ b/atomos.examples/atomos.examples.substrate.felix/README.md
@@ -0,0 +1,8 @@
+# Atomos Substrate Felix Example
+
+This example builds a native image that includes the Felix Framework implementation with a set of bundles using Graal Substrate. See the substrate [README](../SUBSTRATE.md) for instructions on building the Substrate examples.
+
+Buiding this example will create a `target/atomos` executable. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
+
+For this example a directory `target/atomos_lib/` is created. This contains all the original bundle JARs that got compiled into the native image `atomos`. In order to launch the native `atomos` you must be in the directory containing both `atomos` and the `atomos_lib/` folder. This is a simple way for Atomos to discover the available bundles and load additional bundle entries at runtime.
+
diff --git a/atomos.examples/atomos.examples.substrate.maven.equinox/README.md b/atomos.examples/atomos.examples.substrate.maven.equinox/README.md
new file mode 100644
index 0000000..ae677c7
--- /dev/null
+++ b/atomos.examples/atomos.examples.substrate.maven.equinox/README.md
@@ -0,0 +1,6 @@
+# Atomos Substrate Example (atomos-maven-plugin)
+
+This example builds a native image that includes the Equinox Framework implementation with a set of bundles using Graal Substrate. See the substrate [README](../SUBSTRATE.md) for instructions on building the Substrate examples. This example uses the `atomos-maven-plugin` plugin to generate an Atomos index which is then included in the native-image. This allows for a native-image that does not require the presence of the original bundle JARs at runtime in an `atomos_lib/` folder.
+
+Buiding this example will create a `target/atomos` executable. If you launch `atomos` it will give you a gogo `g!` prompt to run gogo commands. Also included in this example is a version of the Felix web console. The web console can be access with http://localhost:8080/system/console/bundles and the id/password is admin/admin.
+
