CELIX-368: Updates documentations, fixes issues in generation eclipse launch file
Project: http://git-wip-us.apache.org/repos/asf/celix/repo Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/42414fa2 Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/42414fa2 Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/42414fa2 Branch: refs/heads/release/celix-2.0.0 Commit: 42414fa20939213bf841298273d4cdc89e364c3f Parents: 3c0bcf3 Author: Pepijn Noltes <pepijnnol...@gmail.com> Authored: Tue Oct 4 21:00:40 2016 +0200 Committer: Pepijn Noltes <pepijnnol...@gmail.com> Committed: Tue Oct 4 21:00:40 2016 +0200 ---------------------------------------------------------------------- cmake/cmake_celix/Packaging.cmake | 2 +- .../getting_started/creating_a_simple_bundle.md | 14 +++++++------- documents/getting_started/readme.md | 4 +++- .../getting_started/using_services_with_c.md | 20 +++++++++++--------- 4 files changed, 22 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/celix/blob/42414fa2/cmake/cmake_celix/Packaging.cmake ---------------------------------------------------------------------- diff --git a/cmake/cmake_celix/Packaging.cmake b/cmake/cmake_celix/Packaging.cmake index 91127cc..7ff5091 100644 --- a/cmake/cmake_celix/Packaging.cmake +++ b/cmake/cmake_celix/Packaging.cmake @@ -564,7 +564,7 @@ $<JOIN:$<TARGET_PROPERTY:${DEPLOY_TARGET},DEPLOY_PROPERTIES>, #generate eclipse project launch file set(PROGRAM_NAME "${CELIX_LAUNCHER}") set(CONTAINER_NAME ${DEPLOY_NAME}) - set(PROJECT_ATTR "build") + set(PROJECT_ATTR "${CMAKE_PROJECT_NAME}-build") set(WORKING_DIRECTORY ${DEPLOY_LOCATION}) include("${CELIX_CMAKE_DIRECTORY}/cmake_celix/RunConfig.in.cmake") #set VAR RUN_CONFIG_IN file(GENERATE http://git-wip-us.apache.org/repos/asf/celix/blob/42414fa2/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 5ea1c40..b5e4f24 100644 --- a/documents/getting_started/creating_a_simple_bundle.md +++ b/documents/getting_started/creating_a_simple_bundle.md @@ -216,12 +216,12 @@ To create the build directory and build the project execute the following comman ```bash cd ${WS} -mkdir myproject/build -cd myproject/build -cmake .. +mkdir myproject-build +cd myproject-build +cmake ../myproject make all #Or -#cmake -G Ninja .. +#cmake -G Ninja ../myproject #ninja ``` @@ -235,7 +235,7 @@ To create a deployment for the hello world bundles two things are needed: ```CMake #${WS}/myproject/CMakeLists.txt -add_deploy(hello +add_deploy(myproject BUNDLES ${CELIX_BUNDLES_DIR}/shell.zip ${CELIX_BUNDLES_DIR}/shell_tui.zip @@ -257,7 +257,7 @@ make -j Now a deploy directory myproject should be available in the deploy directory. This directory contains - among other files - the run.sh script. This can be used to run the Apache Celix framework with the declared bundles from the deploy.cmake. ```bash -cd ${WS}/myproject-build/deploy/hello +cd ${WS}/myproject-build/deploy/myproject . ./release.sh celix #or ./hello @@ -298,7 +298,7 @@ The idea behind service oriented programming is that functionality is provided a 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_cxx.md) http://git-wip-us.apache.org/repos/asf/celix/blob/42414fa2/documents/getting_started/readme.md ---------------------------------------------------------------------- diff --git a/documents/getting_started/readme.md b/documents/getting_started/readme.md index 9c391e9..4ea875b 100644 --- a/documents/getting_started/readme.md +++ b/documents/getting_started/readme.md @@ -1,6 +1,8 @@ #Apache Celix - Getting Started Guide ##Guides -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 or C++ bundle. +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_for_c.md) or [Getting Started: Using Services with C++](using_services_with_cxx.md). http://git-wip-us.apache.org/repos/asf/celix/blob/42414fa2/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 b098f48..5dd6ce9 100644 --- a/documents/getting_started/using_services_with_c.md +++ b/documents/getting_started/using_services_with_c.md @@ -1,12 +1,12 @@ -#Apache Celix - Best Practices +#Apache Celix - Using Services with C ## Intro -This example should give a best practice approach for providing and using service with Apache Celix. +This example gives an overview for providing and using services with Apache Celix with C. ## Services -To start-of, services in Celix are just a pointer to a memory location registered in the service registry using a name and an optional set of key/value pairs. +To start-of, C services in Celix are just a pointer to a memory location registered in the service registry using a name and an optional set of key/value pairs. By convention use the following service layout: @@ -32,7 +32,7 @@ typedef struct example_struct example_t; ``` -For a Celix service a service name, service version and service consumer range should be declared. +For a Celix service a service name, service provider version and service consumer range should be declared. This is explicitly done with macros to prevent symbols so to that no linking dependencies are introduced. Then the actual struct for the service needs to be declared. @@ -44,8 +44,11 @@ The rest of the element should be function pointers, which by convention should 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 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 **)). -It is also possible to create typedef of the pointer to the service struct (e.g. typedef struct example_service *example_service_pt), but this is not needed. -If you do not create typedefs with pointers it is easier to include service struct in an parent struct (without memory allocation) and also make it's possible to use the const on the struct instead of the pointer. +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. ### Semantic Versioning @@ -75,16 +78,15 @@ Changes considered backwards compatible which does not extend the functionaility ## 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. 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. The start function will only be called if all required service are available and the stop function will be called when some required are going or if the component needs to be stopped. Components can also have a `<cmpName>_init` and `<cmpName>_deinit` function which will be called before and after respectively the start and stop function. -The init function can be used to add additional (even required) service dependencies. -The use case for init/deinit component functions are exceptional. +The init/deinit function can be used to include (de)initialization which is not needed/wanted every time when service dependencies are being removed/added. - ## Code Examples The next code block contains some code examples of components to indicate how to handle service dependencies, how to specify providing services and how to cope with locking/synchronizing.
