You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@celix.apache.org by ab...@apache.org on 2011/11/17 14:05:26 UTC
svn commit: r1203179 - in /incubator/celix/site/trunk:
content/celix/documentation/buildingandrunning.mdtext
content/celix/documentation/design.mdtext
content/celix/documentation/mapping.mdtext templates/sidenav.mdtext
Author: abroekhuis
Date: Thu Nov 17 13:05:25 2011
New Revision: 1203179
URL: http://svn.apache.org/viewvc?rev=1203179&view=rev
Log:
Documentation updates
Updated building and running. Added overview of mapping between OSGi (Java) and Celix (C)
Added:
incubator/celix/site/trunk/content/celix/documentation/mapping.mdtext
Modified:
incubator/celix/site/trunk/content/celix/documentation/buildingandrunning.mdtext
incubator/celix/site/trunk/content/celix/documentation/design.mdtext
incubator/celix/site/trunk/templates/sidenav.mdtext
Modified: incubator/celix/site/trunk/content/celix/documentation/buildingandrunning.mdtext
URL: http://svn.apache.org/viewvc/incubator/celix/site/trunk/content/celix/documentation/buildingandrunning.mdtext?rev=1203179&r1=1203178&r2=1203179&view=diff
==============================================================================
--- incubator/celix/site/trunk/content/celix/documentation/buildingandrunning.mdtext (original)
+++ incubator/celix/site/trunk/content/celix/documentation/buildingandrunning.mdtext Thu Nov 17 13:05:25 2011
@@ -10,58 +10,107 @@ To be able to build Celix, the following
CMake (2.8.1)
GNU Make (3.81)
GCC (4.2.1)
- ZLib
- CUnit
Celix sources
+ Sub-project dependencies
+
+Note: Currently the framework and the examples are in one large project, this results in required libraries which aren't used by the framework itself.
+The following is a list of libraries per sub-project:
+
+ Utils:
+ - Apache Portable Runtime
+ - CUnit
+
+ Framework:
+ - Apache Portable Runtime
+ - CUnit
+ - ZLib
+ - Utils (Celix sub-project)
+
+ Shell:
+ - all framework dependencies
+ - cURL
+
+ Remote Services:
+ - all framework dependencies
+ - Jansson (library for encoding/decoding JSON)
+ - Apache Portable Runtime Utils
+
+ Paint example:
+ - all framework dependencies
+ - GTK (2.14 or higher)
## Building
Celix uses CMake to generate makefile. There are cmake scripts to build the libraries, but also to deploy created bundles to a named target.
-To start building and using Celix these makefiles have to be created.
+To start building and using Celix these makefiles have to be created. CMake supports out-of-source builds, for Celix the build directory is used for this.
// First extract the sources
- tar -xvzf celix.tar.gz
+ svn co https://svn.apache.org/repos/asf/incubator/celix/trunk/ celix
cd celix
- // Create and go to the build directory
+ // Create and go to the build directory to be able to do an out-of-source build
mkdir build
cd build
// Generate the make files in the current directory
cmake ..
-After generating the make files, the sources can be build. There are several build targets to build the libraries, deploy the bundles and package archives.
+After generating the make files, the sources can be build. There are several build targets to build the bundles, deploy and package them.
+The following targets are available:
+ // Build all libraries, bundles and packages
+ make all -> build all libraries, bundles and packages
+
+ // Deploy all deployment targets
+ make deploy -> deploys all deployments
+
+ // Build a single bundle (and its dependencies)
+ make {bundle_name}
+
+ // Deploy a singe deployment target (and its dependencies)
+ make deploy_{deployment_name} -> deploys a single deployment (and dependencies)
+
+ // Clean the entire build, including deployment, bundles, libraries etc
+ make clean -> removes all deployments, bundles, libraries etc
+
+ // Build a "framework.zip" file with the framework, headers and selected bundles
+ make install-fw
- // Build all libraries
- make
- // Create all bundles in the "bundles" directory
- make bundles
- // Create all targets in the "deploy" directory
- make deploy
- // Create archives in the "packages" directory
- make packages
+Also it is possible to enter sub directories of the build and run the build from there. So when running make from "build/shell" only the shell
+(and dependencies) will be build. This is the same as running "make shell" in the build root.
+
+Note: The build files are recursive. If a target is build, all required dependencies are build (bundles, libraries etc).
## Bundles
-In Celix a bundle is a library packed in a zip file. Libraries are created using the standard CMake commands (add_library etc).
-The actual bundle is created using the "bundle" command.
-To export files (eg a header file describing the service), a package is created using the "package" command.
+In Celix a bundle is a library packed in a zip file. A bundle is a top level build target and can be added using the following macro:
- add_library(bundleName SHARED sourcefile1 sourcefile2)
- include_directories("${PROJECT_SOURCE_DIR}/includeDir")
- target_link_libraries(bundleName libraryName)
+ bundle(<bundle_name>
+ SOURCES source1 source2 ... sourceN
+ [DIRECTORIES dir1 dir2 ... dirN]
+ [FILES file1 file2 ... fileN])
+
+Include directories and link libraries can be defined using the standard CMake commands.
+The given examples are simplified for basic usage, see the CMake documentation for more information and advanced options.
+
+ include_directories(dir1 dir2 ...)
+ target_link_libraries(<bundle_name> [lib1 [lib2 [...]]])
+
+To export files (eg a header file describing the service), a package is created using the "package" command.
- bundle(bundleName)
- package(bundleName FILES exportedHeader.h)
+ package(<bundle_name>
+ [DIRECTORIES dir1 dir2 ... dirN]
+ [FILES file1 file2 ... fileN])
+
+This can be used to create a package which contains the bundle and additional files (headers etc) needed to use the bundle in different projects.
## Targets
A named target is used to deploy a group of bundles and create a default configuration file.
To create a target the following command is needed:
- deploy("targetName" BUNDLES bundle1 bundle2)
+ deploy(<target_name> BUNDLES bundle1 bundle2 ... bundleN)
-A target is deployed to the build/deploy/{targetName} directory.
+A target is deployed to the build directory where the deploy macro is used. So if in <root>/examples a deploy macro is used, the deployment can be found in <root>/<build_root>/examples.
## Running
@@ -82,3 +131,5 @@ If the library path is set, the launcher
\{build_root\}/launcher/launcher
+Note: for the provided examples a "run.sh" script is generated which takes care of setting up the library path.
+
Modified: incubator/celix/site/trunk/content/celix/documentation/design.mdtext
URL: http://svn.apache.org/viewvc/incubator/celix/site/trunk/content/celix/documentation/design.mdtext?rev=1203179&r1=1203178&r2=1203179&view=diff
==============================================================================
--- incubator/celix/site/trunk/content/celix/documentation/design.mdtext (original)
+++ incubator/celix/site/trunk/content/celix/documentation/design.mdtext Thu Nov 17 13:05:25 2011
@@ -31,12 +31,14 @@ prevent name clashes, function names are
Function in C:
:::c
- SERVICE_REGISTRATION bundleContext_registerService(BUNDLE_CONTEXT context, char * serviceName, void * svcObj, HASHTABLE properties);
+ celix_status_t bundleContext_registerService(BUNDLE_CONTEXT context, char * serviceName, void * svcObj, HASHTABLE properties, SERVICE_REGISTRATION *registration);
Method in Java:
:::java
public ServiceRegistration registerService(String clazz, Object service, Dictionary properties);
+
+More details about the mapping from Java to C can be found at [Mapping](/celix/documentation/mapping.html)
## Imported and Exported Packages
The OSGi Specification uses packages for importing and exporting service interfaces and additional types. As explained
@@ -48,15 +50,5 @@ So it is up to the implementer of a serv
component. The public definitions can be published in a header file.
## Exception Handling
-OSGi uses exceptions to report errors and problems. To be able to handle this in C there are two options:
-
-- Return a status
-
- This requires that each method must return an integer which indicates the state. For returned pointers/values (OUT)
- call-by-reference must be used.
-
-- Use an exception handling interface for C
-
- There are several exception handling solutions available for C. They all introduce a try/catch mechanism. This makes
- it possible to follow the OSGi spec more closely, without letting each function explicitly return a state.
- (for example http://www.nicemice.net/cexcept/)
+OSGi uses exceptions to report errors and problems. Celix return a status from every call. This requires that each method
+must return an integer which indicates the state. For returned pointers/values (OUT) call-by-reference must be used.
\ No newline at end of file
Added: incubator/celix/site/trunk/content/celix/documentation/mapping.mdtext
URL: http://svn.apache.org/viewvc/incubator/celix/site/trunk/content/celix/documentation/mapping.mdtext?rev=1203179&view=auto
==============================================================================
--- incubator/celix/site/trunk/content/celix/documentation/mapping.mdtext (added)
+++ incubator/celix/site/trunk/content/celix/documentation/mapping.mdtext Thu Nov 17 13:05:25 2011
@@ -0,0 +1,65 @@
+Title: Mapping
+Links: documentation/mapping-links.mdtext
+
+To be able to follow the OSGi specification, a standard mapping from C to Java is defined. This mapping
+takes care of how instances, parameters, return values and error codes are used.
+
+## Example
+
+Before going into detail, here is an example of the mapping from a method in Java to a function in C:
+
+ :::c
+ celix_status_t bundleContext_getServiceReferences(BUNDLE_CONTEXT context, const char * serviceName, char * filter, ARRAY_LIST *service_references)
+
+ :::java
+ public ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException
+
+## Template
+
+Using the provided example, the following template can be extracted:
+
+ :::c
+ /**
+ * celix_status_t: return type of the status code
+ *
+ * typeName: name of the object/type this function is part of
+ * functionName: the name of the function
+ *
+ * typeName_t: The actual instance to "invoke" this function on
+ * pool: optional pool on which the output is allocated
+ * parameters: default function parameters
+ * output parameters: the output which the caller can use
+ */
+ celix_status_t typeName_functionName([typeName_t instance, ][apr_pool_t *pool, ][parameters, ][output parameters]);
+
+## Details
+
+To fully explain the mapping, the following items will be detailed:
+
+- Instance parameter
+- Error codes
+- Output parameters
+- Memory pools
+
+### Instances
+When using Java, methods are related to an instance of a type. So for example, when the "getServiceReferences" method is used,
+it is always executed on an instance of BundleContext.
+When using C, functions are not related to any type, and as such, no instance information is available. To make this possible
+in Celix a pointer to the needed instance is always passed as first argument. The only exception are the "create" functions, they
+are used to create a new instance.
+
+Furthermore, the instance typename is used as part of the function name, see "design.html" for more information.
+
+### Error codes
+The OSGi specification uses Java Exceptions for error handling. Even though there are Exceptions-like solutions for C, Celix uses
+the simpler approach. Every method in Celix returns an status code (celix\_status\_t), this code can be used for error handling.
+
+### Output parameters
+Since the return value is always used for the status code output parameters are used to get a possible result from a function.
+Celix uses pass-by-reference for this, the uses has to supply a pointer to the function to get the results. Using this mechanism it is
+also possible to use multiple output parameters.
+Celix always uses the last parameter(s) for output, and the caller has to NULL-initialize the result field.
+
+### Memory pools
+Celix uses APR memory pools for allocation. In the case a functions result has to be allocated to the caller its own pool, the pool has
+to be supplied as an parameter. Note: Not all of Celix' API have been updated to use APR (and memory pools), this is a work in progress.
\ No newline at end of file
Modified: incubator/celix/site/trunk/templates/sidenav.mdtext
URL: http://svn.apache.org/viewvc/incubator/celix/site/trunk/templates/sidenav.mdtext?rev=1203179&r1=1203178&r2=1203179&view=diff
==============================================================================
--- incubator/celix/site/trunk/templates/sidenav.mdtext (original)
+++ incubator/celix/site/trunk/templates/sidenav.mdtext Thu Nov 17 13:05:25 2011
@@ -5,6 +5,7 @@
- [Documentation](/celix/documentation.html)
- [Building and Running](/celix/documentation/buildingandrunning.html)
- [Design](/celix/documentation/design.html)
+ - [Mapping](/celix/documentation/mapping.html)
- [Memory Pools](/celix/documentation/memorypools.html)
- [Examples](/celix/documentation/examples.html)
- [Hello World Example](/celix/examples/helloworld.html)