Feature/99 update documentation

bundles/cxx_remote_services/README.md

@@ -0,0 +1,22 @@
+---
+title: Apache Celix C++ Remote 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 C++ Remote Services

bundles/pubsub/pubsub_admin_tcp/src/pubsub_tcp_handler.c

@@ -1299,7 +1299,6 @@ int pubsub_tcpHandler_acceptHandler(pubsub_tcpHandler_t *handle, psa_tcp_connect
 #endif
         if (rc < 0) {
             pubsub_tcpHandler_freeEntry(entry);
-            free(entry);
             L_ERROR("[TCP Socket] Cannot create epoll\n");
         } else {
             // Call Accept Connection callback

documents/building/README.md

@@ -24,11 +24,14 @@ Apache Celix aims to be support a broad range of UNIX platforms.
 
 Currently, the [continuous integration build server] builds and tests Apache Celix for:
 
-* Ubuntu Bionic Beaver (20.04)
-    * GCC 
-    * CLang 
+* Ubuntu Focal Fossa (20.04)
+  * GCC
+  * CLang
+* Ubuntu Jammy Jellyfish (22.04)
+  * GCC 
+  * CLang 
 * OSX
-    * CLang
+  * CLang
 
 
 ### Download the Apache Celix sources
@@ -40,16 +43,74 @@ 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.
+Apache Celix can be build using [Conan](https://conan.io) as package manager/build system or by directly using
+[CMake](https://cmake.org).
 
-### Building and installing with preinstalled libraries
+### Building Apache Celix using Conan
 The following packages (libraries + headers) should be installed on your system:
 
 * Development Environment
     * build-essentials (gcc/g++ or clang/clang++) 
     * java or zip (for packaging bundles)
     * make (3.14 or higher)
     * git
+    * cmake (3.19 or higher)
+    * Conan (2 or higher)
+
+For Ubuntu 22.04, use the following commands:
+```bash
+sudo apt-get install -yq --no-install-recommends \
+    build-essential \
+    git \
+    default-jdk \
+    python3 \
+    python3-pip \
+    ninja-build
+
+#The cmake version for Ubuntu 20 is older than 3.14,
+#use snap to install the latest cmake version
+snap install cmake
+
+#Install conan
+pip3 install -U conan   
+```
+
+Configure conan default profile using automatic detection of the system
+```bash
+conan profile detect
+```
+
+Create Apache Celix package - and build the dependencies - in the Conan cache:
+```bash
+cd <celix_source_dir>
+conan create . --build missing -o build_all=True   
+#Optionally build with CMake->Ninja, instead of CMake->Make. Note this includes building dependencies with Ninja. 
+conan create . --build missing -o build_all=True  -c tools.cmake.cmaketoolchain:generator=Ninja 
+```
+
+Note installing Apache Celix is not required when using Conan, because Conan will install the Apache Celix package
+in the local Conan cache.
+
+It is also possible to only build a selection of the Apache Celix bundles and/or libs. This can be done by providing
+build options for the required parts instead of the `build_all=True` option. For example to only build the Apache Celix
+framework library and the Apache Celix utils library use the following command:
+```bash
+conan create . --build missing -o build_framework=True -o build_utils=True
+```
+
+To see a complete overview of the available build options use the following command:
+```bash
+conan inspect . | grep build_
+```
+
+### Building Apache Celix directly using CMake
+The following packages (libraries + headers) should be installed on your system:
+
+* Development Environment
+    * build-essentials (gcc/g++ or clang/clang++) 
+    * java or zip (for packaging bundles)
+    * make (3.19 or higher)
+    * git
 * Apache Celix Dependencies
     * libzip
     * uuid
@@ -62,7 +123,7 @@ The following packages (libraries + headers) should be installed on your system:
     * libczmq (for PubSubAdmin ZMQ)
 
 
-For Ubuntu 20.04, use the following commands:
+For Ubuntu 22.04, use the following commands:
 ```bash
 #### get dependencies
 sudo apt-get install -yq --no-install-recommends \

documents/bundles.md

@@ -104,7 +104,7 @@ The bundle context provides functions/methods to:
  - Find service ids for a given filter.
  - Use services directly (without manually creating a service tracker).
  - Use bundles directly (without manually creating a bundle tracker).
- - Wait for events in the Celix event thread.
+ - Wait for events in the Apache Celix event thread.
  - Retrieve framework property values. 
  - Retrieve the bundle object associated with the bundle context. 
 
@@ -180,7 +180,7 @@ add_celix_bundle(my_bundle
     SOURCES src/my_bundle_activator.c
 )
 
-#With `make all`, `make celix-containers` or `make my_container` this Celix container executable will be created at:
+#With `make all`, `make celix-containers` or `make my_container` this Apache Celix container executable will be created at:
 # ${CMAKE_BINARY_DIR}/deploy/my_container/my_container
 add_celix_container(my_container
     C
@@ -221,7 +221,7 @@ add_celix_bundle(MyBundle
     SOURCES src/MyBundleActivator.cc
 )
 
-#With `make all`, `make celix-containers` or `make MyContainer` this Celix container executable will be created at:
+#With `make all`, `make celix-containers` or `make MyContainer` this Apache Celix container executable will be created at:
 # ${CMAKE_BINARY_DIR}/deploy/my_container/MyContainer
 add_celix_container(MyContainer
     CXX
@@ -278,7 +278,7 @@ Bundles will be installed as zip files in the package (default the CMAKE_PROJECT
 It is also possible to use Apache Celix bundles as CMake imported targets, but this requires a more complex 
 CMake installation setup.
 
-## Installing Celix CMake targets
+## Installing Apache Celix CMake targets
 The `install_celix_targets` can be used to generate a CMake file with the imported Apache Celix Bundle CMake targets 
 and this is ideally coupled with a CMake config file so that the bundles are made available when 
 CMake's `find_package` is used.
@@ -296,7 +296,7 @@ add_celix_bundle(ExampleBundleB ...)
 #Install bundle zips
 install_celix_bundle(ExampleBundleA EXPORT MyExport)
 install_celix_bundle(ExampleBundleB EXPORT MyExport)
-#install exported Celix CMake targets
+#install exported Apache Celix CMake targets
 install_celix_targets(MyExport NAMESPACE ExamplePackage:: DESTINATION share/ExamplePackage/cmake FILE CelixTargets)
 
 #Install Package CMake configuration

documents/subprojects.md

@@ -19,24 +19,45 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Apache Celix - Subprojects
+# Apache Celix - Libraries and Bundles
 
-Apache Celix is organized into several subprojects. The following subproject are available:
+The Apache Celix project is organized into several libraries, bundles, group of bundles and examples.
+
+## Core Libraries
+The core of Apache Celix is realized in the following libraries:
 
 * [Framework](../libs/framework) - The Apache Celix framework, an implementation of OSGi adapted to C and C++11.
-* [Utils](../libs/utils/README.md) - The Celix utils library, containing a wide range of utils functions (string, file, C hashmap, C arraylist, etc)
-* [Examples](../examples) - A Selection of examples showing how the framework can be used.
-* [Log Service](../bundles/logging/README.md) - A Log Service logging abstraction for Apache Celix.
-  * [Syslog Writer](../bundles/logging/log_writers/syslog_writer) - A syslog writer for use in combination with the Log Service.
-* [Shell](../bundles/shell/README.md) - A OSGi C and C++11 shell implementation.
-* [Pubsub](../bundles/pubsub/README.md) - An implementation for a publish-subscribe remote message communication system. 
-* [HTTP Admin](../bundles/http_admin/README.md) - An implementation for the OSGi HTTP whiteboard adapted to C and based on civetweb.
-* [Remote Services](../bundles/cxx_remote_services) - A C++17 adaption and implementation of the OSGi Remote Service Admin specification.
-* [Components Ready Check](../bundles/components_ready_check/README.md) - A bundle which checks if all components are ready.
+* [Utils](../libs/utils/README.md) - The Celix utils library, containing a wide range of general utils and 
+                                     OSGi supporting types (properties, version, filter, string utils, file utils, etc).
 
-Standalone libraries:
+## Standalone Libraries
+Apache Celix also provides several standalone libraries which can be used without the framework:
 
-* [Etcd library](../libs/etcdlib/README.md) - A C library that interfaces with ETCD.
+* [ETCD library](../libs/etcdlib/README.md) - A C library that interfaces with ETCD.
 * [Promises library](../libs/promises/README.md) - A C++17 header only adaption and implementation of the OSGi Promise specification.
-* [Push Streams Library](../libs/pushstreams/README.md) - A C++17 header adaption and only implementation of the OSGi Push Stream specification. 
+* [Push Streams Library](../libs/pushstreams/README.md) - A C++17 header adaption and only implementation of the OSGi Push Stream specification.
+* [Dynamic Function Interfacy Library](../libs/dfi/README.md) - A C library, build on top of libffi, to dynamical create C function proxies based on descriptor files.
+
+When using Conan as build system, these libraries can be build standalone using the following commands:
+
+* ETCD library: `conan create . -b missing -o build_celix_etcdlib=True`
+* Promises library: `conan create . -b missing -o build_promises=True`
+* Push Streams Library: `conan create . -b missing -o build_pushstreams=True`
+* Dynamic Function Interfacy Library: `conan create . -b missing -o build_celix_dfi=True`
+
+## Bundles or Groups of Bundles
+Modularization is an important aspect of OSGi. Apache Celix provides several bundles or groups of bundles which extend
+the Apache Celix functionality. Most of these bundles are based on the OSGi specification and are adapted to C or C++.
+
+* [HTTP Admin](../bundles/http_admin/README.md) - An implementation for the OSGi HTTP whiteboard adapted to C and based on civetweb.
+* [Log Service](../bundles/logging/README.md) - A Log Service logging abstraction for Apache Celix.
+  * [Syslog Writer](../bundles/logging/log_writers/syslog_writer) - A syslog writer for use in combination with the Log Service.
+* [Shell](../bundles/shell/README.md) - A OSGi C and C++11 shell implementation, which can be extended with shell command services.
+* [Pubsub](../bundles/pubsub/README.md) - An implementation for a publish-subscribe remote message communication system.
+* [Remote Services](../bundles/remote_services) - A C adaption and implementation of the OSGi Remote Service Admin specification.
+* [C++ Remote Services](../bundles/cxx_remote_services/README.md) - A C++17 adaption and implementation of the OSGi Remote Service Admin specification. Requires manually or code-generated import/export factories to work.
+* [Components Ready Check](../bundles/components_ready_check/README.md) - A bundle which checks if all components are ready.
 
+## Examples
+The Apache Celix provides several [examples](../examples/celix-examples) showing how the framework and bundles can be used. These
+examples are configured in such a way that they can also be used together with an installed Apache Celix.

libs/dfi/README.md

@@ -0,0 +1,22 @@
+---
+title: Apache Celix Dynamic Function Interface
+---
+
+<!--
+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 Dynamic Function Interface

libs/promises/README.md

@@ -85,7 +85,7 @@ target_link_libraries(PromiseExamples PRIVATE Celix::Promises)
 
 ## Open Issues & TODOs
 
-- Documentation not complete
-- PromiseFactory is not complete yet
-- The static helper class Promises is not implemented yet (e.g. all/any)
-- Promise::flatMap not implemented yet
+- Documentation not complete.
+- PromiseFactory is not complete.
+- The static helper class Promises is not implemented (e.g. all/any).
+- Promise::flatMap not implemented.

libs/pushstreams/README.md

@@ -14,10 +14,3 @@ NOTE: this implementation is still experiment and the api and behaviour will pro
 [OSGi Compendium Release 7 Push Stream Specification (HTML)](https://osgi.org/specification/osgi.cmpn/7.0.0/util.pushstream.html)
 
 [OSGi Compendium Release 7 Specification (PDF)](https://docs.osgi.org/download/r7/osgi.cmpn-7.0.0.pdf)
-
-## Usage
-
-## Differences with OSGi PushStreams & Java
-
-
-## Open Issues & TODOs