You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@celix.apache.org by GitBox <gi...@apache.org> on 2022/04/12 14:16:56 UTC
[GitHub] [celix] jermus67 commented on a diff in pull request #412: Feature/update documentation
jermus67 commented on code in PR #412:
URL: https://github.com/apache/celix/pull/412#discussion_r848353102
##########
documents/README.md:
##########
@@ -0,0 +1,90 @@
+---
+title: Introduction
+---
+
+<!--
+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 Celix Introduction
+
+## What is Apache Celix
+Apache Celix is an implementation of a dynamic service framework inspired by the
+[OSGi specification](https://www.osgi.org/developer/specifications) and adapted to C and C++ (C++17).
+It is a framework to develop dynamic modular software applications using component and in-process service-oriented programming.
+
+Apache Celix core is written in C and has a C++17 header-only API on top of the C API.
+
+Building applications with Apache Celix can be done by creating `bundles` which provide and use `services`;
+These `services` can be directly used or in a declarative way using `components`.
+To run a selection of bundles, an Apache Celix `container` executable can be created. An Apache Celix `containter` will
+start an Apache Celix framework and install and start the provided bundles.
+
+## Bundles
+An Apache Celix Bundle is a zip file which contains a collection of shared libraries,
+configuration files and optional an activation entry.
+Bundles can be dynamically installed and started in an Apache Celix framework.
+
+## Services
+An Apache Celix Service is a pointer registered to the Apache Celix framework under a set of properties (metadata).
+Services can be dynamically registered into and looked up from the Apache Celix framework.
+
+By convention a C service in Apache Celix is a pointer to struct of function pointers and a C++ service is a pointer
+(which can be provided as a `std::shared_ptr`) to an object implementing a (pure) abstract class.
+
+## Components
+Apache Celix also offers a way to create components which interact with dynamic services in declarative way.
+
+This removes some complexity of dynamic services by declaring service dependency and configure the dependency
Review Comment:
... and configuring the dependency ...
##########
documents/README.md:
##########
@@ -0,0 +1,90 @@
+---
+title: Introduction
+---
+
+<!--
+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 Celix Introduction
+
+## What is Apache Celix
+Apache Celix is an implementation of a dynamic service framework inspired by the
+[OSGi specification](https://www.osgi.org/developer/specifications) and adapted to C and C++ (C++17).
+It is a framework to develop dynamic modular software applications using component and in-process service-oriented programming.
+
+Apache Celix core is written in C and has a C++17 header-only API on top of the C API.
+
+Building applications with Apache Celix can be done by creating `bundles` which provide and use `services`;
+These `services` can be directly used or in a declarative way using `components`.
Review Comment:
... can be used directly or ...
##########
documents/components.md:
##########
@@ -53,9 +55,9 @@ The Dependency Manager consist out of four main parts: `DM (Dependency Manager)
### DM Activator
The `DM Activator` implements a "normal" Celix bundle activator and depends on four functions which needs to be implemented by the user of the Dependency Manager:
- - `dm_create` : Should be used to allocated and initialize a dm activator structure. If needed this structure can be used to store object during the lifecycle of the bundle.
- - `dm_init` : Should be used to interact with the `Dependency Manager`. Here a user can components, service dependencies and provided services.
- - `dm_destroy` : Should be used to deinitialize and deallocate objects created in the `dm_create` function.
+- `dm_create` : Should be used to allocated and initialize a dm activator structure. If needed this structure can be used to store object during the lifecycle of the bundle.
Review Comment:
... store objects ... instead of ... store object ...
##########
documents/diagrams/services_tracker_services_add_async_seq.puml:
##########
@@ -0,0 +1,41 @@
+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.
+
+@startuml
+actor ProviderBundle
+actor TrackingBundle
+control celix_event_thread
+
+ProviderBundle -> celix_bundle_context_t ++: celix_bundleContext_registerService
Review Comment:
celix_serviceTracker_... instead of celix_bundleContext_registerService?
##########
documents/diagrams/services_tracker_services_add_seq.puml:
##########
@@ -0,0 +1,44 @@
+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.
+
+@startuml
+actor ProviderBundle
+actor TrackerBundle
+control celix_event_thread
+
+ProviderBundle -> celix_bundle_context_t ++: celix_bundleContext_registerService
Review Comment:
celix_serviceTracker_... instead of celix_bundleContext_registerService
##########
documents/services.md:
##########
@@ -0,0 +1,627 @@
+---
+title: Apache Celix Services
+---
+
+<!--
+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 Celix Services
+An Apache Celix Service is a pointer registered to the Celix framework under a set of properties (metadata).
+Services can be dynamically registered into and looked up from the Apache Celix framework.
+
+By convention a C service in Apache Celix is a pointer to struct of function pointers and a C++ service is a pointer
+(which can be provided as a `std::shared_ptr`) to an object implementing a (pure) abstract class.
+
+A service is always register under a service name and this service name is also used to lookup services.
Review Comment:
registered instead of register
##########
documents/diagrams/services_tracker_services_rem_async_seq.puml:
##########
@@ -0,0 +1,38 @@
+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.
+
+@startuml
+actor ProviderBundle
+actor TrackerBundle
+control celix_event_thread
+
+ProviderBundle -> celix_bundle_context_t ++: celix_bundleContext_unregisterService
Review Comment:
celix_serviceTracker_... instead of celix_bundleContext_unregisterService?
##########
documents/components.md:
##########
@@ -19,20 +19,22 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix Dependency Manager
+# Apache Celix Components
+
+TODO refactor this documentation file
## Introduction
-The Dependency Manager contains a static library which can be used to manage (dynamic) services on a higher abstraction level in a declarative style.
+The Dependency Manager contains a static library which can be used to manage (dynamic) services on a higher abstraction level in a declarative style.
The Apache Celix Dependency Manager is inspired by the [Apache Felix Dependency Manager](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html).
## Components
Components are the main building blocks for OSGi applications. They can publish services, and/or they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.
Review Comment:
Apache Celix applications instead of OSGi applications? The framework is stated to be OSGi inspired, not an implementation of iirc.
##########
documents/building/README.md:
##########
@@ -19,119 +19,94 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix - Building and Installing
+# Building and Installing Apache Celix
Apache Celix aims to be support a broad range of UNIX platforms.
-Currently the [continuous integration build server](https://travis-ci.org/apache/celix) builds and tests Apache Celix for:
+Currently, the [continuous integration build server] builds and tests Apache Celix for:
-* Ubuntu Bionic Beaver (18.04)
+* Ubuntu Bionic Beaver (20.04)
* GCC
* CLang
* OSX
- * GCC
- * CLang
+ * CLang
+
+
+### Download the Apache Celix sources
+To get started you first have to download the Apache Celix sources. This can be done by cloning the Apache Celix git repository:
+
+```bash
+#clone the repro
+git clone --single-branch --branch master https://github.com/apache/celix.git
+```
+
+## Building and installing
+Apache Celix uses [CMake](https://cmake.org) as build system. CMake can generate (among others) makefiles.
-# Preparing
+### Building and installing with preinstalled libraries
The following packages (libraries + headers) should be installed on your system:
* Development Environment
* build-essentials (gcc/g++ or clang/clang++)
- * git
- * java (for packaging bundles)
+ * java or zip (for packaging bundles)
* make (3.14 or higher)
* Apache Celix Dependencies
- * zlib
* libzip
Review Comment:
double listing of libzip (see line 56) can be removed.
##########
documents/bundles.md:
##########
@@ -0,0 +1,289 @@
+---
+title: Apache Celix Bundles
+---
+
+<!--
+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 Celix Bundles
+An Apache Celix Bundle contains a collection of shared libraries, configuration files and optional
+an activation entry combined in a zip file. Bundles can be dynamically installed and started in an Apache Celix framework.
+
+## The anatomy of a Celix Bundle
+Technically an Apache Celix Bundle is a zip file with the following content:
+
+- META-INF/MANIFEST.MF: The required bundle manifest, containing information about the bundle (name, activator library etc)
+- Bundle shared libraries (so/dylib files): Optionally a bundle has 1 or more shared libraries.
+ The bundle manifest configures which libraries will be loaded (private libs) and which - if any - library is used
+ when activating the bundle.
+- Bundle resource files: A bundle can also contain additional resource files.
+ This could be configuration files, html files, etc.
+ It is also possible to have bundles which no shared library, but only resource files.
+ Note that bundles can access other bundles resources files.
+
+If a `jar` command is available the Celix CMake commands will use that (instead of the `zip` command) to create bundle
+zip files so that the MANIFEST.MF is always the first entry in the zip file.
+
+
+```bash
+#unpacking celix_shell_wui.zip bundle file from a cmake build `cmake-build-debug`.
+#The celix_shell_wui.zip file is the Celix Shell Web UI bundle. Which provides a web ui interface to the Celix
+#interactive shell; It contains a manifest file, shared libraries, and additional web resources
+#which can be picked up by the `Celix::http_admin` bundle.
+% unzip cmake-build-debug/bundles/shell/shell_wui/celix_shell_wui.zip -d unpacked_bundle_dir
+% find unpacked_bundle_dir
+unpacked_bundle_dir
+unpacked_bundle_dir/resources
+unpacked_bundle_dir/resources/index.html
+unpacked_bundle_dir/resources/ansi_up.js
+unpacked_bundle_dir/resources/script.js
+unpacked_bundle_dir/META-INF
+unpacked_bundle_dir/META-INF/MANIFEST.MF
+unpacked_bundle_dir/libcivetweb_shared.so #or dylib for OSX
+unpacked_bundle_dir/libshell_wui.1.so #or dylib for OSX
+```
+
+## Bundle lifecycle
+An Apache Celix Bundle has its own lifecycle with the following states:
+
+- Installed - The bundle has been installed into the Celix framework, but it is not yet resolved. For Celix this
+ currently means that not all bundle libraries can or have been loaded.
+- Resolved - The bundle is installed and its requirements have been met. For Celix this currently means that the
+ bundle libraries have been loaded.
+- Starting - Starting is a temporary state while the bundle activator create and start callbacks are being executed.
+- Active - The bundle is active.
+- Stopping - Stopping is a temporary state while the bundle activator stop and destroy callbacks are being executed.
Review Comment:
... the bundle activator's stop and destroy callbacks ...
##########
documents/components.md:
##########
@@ -53,9 +55,9 @@ The Dependency Manager consist out of four main parts: `DM (Dependency Manager)
### DM Activator
The `DM Activator` implements a "normal" Celix bundle activator and depends on four functions which needs to be implemented by the user of the Dependency Manager:
- - `dm_create` : Should be used to allocated and initialize a dm activator structure. If needed this structure can be used to store object during the lifecycle of the bundle.
- - `dm_init` : Should be used to interact with the `Dependency Manager`. Here a user can components, service dependencies and provided services.
- - `dm_destroy` : Should be used to deinitialize and deallocate objects created in the `dm_create` function.
+- `dm_create` : Should be used to allocated and initialize a dm activator structure. If needed this structure can be used to store object during the lifecycle of the bundle.
+- `dm_init` : Should be used to interact with the `Dependency Manager`. Here a user can components, service dependencies and provided services.
Review Comment:
verb missing: ... Here a user can <?> components, service dependencies, and provide services. (maybe "register"?)
##########
documents/diagrams/services_tracker_services_rem_seq.puml:
##########
@@ -0,0 +1,42 @@
+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.
+
+@startuml
+actor ProviderBundle
+actor TrackerBundle
+control celix_event_thread
+
+ProviderBundle -> celix_bundle_context_t ++: celix_bundleContext_unregisterService
Review Comment:
celix_serviceTracker_... instead of celix_bundleContext_unregisterService
##########
documents/building/README.md:
##########
@@ -19,119 +19,94 @@ See the License for the specific language governing permissions and
limitations under the License.
-->
-# Apache Celix - Building and Installing
+# Building and Installing Apache Celix
Apache Celix aims to be support a broad range of UNIX platforms.
-Currently the [continuous integration build server](https://travis-ci.org/apache/celix) builds and tests Apache Celix for:
+Currently, the [continuous integration build server] builds and tests Apache Celix for:
-* Ubuntu Bionic Beaver (18.04)
+* Ubuntu Bionic Beaver (20.04)
* GCC
* CLang
* OSX
- * GCC
- * CLang
+ * CLang
+
+
+### Download the Apache Celix sources
+To get started you first have to download the Apache Celix sources. This can be done by cloning the Apache Celix git repository:
+
+```bash
+#clone the repro
+git clone --single-branch --branch master https://github.com/apache/celix.git
+```
+
+## Building and installing
+Apache Celix uses [CMake](https://cmake.org) as build system. CMake can generate (among others) makefiles.
-# Preparing
+### Building and installing with preinstalled libraries
The following packages (libraries + headers) should be installed on your system:
* Development Environment
* build-essentials (gcc/g++ or clang/clang++)
- * git
Review Comment:
Git is removed here, but used in the command on line 70
##########
documents/bundles.md:
##########
@@ -0,0 +1,289 @@
+---
+title: Apache Celix Bundles
+---
+
+<!--
+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 Celix Bundles
+An Apache Celix Bundle contains a collection of shared libraries, configuration files and optional
+an activation entry combined in a zip file. Bundles can be dynamically installed and started in an Apache Celix framework.
+
+## The anatomy of a Celix Bundle
+Technically an Apache Celix Bundle is a zip file with the following content:
+
+- META-INF/MANIFEST.MF: The required bundle manifest, containing information about the bundle (name, activator library etc)
+- Bundle shared libraries (so/dylib files): Optionally a bundle has 1 or more shared libraries.
+ The bundle manifest configures which libraries will be loaded (private libs) and which - if any - library is used
+ when activating the bundle.
+- Bundle resource files: A bundle can also contain additional resource files.
+ This could be configuration files, html files, etc.
+ It is also possible to have bundles which no shared library, but only resource files.
+ Note that bundles can access other bundles resources files.
+
+If a `jar` command is available the Celix CMake commands will use that (instead of the `zip` command) to create bundle
+zip files so that the MANIFEST.MF is always the first entry in the zip file.
+
+
+```bash
+#unpacking celix_shell_wui.zip bundle file from a cmake build `cmake-build-debug`.
+#The celix_shell_wui.zip file is the Celix Shell Web UI bundle. Which provides a web ui interface to the Celix
+#interactive shell; It contains a manifest file, shared libraries, and additional web resources
+#which can be picked up by the `Celix::http_admin` bundle.
+% unzip cmake-build-debug/bundles/shell/shell_wui/celix_shell_wui.zip -d unpacked_bundle_dir
+% find unpacked_bundle_dir
+unpacked_bundle_dir
+unpacked_bundle_dir/resources
+unpacked_bundle_dir/resources/index.html
+unpacked_bundle_dir/resources/ansi_up.js
+unpacked_bundle_dir/resources/script.js
+unpacked_bundle_dir/META-INF
+unpacked_bundle_dir/META-INF/MANIFEST.MF
+unpacked_bundle_dir/libcivetweb_shared.so #or dylib for OSX
+unpacked_bundle_dir/libshell_wui.1.so #or dylib for OSX
+```
+
+## Bundle lifecycle
+An Apache Celix Bundle has its own lifecycle with the following states:
+
+- Installed - The bundle has been installed into the Celix framework, but it is not yet resolved. For Celix this
+ currently means that not all bundle libraries can or have been loaded.
+- Resolved - The bundle is installed and its requirements have been met. For Celix this currently means that the
+ bundle libraries have been loaded.
+- Starting - Starting is a temporary state while the bundle activator create and start callbacks are being executed.
+- Active - The bundle is active.
+- Stopping - Stopping is a temporary state while the bundle activator stop and destroy callbacks are being executed.
+- Uninstalled - The bundle has been removed from the Celix framework.
+
+
+
+## Bundle activation
+Bundles can be installed and started dynamically. When a bundle is started it will be activated by looking up the bundle
+activator entry points (using `dlsym`). The entry points signatures are:
+- `celix_status_t celix_bundleActivator_create(celix_bundle_context_t *ctx, void **userData)`:
+ Called to create the bundle activator.
+- `celix_status_t celix_bundleActivator_start(void *userData, celix_bundle_context_t *ctx)`:
+ Called to start the bundle.
+- `celix_status_t celix_bundleActivator_stop(void *userData, celix_bundle_context_t *ctx)`:
+ Called to stop the bundle.
+- `celix_status_t celix_bundleActivator_destroy(void *userData, celix_bundle_context_t* ctx)`:
+ Called to destroy (free mem) the bundle activator.
+
+The most convenient way to create a bundle activator in C is to use the macro `CELIX_GEN_BUNDLE_ACTIVATOR` defined in
+`celix_bundle_activator.h`. This macro requires two functions (start,stop), these function can be `static` and
+use a typed bundle activator struct instead of `void*`.
+
+For C++, the macro `CELIX_GEN_CXX_BUNDLE_ACTIVATOR` defined in `celix/BundleActivator.h` must be used to create a
+bundle activator. For C++ a RAII approach is used for bundle activation.
+This means that a C++ bundle is started by creating a bundle activator object and stopped by
+letting the bundle activator object go out of scope.
+
+## Bundle and Bundle Context
+
+A bundle can interact with the Apache Celix framework using a bundle execution context or bundle context in short.
+The bundle context provides functions/methods to:
+ - Register and un-register services.
+ - Install, start, stop or uninstall bundles.
+ - Track for service being added or removed.
Review Comment:
... for services being added ...
##########
documents/bundles.md:
##########
@@ -0,0 +1,289 @@
+---
+title: Apache Celix Bundles
+---
+
+<!--
+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 Celix Bundles
+An Apache Celix Bundle contains a collection of shared libraries, configuration files and optional
+an activation entry combined in a zip file. Bundles can be dynamically installed and started in an Apache Celix framework.
+
+## The anatomy of a Celix Bundle
+Technically an Apache Celix Bundle is a zip file with the following content:
+
+- META-INF/MANIFEST.MF: The required bundle manifest, containing information about the bundle (name, activator library etc)
+- Bundle shared libraries (so/dylib files): Optionally a bundle has 1 or more shared libraries.
+ The bundle manifest configures which libraries will be loaded (private libs) and which - if any - library is used
+ when activating the bundle.
+- Bundle resource files: A bundle can also contain additional resource files.
+ This could be configuration files, html files, etc.
+ It is also possible to have bundles which no shared library, but only resource files.
+ Note that bundles can access other bundles resources files.
+
+If a `jar` command is available the Celix CMake commands will use that (instead of the `zip` command) to create bundle
+zip files so that the MANIFEST.MF is always the first entry in the zip file.
+
+
+```bash
+#unpacking celix_shell_wui.zip bundle file from a cmake build `cmake-build-debug`.
+#The celix_shell_wui.zip file is the Celix Shell Web UI bundle. Which provides a web ui interface to the Celix
+#interactive shell; It contains a manifest file, shared libraries, and additional web resources
+#which can be picked up by the `Celix::http_admin` bundle.
+% unzip cmake-build-debug/bundles/shell/shell_wui/celix_shell_wui.zip -d unpacked_bundle_dir
+% find unpacked_bundle_dir
+unpacked_bundle_dir
+unpacked_bundle_dir/resources
+unpacked_bundle_dir/resources/index.html
+unpacked_bundle_dir/resources/ansi_up.js
+unpacked_bundle_dir/resources/script.js
+unpacked_bundle_dir/META-INF
+unpacked_bundle_dir/META-INF/MANIFEST.MF
+unpacked_bundle_dir/libcivetweb_shared.so #or dylib for OSX
+unpacked_bundle_dir/libshell_wui.1.so #or dylib for OSX
+```
+
+## Bundle lifecycle
+An Apache Celix Bundle has its own lifecycle with the following states:
+
+- Installed - The bundle has been installed into the Celix framework, but it is not yet resolved. For Celix this
+ currently means that not all bundle libraries can or have been loaded.
+- Resolved - The bundle is installed and its requirements have been met. For Celix this currently means that the
+ bundle libraries have been loaded.
+- Starting - Starting is a temporary state while the bundle activator create and start callbacks are being executed.
+- Active - The bundle is active.
+- Stopping - Stopping is a temporary state while the bundle activator stop and destroy callbacks are being executed.
+- Uninstalled - The bundle has been removed from the Celix framework.
+
+
+
+## Bundle activation
+Bundles can be installed and started dynamically. When a bundle is started it will be activated by looking up the bundle
+activator entry points (using `dlsym`). The entry points signatures are:
+- `celix_status_t celix_bundleActivator_create(celix_bundle_context_t *ctx, void **userData)`:
+ Called to create the bundle activator.
+- `celix_status_t celix_bundleActivator_start(void *userData, celix_bundle_context_t *ctx)`:
+ Called to start the bundle.
+- `celix_status_t celix_bundleActivator_stop(void *userData, celix_bundle_context_t *ctx)`:
+ Called to stop the bundle.
+- `celix_status_t celix_bundleActivator_destroy(void *userData, celix_bundle_context_t* ctx)`:
+ Called to destroy (free mem) the bundle activator.
+
+The most convenient way to create a bundle activator in C is to use the macro `CELIX_GEN_BUNDLE_ACTIVATOR` defined in
+`celix_bundle_activator.h`. This macro requires two functions (start,stop), these function can be `static` and
+use a typed bundle activator struct instead of `void*`.
+
+For C++, the macro `CELIX_GEN_CXX_BUNDLE_ACTIVATOR` defined in `celix/BundleActivator.h` must be used to create a
+bundle activator. For C++ a RAII approach is used for bundle activation.
+This means that a C++ bundle is started by creating a bundle activator object and stopped by
+letting the bundle activator object go out of scope.
+
+## Bundle and Bundle Context
+
+A bundle can interact with the Apache Celix framework using a bundle execution context or bundle context in short.
+The bundle context provides functions/methods to:
+ - Register and un-register services.
+ - Install, start, stop or uninstall bundles.
+ - Track for service being added or removed.
+ - Track for bundles being installed, started, stopped or uninstalled.
+ - Track for service tracker being started or stopped
Review Comment:
... for service tracer**s** being started ...
##########
documents/bundles.md:
##########
@@ -0,0 +1,289 @@
+---
+title: Apache Celix Bundles
+---
+
+<!--
+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 Celix Bundles
+An Apache Celix Bundle contains a collection of shared libraries, configuration files and optional
+an activation entry combined in a zip file. Bundles can be dynamically installed and started in an Apache Celix framework.
+
+## The anatomy of a Celix Bundle
+Technically an Apache Celix Bundle is a zip file with the following content:
+
+- META-INF/MANIFEST.MF: The required bundle manifest, containing information about the bundle (name, activator library etc)
+- Bundle shared libraries (so/dylib files): Optionally a bundle has 1 or more shared libraries.
+ The bundle manifest configures which libraries will be loaded (private libs) and which - if any - library is used
+ when activating the bundle.
+- Bundle resource files: A bundle can also contain additional resource files.
+ This could be configuration files, html files, etc.
+ It is also possible to have bundles which no shared library, but only resource files.
+ Note that bundles can access other bundles resources files.
+
+If a `jar` command is available the Celix CMake commands will use that (instead of the `zip` command) to create bundle
+zip files so that the MANIFEST.MF is always the first entry in the zip file.
+
+
+```bash
+#unpacking celix_shell_wui.zip bundle file from a cmake build `cmake-build-debug`.
+#The celix_shell_wui.zip file is the Celix Shell Web UI bundle. Which provides a web ui interface to the Celix
+#interactive shell; It contains a manifest file, shared libraries, and additional web resources
+#which can be picked up by the `Celix::http_admin` bundle.
+% unzip cmake-build-debug/bundles/shell/shell_wui/celix_shell_wui.zip -d unpacked_bundle_dir
+% find unpacked_bundle_dir
+unpacked_bundle_dir
+unpacked_bundle_dir/resources
+unpacked_bundle_dir/resources/index.html
+unpacked_bundle_dir/resources/ansi_up.js
+unpacked_bundle_dir/resources/script.js
+unpacked_bundle_dir/META-INF
+unpacked_bundle_dir/META-INF/MANIFEST.MF
+unpacked_bundle_dir/libcivetweb_shared.so #or dylib for OSX
+unpacked_bundle_dir/libshell_wui.1.so #or dylib for OSX
+```
+
+## Bundle lifecycle
+An Apache Celix Bundle has its own lifecycle with the following states:
+
+- Installed - The bundle has been installed into the Celix framework, but it is not yet resolved. For Celix this
+ currently means that not all bundle libraries can or have been loaded.
+- Resolved - The bundle is installed and its requirements have been met. For Celix this currently means that the
+ bundle libraries have been loaded.
+- Starting - Starting is a temporary state while the bundle activator create and start callbacks are being executed.
Review Comment:
... the bundle activator's create and start callbacks ...
##########
documents/getting_started/using_services_with_c.md:
##########
@@ -59,30 +57,24 @@ This is explicitly done with macros to prevent symbols so to that no linking dep
Then the actual struct for the service needs to be declared.
The first element of the service struct should be a handle which can be used to store the service context, as convention we keep this pointer a void pointer to explicitly make it opaque.
Note that also an opaque struct could be used (e.g a declared but not defined struct), but this can become problematic concerning components registering multiple services.
-In that case explicit cast are needed to prevent warning and this can be confusing for the To prevent that issues void pointers are preferred.
-The rest of the element should be function pointers, which by convention should return an celix_status_t or int (which is technically the same).
-The return value is used as a way of handling errors and is also needed to be able to make remote services (e.g. to be able to handle remote exceptions).
+The rest of the elements should be function pointers, which by convention should return a celix_status_t or int (technically the same).
+The return value is used as a way of handling errors.
-The first argument of a service function should be the service handle and if there is a result the last argument should be a output parameter (either pre allocated (e.g. double *) or not (e.g. double **)).
-If the caller is not the owner of the output argument, a const pointer should be used (e.g. const char**).
-It is also possible to create typedef of the pointer to the service struct (e.g. typedef struct example_struct example_t), but this is not needed.
-
-In the Celix code base there are still service which uses a typedef with a pointer (e.g. typedef struct example_struct* example_struct_pt). This should be avoided,
-because it is not possible to create the const pointer of those typedefs and it is not possible to include those typedef inside a existing struct without the needed for an additional malloc.
+The first argument of a service function should be the service handle and if there is a result the last argument should be an output parameter (either pre allocated (e.g. double *) or not (e.g. double **)).
+Use code documentation to clearly specify who is the owner of the output parameter (who needs to cleanup the memory).
### Semantic Versioning
-
For versioning, semantic versioning should be used.
A backward incompatible change should lead to a major version increase (e.g. 1.0.0 -> 2.0.0).
For a C Service versioning is used to express binary compatibility (for the same platform / compiler), change that are incompatible are:
Review Comment:
... changes that are incompatible ... instead of ... change that are incompatible ...
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscribe@celix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org