Skip to content
Permalink
Browse files
Updates build, framework and dev documentation
  • Loading branch information
pnoltes committed Apr 10, 2022
1 parent 01b4e67 commit 2e63f9cc71c81e29d006bfa5f77dcf573e7d9958
Showing 36 changed files with 566 additions and 101 deletions.
@@ -27,7 +27,7 @@ It is a framework to develop (dynamic) modular software applications using compo

## Documentation
- [Building Apache Celix](documents/building/README.md)
- [Apache Celix Intro](documents/intro/README.md)
- [Apache Celix Intro](documents/README.md)

## Building in a Nutshell

@@ -59,7 +59,8 @@ Even though the dependency manager is not part of the OSGi specification,
this is the preferred way of handling dynamics services in Celix, because it uses a higher abstraction.

## Containers
Apache Celix containers are executable which start a Celix framework and a preconfigured set of bundles.
Apache Celix containers are executables which starts a Celix framework, with a set of preconfigured properties
and a preconfigured set of bundles.
Although it is also possible to create and start a Celix framework in code, the benefit of a Celix container
is that this can be done with a single `add_celix_container` Celix CMake command.

@@ -75,15 +76,17 @@ libstdc++.
Apache Celix also offers some C++ only libraries and bundles. The C++ libraries are also header only, but the C++
bundles contains binaries depending on the stdlibc++ library.

## Documentation

For more information see:

* [Apache Celix - Building and Installing](../building/README.md)
* [Apache Celix - Bundles](bundles.md)
* [Apache Celix - Services](services.md)
* [Apache Celix - Components](components.md)
* TODO MAYBE add Creating Containers readme
* TODO MAYBE Services on demand -> meta tracker in C and C++
* [Apache Celix - Getting Started Guide](../getting_started/README.md) TODO MAYBE REMOVE, replaced with bundles.md, services.md
* [Apache Celix - CMake Commands](../cmake_commands/README.md)
## More information

* Building
* [Building and Installing Apache Celix](building)
* [Building and Developing Apache Celix with CLion](building/dev_celix_with_clion.md)
* Framework
* [Apache Celix Bundles](bundles.md)
* [Apache Celix Services](services.md)
* [Apache Celix Components](components.md)
* [Starting and stopping an Apache Celix Framework](framework.md)
* [Apache Celix Containers](containers.md)
* [OSGi patterns in Apache Celix](patterns.md)
* [Apache Celix CMake Commands](cmake_commands)
* [Apache Celix - Getting Started Guide](getting_started) TODO MAYBE REMOVE, replaced with bundles.md, services.md
@@ -1,5 +1,5 @@
---
title: Building and Installing
title: Building and Installing Apache Celix
---

