You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by tj...@apache.org on 2021/02/10 20:14:16 UTC
[felix-atomos] 01/01: initial gh-pages
This is an automated email from the ASF dual-hosted git repository.
tjwatson pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/felix-atomos.git
commit 0d4d631e5683de1405980c13d33eec8ccadcb316
Author: Thomas Watson <tj...@us.ibm.com>
AuthorDate: Wed Feb 10 14:13:05 2021 -0600
initial gh-pages
---
.gitattributes | 60 +++++++++++++
.gitignore | 42 ++++++++++
CODE_OF_CONDUCT.md | 22 +++++
CONTRIBUTING.md | 24 ++++++
LICENSE | 201 ++++++++++++++++++++++++++++++++++++++++++++
README.md | 242 +++++++++++++++++++++++++++++++++++++++++++++++++++++
_config.yml | 9 ++
7 files changed, 600 insertions(+)
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..0a6421b
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,60 @@
+# Text files with LF eol
+*.awk crlf=input
+*.bnd crlf=input
+*.c crlf=input ident
+*.conf crlf=input
+*.cpp crlf=input ident
+*.css crlf=input
+*.groovy crlf=input
+*.h crlf=input ident
+*.html crlf=input ident
+*.java crlf=input ident
+*.js crlf=input
+*.MF crlf=input
+*.php crlf=input
+*.pl crlf=input
+*.prefs crlf=input
+*.properties crlf=input
+*.py crlf=input
+*.schema crlf=input
+*.sh crlf=input
+*.tcl crlf=input
+*.txt crlf=input
+*.xml crlf=input
+*.xsd crlf=input ident
+*.xsl crlf=input
+*.xslt crlf=input
+.classpath crlf=input
+.project crlf=input
+packageinfo crlf=input
+Makefile crlf=input
+
+# No EOL translation
+*.bat -crlf
+
+# Binary. No EOL translation, no diff
+*.ico binary
+*.jpeg binary
+*.jpg binary
+*.png binary
+*.crt binary
+*.pdf binary
+*.dll binary
+*.jar binary
+*.jnilib binary
+*.so binary
+*.zip binary
+*.doc binary
+*.ppt binary
+*.xls binary
+*.odg binary
+*.odp binary
+*.ods binary
+*.odt binary
+*.otg binary
+*.otp binary
+*.ots binary
+*.ott binary
+*.key binary
+*.numbers binary
+*.pages binary
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e902dd6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,42 @@
+*#
+*.iml
+*.ipr
+*.iws
+*.jar
+*.sw?
+*~
+.#*
+.*.md.html
+.DS_Store
+.classpath
+.factorypath
+.gradle
+.idea
+.metadata
+.project
+.recommenders
+.settings
+.springBeans
+.theia
+/build
+/code
+_site/
+activemq-data
+bin
+build
+build.log
+dependency-reduced-pom.xml
+dump.rdb
+interpolated*.xml
+lib/
+manifest.yml
+overridedb.*
+settings.xml
+target
+transaction-logs
+.flattened-pom.xml
+secrets.yml
+.gradletasknamecache
+.sts4-cache
+configuration/
+felix-cache/
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..8f67f34
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,22 @@
+<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+Apache Software Foundation Code of Conduct
+====
+
+Being an Apache project, Apache Felix adheres to the Apache Software Foundation's [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1c489ba
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,24 @@
+<!--/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/-->
+Contributing
+====
+
+Thanks for choosing to contribute!
+
+You will find all the necessary details about how you can do this at https://felix.apache.org/documentation/community/contributing.html.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ 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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3fad5b7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,242 @@
+# Atomos [](https://github.com/apache/felix-atomos/actions?query=workflow%3A%22Java%20CI%22) [](https://join.slack.com/share/IV58N2A1L/2uiZ00qrH7wuBi1Dpgdv263g/enQtOTkxMjk0MDc4MDU0LWU3M2ZiYTczZGY5ZTNhZjI5M2NhMzNjYTdmN2VlMzg0NTU3NzEyOGI0MWJmYzU1YjI1ZjNhMTMzMzg4Y2RmNDk) [, the [Connect](https://docs.osgi.org/specification/osgi.core/8.0.0/framework.connect.html) Specification enables OSGi frameworks to be extended to support environments not previously possible in a standard way. Atomos uses the Connect specification to extend the use of the OSGi framework into many different environments.
+
+# Examples
+
+A number of example projects are contained in the Atomos git repository under the folder `atomos.examples`.
+
+1. Run from the [class path](atomos.examples/atomos.examples.springloader/README.md)
+1. Run from the module path with [jlink](atomos.examples/atomos.examples.jlink/README.md)
+1. Run with a [native image](atomos.examples/atomos.examples.substrate.maven/README.md)
+
+See Atomos examples [README](atomos.examples/README.md) for more information.
+
+# Module Path and Class Path Usage
+
+Two simple ways to use Atomos is with the flat class path or the module path. Typically an OSGi framework requires complete control over loading classes and resources out of bundles. This allows the framework to provide the isolation defined by the OSGi specification through the use of its own class loader implementation. For example, only allowing a bundle to load classes and resources which are either local to the bundle or imported with the `Import-Package` or `Require-Bundle` header. [...]
+
+The `Atomos` class provides a convenient way to launch an OSGi framework implementation with support for the module path or the class path. For example, to load all bundles included in a directory called `bundles` the following `java` command can be run using the class path:
+
+`java -cp "bundles/*" org.apache.felix.atomos.Atomos`
+
+The following `java` command can be run using the module path:
+
+`java -p bundles -m org.apache.felix.atomos`
+
+In both cases Atomos will discover all the JARs contained in the `bundles/` directory. For each bundle JAR included in `bundles/` the launcher will install and start each bundle in an OSGi framework instance. The bundles are loaded using the class loader provided by the JVM itself. In this case the framework is not in control of the class loading for the bundles contained on the class path or the module path.
+
+Atomos requires a compliant OSGi R8 framework implementation. In addition, when running on the module path, Atomos requires a module named `osgi.core` to represent the framework implementation. Atomos provides two `osgi.core` modules to represent Equinox (`org.apache.felix.atomos:osgi.core:8.0.0:jar:AtomosEquinox`) and Felix (`org.apache.felix.atomos:osgi.core:8.0.0:jar:AtomosFelix`). One of these modules along with the corresponding framework implementation JAR (`org.eclipse.osgi` or `o [...]
+
+For example, consider a `bundles/` folder containing the necessary bundles to run the Gogo console:
+
+```
+jline-3.13.3.jar
+org.apache.felix.atomos-1.0.0.jar
+org.apache.felix.gogo.command-1.1.2.jar
+org.apache.felix.gogo.jline-1.1.8.jar
+org.apache.felix.gogo.runtime-1.1.4.jar
+org.eclipse.osgi-3.16.100.jar
+osgi.core-8.0.0-AtomosEquinox.jar
+```
+The JARs `osgi.core-8.0.0-AtomosEquinox.jar` and `org.eclipse.osgi-3.16.100.jar` provide the framework implementation for Equinox. When running on Java 11 or higher, regardless of using the class path or module path, Atomos will discover the available modules from the boot layer and represent them as bundles in the framework. For example, running `java -p bundles -m org.apache.felix.atomos` on the above `bundles/` folder will get you this result for the Gogo `lb -s` command:
+
+```
+g! lb -s
+START LEVEL 1
+ ID|State |Level|Symbolic name
+ 0|Active | 0|org.eclipse.osgi (3.16.100.v20201030-1916)|3.16.100.v20201030-1916
+ 1|Active | 1|java.base (11.0.8)|11.0.8
+ 2|Active | 1|java.compiler (11.0.8)|11.0.8
+ 3|Active | 1|java.datatransfer (11.0.8)|11.0.8
+ 4|Active | 1|java.desktop (11.0.8)|11.0.8
+ ...
+ 71|Active | 1|org.apache.felix.atomos (1.0.0)|1.0.0
+ 72|Active | 1|org.apache.felix.gogo.command (1.1.2)|1.1.2
+ 73|Active | 1|org.apache.felix.gogo.jline (1.1.8)|1.1.8
+ 74|Active | 1|org.apache.felix.gogo.runtime (1.1.4)|1.1.4
+ 75|Active | 1|org.jline (3.13.3)|3.13.3
+ 76|Active | 1|osgi.core (0.0.0)|0.0.0
+```
+
+Running with the module path will load all modules discovered within the `bundles/` folder and the JVM modules in the boot layer as bundles in the framework. This is true even for modules that do not contain an OSGi bundle manifest. Running with `java -cp "bundles/*" org.apache.felix.atomos.Atomos` will produce nearly identical results with the exception that the `osgi.core` module will not be installed. This is because the `osgi.core` module from Atomos does not contain a bundle manifes [...]
+
+Atomos currently can support Java 8 as well which does not have support for the module path. When using Java 8, the module path mode is not available.
+
+# Connecting Content
+
+The OSGi Connect specification allows an implementation of a [ModuleConnector](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/connect/ModuleConnector.html) to be used to create a new framework instance with the [ConnectFrameworkFactory.newFramework](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/connect/ConnectFrameworkFactory.html#newFramework-java.util.Map-org.osgi.framework.connect.ModuleConnector-) method.
+
+Atomos provides a `ModuleConnector` that adds support to enable bundles to be connected to four different sources of content:
+
+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 bundles. This also allows for Atomos and a set of 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 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. One usecase for the bundle index is in the creation Android applications.
+
+# Atomos API
+
+The `Atomos` class provides convenient methods to create and launch an OSGi framework implementation with Atomos support. The `main` method can be used to discover, install and start all the bundles found into a framework instance. In some scenarios more control is necessary to configure the framework and its set of installed bundles. The `Atomos` class allows more control over the configuration, bundle installation and launching of the framework instance.
+
+## Creating A Framework
+
+Atomos provides a [ModuleConnector](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/connect/ModuleConnector.html)
+implemenation that can be used to create a [Framework](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/Framework.html) instance. The following is an example of how to use a [ConnectFrameworkFactory](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/connect/ConnectFrameworkFactory.html) to create a framework instance that uses Atomos:
+
+```java
+ ServiceLoader<ConnectFrameworkFactory> loader = ServiceLoader.load(ConnectFrameworkFactory.class);
+ ConnectFrameworkFactory factory = loader.findFirst().get();
+ Framework framework = factory.newFramework(
+ Map.of(
+ Constants.FRAMEWORK_SYSTEMPACKAGES, ""),
+ Atomos.newAtomos().getModuleConnector());
+```
+
+The framework must be configured with `org.osgi.framework.system.packages=""` when running on Java 9+ to configure the `system.bundle` to not export any of the packages provided by the JVM boot layer. Alternatively, a framework can be constructed using the `Atomos.newFramework` method like the following:
+
+```java
+ Framework framework = Atomos.newAtomos().newFramework(Map.of());
+```
+
+In this case the `org.osgi.framework.system.packages` configuration will be set appropriately for the running Java version. In most all cases the `Atomos.newFramework` method can be used.
+
+When the framework is initialized Atomos will install and start all bundles that have been discovered by default. To disable starting the bundles on framework initialization the `atomos.content.start` framework configuration property can be used:
+
+```java
+ Framework framework = Atomos.newAtomos().newFramework(Map.of("atomos.content.start", "false"));
+```
+
+To disable installing the bundles on framework initialization the `atomos.content.install` framework configuration property can be used:
+
+```java
+ Framework framework = Atomos.newAtomos().newFramework(Map.of("atomos.content.install", "false"));
+```
+## Installing Bundles
+
+Special handling is needed to install content discovered by Atomos as bundles in a framework. Atomos has layers which are used to contain content it discovers. For example, the modules on the module path or the JARs on the class path are considered content. When an `Atomos` instance is created it discovers the available content in the environment it is running (e.g. the module path or class path). This initial content is placed into an `AtomosLayer` that is called the boot layer. Each [...]
+
+### Connected Bundles
+
+As mentioned, `AtomosContent` is contained with an `AtomosLayer`. The following code can be used to install and start all the content discovered by Atomos from the boot layer:
+
+```java
+ Atomos atomos = Atomos.newAtomos();
+ // Set atomos.content.install to false to prevent automatic bundle installation
+ Framework framework = atomos.newFramework(Map.of("atomos.content.install", "false"));
+ // framework must be initialized before any bundles can be installed
+ framework.init();
+ List<Bundle> bundles = new ArrayList<>();
+ for (AtomosContent content: atomos.getBootLayer().getAtomosContents()) {
+ // The resulting bundle will use a bundle location of
+ // "atomos:" + atomosContent.getAtomosLocation();
+ bundles.add(content.install());
+ }
+ for (Bundle b : bundles) {
+ b.start();
+ }
+ // The installed bundles will not actually activate until the framework is started
+ framework.start();
+```
+
+This allows for control over what gets exposed as a bundle from the discovered Atomos content. An alternative to using the `AtomosContent.install` method is to use a `BundleContext` to install the bundles. Before this can be done the `AtomosContent` must be connected with the bundle location that will be used to install the bundle. The following code can be used to do that instead:
+
+```java
+ Atomos atomos = Atomos.newAtomos();
+ // Set atomos.content.install to false to prevent automatic bundle installation
+ Framework framework = atomos.newFramework(Map.of("atomos.content.install", "false"));
+ // framework must be initialized before any bundles can be installed
+ framework.init();
+ BundleContext systemContext = framework.getBundleContext();
+ List<Bundle> bundles = new ArrayList<>();
+ Random random = new Random();
+ for (AtomosContent content: atomos.getBootLayer().getAtomosContents()) {
+ String location = String.valueOf(new Random().nextLong()) + "-location";
+ // Connect the content to a specific location.
+ content.connect(location);
+ // Use the same location to install the bundle.
+ // Note that an input stream cannot be provided for installing connected bundles,
+ // only the location string can be used.
+ bundles.add(systemContext.installBundle(location));
+ }
+ for (Bundle b : bundles) {
+ b.start();
+ }
+ // The installed bundles will not actually activate until the framework is started
+ framework.start();
+```
+
+This allows for complete control over the bundle location string used to install the bundles.
+
+### Standard Bundles
+
+Bundles may be installed which are not contained in an `AtomosLayer`. This is done by using one of the [BundleContext.install](https://docs.osgi.org/javadoc/osgi.core/8.0.0/org/osgi/framework/BundleContext.html#installBundle-java.lang.String-) methods using a location string which has not been connected with an `AtomosContent`. In this case the bundle class loading and resource access is under the complete control of the framework. Standard bundles may depend on any other bundles install [...]
+
+## Adding Layers
+
+When running on Java 9+ additional JPMS layers can be added and removed dynamically using the `AtomosLayer` API. An `AtomosLayer` is added as a child layer to one or more existing `AtomosLayer` instances. The following can be used to install two different sibling layers as a child of the boot layer:
+
+```java
+ Atomos atomos = Atomos.newAtomos();
+ AtomosLayer bootLayer = atomos.getBootLayer();
+
+ // Add a layer that loads all modules contained in "modules-child1" directory
+ Path modulesChild1 = new File("modules-child1").toPath();
+ AtomosLayer child1 = bootLayer.addLayer("child1", LoaderType.SINGLE, modulesChild1);
+
+ // Add a layer that loads all modules contained in "modules-child1" directory
+ Path modulesChild2 = new File("modules-child2").toPath();
+ AtomosLayer child2 = bootLayer.addLayer("child2", LoaderType.SINGLE, modulesChild2);
+
+ // Create a new framework to use the layers configured with Atomos
+ Framework framework = atomos.newFramework(Map.of());
+ // Starting the framework will automatically install and start the content from all
+ // Atomos layers known. This will include the content in child1 and child2.
+ // The "atomos.content.install" configuration can be used to disable that.
+ framework.start();
+
+ // stopping the framework will persist the added layers in the framework storage area
+ framework.stop();
+```
+
+A layer can be added before or after creating and starting the framework instance with Atomos. If added before initializing the framework then all of the known layers configured with Atomos will have their bundles installed and started according to the `atomos.content.install` framework configuration setting.
+
+When adding a layer there is a choice of the loader type. This refers to the class loader behavior. Atomos has three different loader types available.
+
+1. `SINGLE` - All modules in the layer will be loaded with a single class loader
+1. `MANY` - All modules in the layer will get their own individual class loader
+1. `OSGI` - All modules in the layer will get their own individual class loader that behaves the same as `MANY` except the class loader will implement the `BundleReference` interface.
+
+Once a layer is added the content can be installed just like the example above with the boot layer. When a framework is initialized, the storage area for the framework will be used to save the layer information to persistent storage. When the framework is created again, using the same framework storage location, the Atomos layers will be loaded back into Atomos.
+
+A layer can be dynamically uninstalled using the AtomosLayer.uninstall() method. This will result in the layer and all of its children layers being removed from Atomos. Any bundles that are installed from the removed layers will also be uninstalled from the framework.
+
+It is possible to get the `Module` that backs an `AtomosContent` by calling the method `AtomosContent.adapt(Module.class)`. Similarly it is possible to get the `ModuleLayer` that backs an `AtomosLayer` by calling the method `AtomosLayer.adapt(ModuleLayer.class)`.
+
+The examples above demostrate the commonly used hierarchy with single parent layers. More advanced scenarios that require multi-parent layers must use the `Atomos.addLayer(List<AtomosLayer>, String, LoaderType, Path...)` method instead of the `AtomosLayer.addLayer` method.
+
+## OSGi Capability Resolution and Service Visibility
+
+When running Atomos on the module path the class loading rules are defined by the Java Platform Module System (JPMS). This implies that there is a resolution step done within JPMS when configuring the `ModuleLayer` that backs the `AtomosLayer`. When an OSGi bundle is connected to `AtomosContent`, the framework will attempt to resolve the bundle within the framework as well. The resolution done by JPMS for the modules contained in an `AtomosLayer` will influence how the bundle connected t [...]
+
+### OSGi Bundle Resolution
+
+The OSGi bundles that are connected to `AtomosContent` located in a JPMS layer will resolve against capabilities for the namespaces `osgi.wiring.package` and `osgi.wiring.bundle` according the behavior of the `java.lang.Module.canRead(Module)` method. All other namespaces are resolved against capabilities provided by modules within the same layer or modules contained in the parent layer hierarchy. This implies that the requirements for an AtomosContent bundle cannot be resolved against [...]
+
+### OSGi Service Visibility
+
+The service availability in the OSGi service registry is not influenced by the layer hierarchy. Standard bundles are able to use OSGi services registered by connected bundles and vise versa as long as the consumer and producer bundles are using the same source for the service package. There is no additional isolation of OSGi services between the different layers in Atomos.
+
+# Build
+
+Java 11 or higher must be used to build Atomos. Atomos build uses the 1.0.0.RC1 version of the moditect plugin (https://github.com/moditect/moditect.git). This plugin provides some utilities for adding module-infos to existing dependency JARs and building `jlink` images. You can build the Atomos with the following:
+
+`./mvnw clean install -Pjava8 -Pequinox`
+
+Or if you want to use the Felix framework
+
+`./mvnw clean install -Pjava8 -Pfelix`
+
+To build you must specify one of the framework implementation profiles (`equinox` or `felix`). If you build without the `java8` profile then the resulting Atomos runtime will only work with Java 11+. The build also includes a number of example projects that demonstrate 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)
+
diff --git a/_config.yml b/_config.yml
new file mode 100644
index 0000000..382b9ea
--- /dev/null
+++ b/_config.yml
@@ -0,0 +1,9 @@
+title: Atomos
+author: Apache Felix
+email: dev@felix.apache.org
+description: > # this means to ignore newlines until "baseurl:"
+ A Java Module Runtime that uses OSGi Connect to represent Java modules
+ and other content as bundles in an OSGi framework instance.
+show_excerpts: true # set to false to remove excerpts on the homepage
+theme: minima
+