celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject celix git commit: CELIX-412: Updates building and getting started documentation
Date Wed, 24 Jan 2018 11:49:35 GMT
Repository: celix
Updated Branches:
  refs/heads/release/2.1.0 5f0bc1ce9 -> 34ed6ba36


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/release/2.1.0
Commit: 34ed6ba364539f9ba320e16ea22408935617c232
Parents: 5f0bc1c
Author: Pepijn Noltes <pepijnnoltes@gmail.com>
Authored: Wed Jan 24 12:58:17 2018 +0100
Committer: Pepijn Noltes <pepijnnoltes@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.
 
 ![import project](getting_started_img2.png)
 
-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.
 
-![run project](getting_started_img3.png) 
  
 ## 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;
 }


Mime
View raw message