You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@celix.apache.org by pn...@apache.org on 2018/01/30 19:19:45 UTC
[49/50] [abbrv] celix git commit: CELIX-412: Updates building and
getting started documentation
CELIX-412: Updates building and getting started documentation
Project: http://git-wip-us.apache.org/repos/asf/celix/repo
Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/34ed6ba3
Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/34ed6ba3
Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/34ed6ba3
Branch: refs/heads/master
Commit: 34ed6ba364539f9ba320e16ea22408935617c232
Parents: 5f0bc1c
Author: Pepijn Noltes <pe...@gmail.com>
Authored: Wed Jan 24 12:58:17 2018 +0100
Committer: Pepijn Noltes <pe...@gmail.com>
Committed: Wed Jan 24 12:58:17 2018 +0100
----------------------------------------------------------------------
documents/building/readme.md | 14 +--
.../getting_started/creating_a_simple_bundle.md | 100 +++++++++--------
.../getting_started/getting_started_img3.png | Bin 127686 -> 0 bytes
documents/getting_started/readme.md | 5 +-
.../getting_started/using_services_with_c.md | 108 +++++++++----------
5 files changed, 114 insertions(+), 113 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/celix/blob/34ed6ba3/documents/building/readme.md
----------------------------------------------------------------------
diff --git a/documents/building/readme.md b/documents/building/readme.md
index e624d26..79f1a64 100644
--- a/documents/building/readme.md
+++ b/documents/building/readme.md
@@ -48,7 +48,6 @@ For debian based systems (apt), the following command should work:
```bash
sudo apt-get install -yq --no-install-recommends \
build-essential \
- ninja \
curl \
git \
libjansson-dev \
@@ -64,7 +63,6 @@ For Fedora based systems (dnf), the following command should work:
sudo dnf group install -y "C Development Tools and Libraries"
sudo dnf install \
cmake \
- ninja-build \
make \
git \
java \
@@ -96,8 +94,7 @@ 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 or ninja build files.
-using ninja build files will result in a faster build.
+Apache Celix uses [CMake](https://cmake.org) as build system. CMake can generate (among others) makefiles.
### Building using CMake and makefiles:
```bash
@@ -108,15 +105,6 @@ cmake ..
make
```
-### Building using CMake and Ninja
-```bash
-cd ${WS}/celix
-mkdir build
-cd build
-cmake -G Ninja ..
-ninja
-```
-
## Editing Build options
With use of CMake, Apache Celix makes it possible to edit build options. This enabled users, among other options, to configure a install location and select additional bundles.
To edit the options use ccmake or cmake-gui. For cmake-gui an additional package install can be necessary (Fedora: `dnf install cmake-gui`).
http://git-wip-us.apache.org/repos/asf/celix/blob/34ed6ba3/documents/getting_started/creating_a_simple_bundle.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/creating_a_simple_bundle.md b/documents/getting_started/creating_a_simple_bundle.md
index e580477..8f10869 100644
--- a/documents/getting_started/creating_a_simple_bundle.md
+++ b/documents/getting_started/creating_a_simple_bundle.md
@@ -68,8 +68,8 @@ find_package(CELIX REQUIRED)
include_directories(${CELIX_INCLUDE_DIRS})
#Part 4. Choose C, C++ or both
-add_subdirectory(bundles/hello_world) #C
-add_subdirectory(bundles/HelloWorld) #C++
+add_subdirectory(bundles/HelloWorld_c) #C
+add_subdirectory(bundles/HelloWorld_cxx) #C++
```
This CMakeLists.txt file, sets up the following:
@@ -94,49 +94,46 @@ Create the sub directory:
```CMake
#Create directory structure for the hello_world bundles
cd ${WS}/myproject
-mkdir -p bundles/hello_world/private/src
-mkdir -p bundles/HelloWorld/private/src
-mkdir -p bundles/HelloWorld/private/include
+mkdir -p bundles/HelloWorld_c/src
+mkdir -p bundles/HelloWorld_cxx/src
+mkdir -p bundles/HelloWorld_cxx/include
```
And add the following CMakeLists.txt file for the C Bundle:
```CMake
-#${WS}/myproject/bundles/hello_world/CMakeLists.txt
+#${WS}/myproject/bundles/HelloWorld_c/CMakeLists.txt
-add_celix_bundle(hello_world
+add_celix_bundle(HelloWorld_c
VERSION 1.0.0
SOURCES
- private/src/hello_world_activator.c
+ src/HelloWorld_activator.c
)
if(APPLE)
- target_link_libraries(hello_world ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_LIB})
+ target_link_libraries(HelloWorld_c ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_LIB})
else()
- target_link_libraries(hello_world -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
+ target_link_libraries(HelloWorld_c -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
endif()
```
And/or the following CMakeLists.txt for the C++ bundle:
```CMake
-#${WS}/myproject/bundles/HelloWorld/CMakeLists.txt
+#${WS}/myproject/bundles/HelloWorld_cxx/CMakeLists.txt
-include_directories(
- private/include
-)
-
-add_celix_bundle(HelloWorld
+add_celix_bundle(HelloWorld_cxx
VERSION 1.0.0
SOURCES
- private/src/HelloWorldActivator.cc
+ src/HelloWorldActivator.cc
)
+target_include_directories(HelloWorld_cxx PRIVATE include)
IF(APPLE)
- target_link_libraries(HelloWorld ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_CXX_LIB})
+ target_link_libraries(HelloWorld_cxx ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_CXX_LIB})
else()
- target_link_libraries(HelloWorld -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_CXX_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
+ target_link_libraries(HelloWorld_cxx -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_CXX_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES})
endif()
```
@@ -151,7 +148,7 @@ The dependency manager uses a higher abstraction and is more simple to understan
The C Bundle Activator:
```C
-//${WS}/myproject/bundles/hello_world/private/src/hello_world_activator.c
+//${WS}/myproject/bundles/hello_world/src/HelloWorld_activator.c
#include <stdlib.h>
#include <stdio.h>
@@ -188,32 +185,30 @@ celix_status_t dm_destroy(void* userData, bundle_context_pt context, dm_dependen
The C++ Bundle Activator (header + source):
```C++
-//${WS}/myproject/bundles/HelloWorld/private/include/HelloWorldActivator.h
+//${WS}/myproject/bundles/HelloWorld/include/HelloWorldActivator.h
#ifndef HELLOWORLDACTIVATOR_H_
#define HELLOWORLDACTIVATOR_H_
#include "celix/dm/DmActivator.h"
-using namespace celix::dm;
-
-class HelloWorldActivator : public DmActivator {
+class HelloWorldActivator : public celix::dm::DmActivator {
private:
- const std::string word {"C++ World"};
+ const std::string word {"C++ World"};
public:
- HelloWorldActivator(DependencyManager& mng) : DmActivator {mng} {}
+ HelloWorldActivator(celix::dm::DependencyManager& mng) : DmActivator {mng} {}
virtual void init();
virtual void deinit();
};
#endif //HELLOWORLDACTIVATOR_H_
+```
+```C++
//${WS}/myproject/bundles/HelloWorld/private/src/HelloWorldActivator.cc
#include "HelloWorldActivator.h"
#include <iostream>
-using namespace celix::dm;
-
-DmActivator* DmActivator::create(DependencyManager& mng) {
+DmActivator* DmActivator::create(celix::dm::DependencyManager& mng) {
return new HelloWorldActivator(mng);
}
@@ -241,14 +236,16 @@ cmake ../myproject
make all
```
-Hopefully you will some some build results scrolling over the screen and actual build results in the build directory. There should be a hello_world.zip in the bundles/hello_world directory, this the actual bundle.
-A bundle on its own has no real value, so lets setup a deployment and run the Apache Celix framwork with these bundles.
+Hopefully you will some some build results scrolling over the screen and actual build results in the build directory.
+There should be a HelloWorld_c.zip in the bundles/HelloWorld_c directory and a HelloWorld_cxx.zip in the bundles/HelloWorld_cxx directory,
+these are the actual bundles.
+A bundle on its own has no real value, so lets setup a Celix container and run Celix with these bundles.
### Running
To create a deployment for the hello world bundles two things are needed:
-1. Add a `add_celix_container` statement in the `CMakeLists.txt` file declaring what to deploy and under which name.
+1. Add a `add_celix_container` statement in the (top level) `CMakeLists.txt` file declaring what to deploy and under which name.
```CMake
#${WS}/myproject/CMakeLists.txt
@@ -258,11 +255,14 @@ add_celix_container(myproject
${CELIX_BUNDLES_DIR}/shell.zip
${CELIX_BUNDLES_DIR}/shell_tui.zip
${CELIX_BUNDLES_DIR}/dm_shell.zip
- hello_world #C bundle
- HelloWorld #C++ bundle
+ HelloWorld_c #C bundle
+ HelloWorld_cxx #C++ bundle
)
```
-
+
+With the `add_celix_container` CMake function a Celix container will be configured, which bundles to use can be specified with absolute paths to
+bundle files (e.g. the shell.zip bundle) or Celix bundle CMake target (e.g. the HelloWorld_c bundle).
+
Rerun make again form the build project. the make files generated by CMake will ensure cmake is run it again to update the actual make files.
```bash
@@ -274,20 +274,19 @@ Now a deploy directory myproject should be available in the deploy directory. Th
```bash
cd ${WS}/myproject-build/deploy/myproject
-. ./release.sh
-./hello
+./myproject
```
-The hello_world bundle should be started with the famous "Hello World" text printed twice from the C and C++ bundle. The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for querying the installed bundles, listing all known shell command, showing the help of a specific command and stopping a specific bundle (note that bundle 0 is the framework "bundle"):
+The HelloWorld_c and HelloWorld_cxx bundles should be started with their own famous "Hello World" text variant printed. One for the C and one for the C++ bundle.
+The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for querying the installed bundles, listing all known shell command, showing the help of a specific command and stopping a specific bundle (note that bundle 0 is the framework "bundle"):
```
lb
help
-help inspect
stop 0
```
-## Apache Celix Bundle Project in Eclipse
+## Apache Celix Projects in Eclipse
A nice feature of CMake is the ability to generate Eclipse project files, with this feature bundles can also be developed with use of Eclipse. This should help speed up the development process.
To get started change directory to the build directory and generate a eclipse project file.
@@ -303,17 +302,30 @@ Import the project with existing project.
-To build the project, use Project->Build All. To run or debug from Eclipse navigate to the myproject deploy directory and right click on the 'myproject-deploy.launch' file. And select Run As or Debug As to run or debug the bundle.
+To build the project, use Project->Build All.
+To run or debug from Eclipse navigate to the myproject deploy directory and right click on
+the 'myproject' executable and as "Local C/C++ Application"
+
+
+## Apache Celix Projects in CLion
+
+Using Apache Celix projects in CLion quite easy.
+Just use `File -> Open ...` and select a Apache Celix project.
+Because CLion is a IDE for CMake projects and Apache Celix projects are CMake projects this works out of the box.
+
+To run a Celix container just select the target from CLion and press Run.
-
## Next
+The get a complete overview of the available Celix CMake commands see:
+ - [Apache Celix - Celix CMake Commands](../cmake_commands/readme.md)
+
The idea behind service oriented programming is that functionality is provided and used by abstract service, which hide implementation details.
For a guide how to provide and use services see
-* [Apache Celix - Getting Started Guide: Using Services with C](using_services_with_c.md)
-* [Apache Celix - Getting Started Guide: Using Services with C++](using_services_with_cxx.md)
+- [Apache Celix - Getting Started Guide: Using Services with C](using_services_with_c.md)
+- [Apache Celix - Getting Started Guide: Using Services with C++](using_services_with_cxx.md)
http://git-wip-us.apache.org/repos/asf/celix/blob/34ed6ba3/documents/getting_started/getting_started_img3.png
----------------------------------------------------------------------
diff --git a/documents/getting_started/getting_started_img3.png b/documents/getting_started/getting_started_img3.png
deleted file mode 100644
index 3d4cf42..0000000
Binary files a/documents/getting_started/getting_started_img3.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/celix/blob/34ed6ba3/documents/getting_started/readme.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/readme.md b/documents/getting_started/readme.md
index 6dd798c..9692bc0 100644
--- a/documents/getting_started/readme.md
+++ b/documents/getting_started/readme.md
@@ -21,5 +21,6 @@ limitations under the License.
There are several guide to help you get started. The first guide is [Getting Started: Creating a simple bundle](creating_a_simple_bundle.md)
and this should get you started for your first C and/or C++ bundle.
-After that you can extend the example by providing and use services using the
-guide [Getting Started: Using Services with C](using_services_with_c.md) or [Getting Started: Using Services with C++](using_services_with_cxx.md).
+After that you can extend the example by using services with the following guides:
+ - [Getting Started: Using Services with C](using_services_with_c.md)
+ - [Getting Started: Using Services with C++](using_services_with_cxx.md).
http://git-wip-us.apache.org/repos/asf/celix/blob/34ed6ba3/documents/getting_started/using_services_with_c.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/using_services_with_c.md b/documents/getting_started/using_services_with_c.md
index 258b147..6622cba 100644
--- a/documents/getting_started/using_services_with_c.md
+++ b/documents/getting_started/using_services_with_c.md
@@ -32,9 +32,9 @@ By convention use the following service layout:
#ifndef EXAMPLE_H_
#define EXAMPLE_H_
-#define EXAMPLE_NAME "org.example"
-#define EXAMPLE_VERSION "1.0.0"
-#define EXAMPLE_CONSUMER_RANGE "[1.0.0,2.0.0)"
+#define EXAMPLE_NAME "org.example"
+#define EXAMPLE_VERSION "1.0.0"
+#define EXAMPLE_CONSUMER_RANGE "[1.0.0,2.0.0)"
struct example_struct {
@@ -98,7 +98,7 @@ For C services generally platform specific calling convention are used therefore
## Components
Component should use the ADT principle (see [ADT in C](http://inst.eecs.berkeley.edu/~selfpace/studyguide/9C.sg/Output/ADTs.in.C.html)).
-Note that is a a convention.
+Note that is a convention.
Components should have a `<cmpName>_create` and `<cmpName>_destroy` function.
Components can have a `<cmpName>_start` and `<cmpName>_stop` function to start/stop threads or invoke functionality needed a fully created component.
@@ -180,44 +180,44 @@ struct activator {
};
celix_status_t dm_create(bundle_context_pt context, void **userData) {
- celix_status_t status = CELIX_SUCCESS;
- struct activator *act = calloc(1, sizeof(*act));
- if (act != NULL) {
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *act = calloc(1, sizeof(*act));
+ if (act != NULL) {
- act->bar = bar_create();
- act->exampleService.handle = act->bar;
- act->exampleService.method = (void*) bar_method;
+ act->bar = bar_create();
+ act->exampleService.handle = act->bar;
+ act->exampleService.method = (void*) bar_method;
- if (act->bar != NULL) {
+ if (act->bar != NULL) {
*userData = act;
} else {
free(act);
}
- } else {
- status = CELIX_ENOMEM;
+ } else {
+ status = CELIX_ENOMEM;
}
return status;
}
celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
celix_status_t status = CELIX_SUCCESS;
- struct activator *activator = userData;
+ struct activator *activator = userData;
- dm_component_pt cmp = NULL;
- component_create(context, "BAR", &cmp);
- component_setImplementation(cmp, activator->bar);
- component_addInterface(cmp, EXAMPLE_NAME, EXAMPLE_VERSION, &activator->exampleService, NULL);
+ dm_component_pt cmp = NULL;
+ component_create(context, "BAR", &cmp);
+ component_setImplementation(cmp, activator->bar);
+ component_addInterface(cmp, EXAMPLE_NAME, EXAMPLE_VERSION, &activator->exampleService, NULL);
- dependencyManager_add(manager, cmp);
+ dependencyManager_add(manager, cmp);
return status;
}
celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
- celix_status_t status = CELIX_SUCCESS;
- struct activator *activator = userData;
- bar_destroy(activator->bar);
- free(activator);
- return status;
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *activator = userData;
+ bar_destroy(activator->bar);
+ free(activator);
+ return status;
};
```
@@ -342,53 +342,53 @@ struct activator {
};
celix_status_t dm_create(bundle_context_pt context, void **userData) {
- celix_status_t status = CELIX_SUCCESS;
- struct activator *act = calloc(1, sizeof(*act));
- if (act != NULL) {
- act->foo = foo1_create();
+ celix_status_t status = CELIX_SUCCESS;
+ struct activator *act = calloc(1, sizeof(*act));
+ if (act != NULL) {
+ act->foo = foo1_create();
if (act->foo != NULL) {
*userData = act;
} else {
free(act);
}
- } else {
- status = CELIX_ENOMEM;
- }
- return status;
+ } else {
+ status = CELIX_ENOMEM;
+ }
+ return status;
}
celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) {
celix_status_t status = CELIX_SUCCESS;
- struct activator *activator = userData;
+ struct activator *activator = userData;
- dm_component_pt cmp = NULL;
- component_create(context, "FOO1", &cmp);
- component_setImplementation(cmp, activator->foo);
+ dm_component_pt cmp = NULL;
+ component_create(context, "FOO1", &cmp);
+ component_setImplementation(cmp, activator->foo);
- /*
- With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component
- with type foo1_t*
- */
+ /*
+ With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component
+ with type foo1_t*
+ */
component_setCallbacksSafe(cmp, foo1_t*, NULL, foo1_start, foo1_stop, NULL);
- dm_service_dependency_pt dep = NULL;
- serviceDependency_create(&dep);
- serviceDependency_setRequired(dep, true);
- serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL);
- serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING);
+ dm_service_dependency_pt dep = NULL;
+ serviceDependency_create(&dep);
+ serviceDependency_setRequired(dep, true);
+ serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL);
+ serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING);
- /*
- With the serviceDependency_setCallbacksSafe we register callbacks when a service
- is added and about to be removed for the component type foo1_t* and service type example_t*.
+ /*
+ With the serviceDependency_setCallbacksSafe we register callbacks when a service
+ is added and about to be removed for the component type foo1_t* and service type example_t*.
- We should protect the usage of the
- service because after removal of the service the memory location of that service
- could be freed
- */
+ We should protect the usage of the
+ service because after removal of the service the memory location of that service
+ could be freed
+ */
serviceDependency_setCallbacksSafe(dep, foo1_t*, const example_t*, foo1_setExample, NULL, NULL, NULL, NULL);
- component_addServiceDependency(cmp, dep);
+ component_addServiceDependency(cmp, dep);
- dependencyManager_add(manager, cmp);
+ dependencyManager_add(manager, cmp);
return status;
}