<!--
@@ -19,19 +19,30 @@ 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 (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
@@ -41,6 +52,8 @@ The following packages (libraries + headers) should be installed on your system:
* Apache Celix Dependencies
* libzip
* uuid
* zlib
* libzip
* curl (only initialized in the Celix framework)
* jansson (for serialization in libdfi)
* libffi (for libdfi)
@@ -49,12 +62,8 @@ The following packages (libraries + headers) should be installed on your system:
* libczmq (for PubSubAdmin ZMQ)


For debian based systems (apt), the following command should work:
For Ubuntu 20.04, use the following commands:
```bash
#### prepare system
sudo apt-get update
sudo apt-get upgrade
#### get dependencies
sudo apt-get install -yq --no-install-recommends \
build-essential \
@@ -76,25 +85,14 @@ sudo apt-get install -yq --no-install-recommends \
snap install cmake
```

For OSX systems with brew installed, the following command should work:
For OSX systems with brew installed, use the following commands:
```bash
brew update && \
brew install lcov libffi libzip czmq rapidjson libxml2 cmake && \
brew link --force libffi
```

## 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 Apache Celix
Apache Celix uses [CMake](https://cmake.org) as build system. CMake can generate (among others) makefiles.

### Building using CMake and makefiles:
Use CMake and make to build Apache Celix
```bash
cd celix
mkdir build
@@ -125,12 +123,11 @@ sudo make install
```

## Running Apache Celix

If Apache Celix is successfully installed running
```bash
celix
```
should give the following output:
"Error: invalid or non-existing configuration file: 'config.properties'.No such file or directory".

For more info how to build your own projects and/or running the Apache Celix examples see [Celix Intro](../intro/README.md).
For more info how to build your own projects and/or running the Apache Celix examples see [Celix Intro](../README.md).
@@ -0,0 +1,64 @@
---
title: Building and Developing Apache Celix with CLion
---

<!--
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.
-->

# Building and Developing Apache Celix with CLion
Apache Celix can be build for development in CLion with use of the Conan package manager.
Conan will arrange the building of the Apache Celix dependencies and generate Find<package> files for these dependencies.

Conan will also generate a `active_run.sh` and `deactivate_run.sh` script that does the environment (de)setup for the
binary locations of the build dependencies (i.e. configures `PATH` and `LD_LIBRARY_PATH`/`DYLD_LIBRARY_PATH`).

## Setting up the build directory
```shell
#clone git repo
git clone https://github.com/apache/celix.git
cd celix
#if needed setup conan default and debug profile
conan profile new default --detect
conan profile new debug --detect
conan profile update settings.build_type=Debug debug
#generate and configure cmake-build-debug directory
conan install . celix/2.3.0@apache/testing -pr:b default -pr:h debug -if cmake-build-debug/ -o celix:enable_testing=True -o celix:enable_address_sanitizer=True -o celix:build_all=True -b missing
conan build . -bf cmake-build-debug/ --configure
#optional build
cd cmake-build-debug
make -j
#optional setup run env and run tests
source activate_run.sh
ctest --verbose
source deactivate_run.sh
```

## Configuring CLion
To ensure that all Conan build dependencies can be found the Run/Debug configurations of CLion needs te be updated.

This can be done under the menu "Run->Edit Configurations...", then select "Edit configuration templates..." and
then update the "Google Test" template so that the `active_run.sh` Conan generated script is sourced in the
"Environment variables" entry.

If the Apache Celix CMake build directory is `home/joe/workspace/celix/cmake-build-debug` then the value for
"Environment variables" should be: `source /home/joe/workspace/celix/cmake-build-debug/run_activate.sh`

![Configure CLion](media/clion_run_configuration_template.png)
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -1,5 +1,5 @@
---
title: Bundles
title: Apache Celix Bundles
---

<!--
@@ -19,7 +19,7 @@ See the License for the specific language governing permissions and
limitations under the License.
-->

# Bundles
# Apache Celix Bundles
An Apache Celix Bundle is dynamically loadable collection of shared libraries, configuration files and optional
an activation entry combined in a zip file. Bundles can be dynamically installed and started in a Celix framework.

@@ -223,4 +223,62 @@ add_celix_container(MyContainer
By design bundles cannot directly access the symbols of another bundle. Interaction between bundles must be done using
Celix services. This means that unless functionality is provided by means of a Celix service, bundle functionality
is private to the bundle.
In Celix symbols are kept private by loading bundle libraries locally (`dlopen` with `RTLD_LOCAL`).
In Celix symbols are kept private by loading bundle libraries locally (`dlopen` with `RTLD_LOCAL`).
## Installing bundles
Celix bundles can be installed with the Celix CMake command `install_celix_bundle`.
Bundles will be installed as zip files in the package (default the CMAKE_PROJECT_NAME) share directory
(e.g `/use/share/celix/bundles`).
It is also possible to use Celix bundles as CMake imported targets, but this requires a more complex CMake installation
setup.
The `install_celix_targets` can be used to generate a CMake file with the imported Celix Bundle CMake targets and
this is ideally coupled with a CMake config file so that the bundles are made avaible when CMake's `find_package` is
used.
Example:
```CMake
#Project setup
project(ExamplePackage C CXX)
find_package(Celix REQUIRED)
#Create bundles
add_celix_bundle(ExampleBundleA ...)
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_celix_targets(MyExport NAMESPACE ExamplePackage:: DESTINATION share/ExamplePackage/cmake FILE CelixTargets)
#Install Package CMake configuration
file(GENERATE OUTPUT ${CMAKE_BINARY_DIR}/ExamplePackageConfig.cmake CONTENT "
# relative install dir from lib/CMake/ExamplePackage.
get_filename_component(REL_INSTALL_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
get_filename_component(REL_INSTALL_DIR "${REL_INSTALL_DIR}" PATH)
get_filename_component(REL_INSTALL_DIR "${REL_INSTALL_DIR}" PATH)
get_filename_component(REL_INSTALL_DIR "${REL_INSTALL_DIR}" PATH)
include(${REL_INSTALL_DIR}/share/celix/cmake/CelixTargets.cmake)
")
install(FILES
${CMAKE_BINARY_DIR}/ExamplePackageConfig.cmake
DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ExamplePackage)
```
Downstream Usage Example:
```CMake
project(UsageExample C CXX)
find_package(Celix REQUIRED)
find_package(ExamplePackage REQUIRED)
add_celix_container(test_container BUNDLES
Celix::shell
Celix::shell_tui
ExamplePackage::ExampleBundleA
ExamplePackage::ExampleBundleB
)
```
See [Apache Celix CMake Commands](cmake_commands) for more detailed information.
@@ -236,7 +236,7 @@ install_celix_bundle(<bundle_target>

## install_celix_targets
Generate and install a Celix Targets cmake file which contains CMake commands to create imported targets for the bundles
install using the provided <export_name>. These imported CMake targets can be used in in CMake project using the installed
install using the provided <export_name>. These imported CMake targets can be used in CMake projects using the installed
bundles.

Optional Arguments:
File renamed without changes.
@@ -0,0 +1,74 @@
---
title: Apache Celix Containers
---

<!--
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 Containers
Apache Celix containers are executables which starts a Celix framework, with a set of preconfigured properties
and a preconfigured set of bundles.
Although it is also possible to create and start a Celix framework in code, the benefit of a Celix container
is that this can be done with a single `add_celix_container` Celix CMake command.

## Celix Container overview

### Example minimal (empty) container
```CMake
add_celix_container(my_empty_container)
```

### Example web shell container

```CMake
add_celix_container(my_web_shell_container
BUNDLES
Celix::http_admin
Celix::shell
Celix::shell_wui
PROPERTIES
CELIX_LOGGING_DEFAULT_ACTIVE_LOG_LEVEL=debug
CELIX_HTTP_ADMIN_LISTENING_PORTS=8888
)
```

## Celix Container Properties

## Celix Container Run Levels

## Celix Container Cache Directory

## Installing Celix container
Currently, installing Apache Celix containers (i.e. using `make install` on a Celix Container) is not supported.

The reason behind this is that an Apache Celix container depends on the location of bundles and there is currently no
reliable way to find bundles in a system. For this to work Apache Celix should support something like:
- A bundle search path concept like `LD_LIBRARY_PATH`
- Support for embedded bundles in an executable so that Apache Celix containers can be self containing
- Bundles as shared libraries (instead of zip) so that the normal shared libraries concepts
(installation, `LD_LIBRARY_PATH`, etc ) can be reused.

There is an exception when an installation of a Apache Celix containers works: If all used bundles are based on already
installed bundles and are added to the Apache Celix container with an absolute path (default).

TODO Apache Celix containers deploy directories and OSI/docker images.






File renamed without changes.
File renamed without changes.

0 comments on commit 2e63f9c

Please sign in to comment.