incubator-celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From abroekh...@apache.org
Subject 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
Date Thu, 17 Nov 2011 13:05:26 GMT
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)



Mime
View raw message