celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject svn commit: r1623877 - /celix/site/trunk/content/documentation/getting_started.md
Date Tue, 09 Sep 2014 20:04:47 GMT
Author: pnoltes
Date: Tue Sep  9 20:04:47 2014
New Revision: 1623877

URL: http://svn.apache.org/r1623877
Log:
CELIX-144: added first draft of getting started documented. not yet complete or ready for
public view ..

Added:
    celix/site/trunk/content/documentation/getting_started.md

Added: celix/site/trunk/content/documentation/getting_started.md
URL: http://svn.apache.org/viewvc/celix/site/trunk/content/documentation/getting_started.md?rev=1623877&view=auto
==============================================================================
--- celix/site/trunk/content/documentation/getting_started.md (added)
+++ celix/site/trunk/content/documentation/getting_started.md Tue Sep  9 20:04:47 2014
@@ -0,0 +1,208 @@
+##Intro
+This page is intended for first time users of Apache Celix. It should guide you through building
& installing Apache Celix, setting up a new eclipse project, creating your first bundle
and finally running and debugging your bundle directly from eclipse workspace. 
+
+If there are any uncertainties or question, don't hesitate to ask your questions in the [Apache
Celix mailing](https://celix.apache.org/support/mailinglist.html).
+
+##Prerequisite
+Some experience with a command line interface (X terminal) is expected to be able to follow
this guide. 
+
+The following packages (libraries + headers) should be installed on the system:
+
+*	Development Environment
+	*	build-essentials (duh)
+	* 	subversion
+	*	cmake
+* 	Apache Celix Dependencies
+	*	apr
+	*	apr-util
+	*	curl
+	*	jansson
+
+For a debian based systems, the following command could help:
+<pre>
+apt-get install -yq --no-install-recommends \
+	build-essential \
+  	curl \
+  	libapr1-dev \
+  	libaprutil1-dev \
+  	subversion \
+  	libjansson-dev \
+  	libcurl4-openssl-dev \
+  	cmake 
+</pre>
+
+
+##Building & Installing Apache Celix
+To get started we first have to install Apache Celix, to do this you can download a source
release from the [download page](/celix/download.cgi) or checkout the latest version from
svn. For this getting started guide the latest trunk version is assumed. Then choose a workspace
dir to work in , set the location to the environment variable WS and follow the following
guide:
+
+	#Create a new workspace to work in
+	
+	#e.g 
+	#mkdir ${HOME}/workspace
+	#export WS=${HOME}/workspace
+	
+	cd ${WS}
+	
+	#checkout Apache Celix
+	svn co https://svn.apache.org/repos/asf/celix/trunk/ celix-src
+	
+	#create a build directory to build Celix in (out of source build)
+	mkdir celix-build
+	
+	#build Apache Celix with the default settings
+	#Note1 	if you want to change the install path add -DCMAKE_INSTALL_PREFIX=/opt/local
+	#Note2 	If you want to be able to edit all the available options, 
+	#		use the ccmake (ncursus) instead of cmake. 
+	#TODO check which bundles or on default. probably not shell & shell_tui...
+	cd celix-build
+	cmake ../celix-src
+	make all 
+	
+	#install the framework and the bundles
+	make install-all
+	
+##Installing Eclipse CDT
+Download the latest eclipse CDT at [www.eclipse.org](www.eclipse.org) and install it on your
system. For more information on how the install eclipse on your system consult the eclipse
documentation. In this getting started guide the luna version of eclipse was used ([linux](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-linux-gtk-x86_64.tar.gz)
[mac](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-macosx-cocoa-x86_64.tar.gz)).
+
+
+	
+##Apache Celix Bundle project
+Create a new project dir to work in:
+	
+	mkdir ${WS}/myproject
+	cd ${WS}/myproject
+	
+For Apache Celix and an Apache Celix Bundle project CMake is used as build system. CMake
is a cross platform build system which is uses a declarative way of describing build. This
getting started will only roughly explain how CMake works, for a more detail introduction
on CMake consult the CMake documentation. 
+
+The Apache Celix installed additional cmake files to extend the default functionality of
CMake to support the creating and testing of OSGi bundles.
+
+CMake expects a CMakeLists.txt file in the root of a project directory. To get started add
an initial CMakeLists.txt file to the project root with your favourite editor:
+	
+	#${WS}/myproject/CMakeLists.txt
+	
+	#PART1
+	cmake_minimum_required(VERSION 2.8)
+	project(myproject C)
+	cmake_policy(SET CMP0012 NEW)
+	
+	#PART2
+	set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/share/celix/cmake/modules")
+	find_package(CELIX REQUIRED)
+	include_directories(${CELIX_INCLUDE_DIRS})
+
+	#PART3
+	add_subdirectory(bundles/hello_world)
+		
+	
+Part 1 of the CMakeLists.txt file declares an minimum cmake required, a project name, the
source to be expected in the project (C) and that the new CMP0012 policy should be used instead
of the old one (in short it corrects wrong handling of numbers & booleans in CMake if
statements).
+
+Part 2 extends the CMake module path to include Apache Celix CMake modules, uses the find_package
to find the Apache Celix libraries/binaries and extends CMake with Apache Celix specific CMake
functions and declares that the Apache Celix header directory should be included when building.
+
+Part 3 will look in the specified subdirectory for another CMakeLists.txt and continue from
there. 
+
+
+	#Create directory structure for the hello_world bundles
+	cd ${WS}/myproject
+	mkdir -p bundles/hello_world/private/src
+
+
+TODO add CMakeLists.txt per bundle and explain 
+
+	
+	#${WS}/myproject/bundles/hello_world/CMakeLists.txt
+	
+	set(BUNDLE_SYMBOLICNAME "hello_world")
+	set(BUNDLE_VERSION "1.0.0")
+	set(BUNDLE_NAME "Say Hello")
+
+	
+	bundle(hello_world
+		SOURCES(private/src/activator)
+	)	
+	
+
+TODO add activator.c and explain (also why create, start, stop & destroy. instead of
just start/stop)
+
+	//${WS}/myproject/bundles/hello_world/private/src/activator.c
+	#include <stdlib.h>
+	#include <stdio.h>
+	
+	#include "bundle_activator.h"
+	#include "bundle_context.h"
+
+
+	struct userData {
+    	    char * word;
+	};
+
+	celix_status_t bundleActivator_create(bundle_context_pt context, void **userData) {
+    	celix_status_t status = CELIX_SUCCESS;
+        *userData = malloc(sizeof(struct userData));
+    	if (userData != NULL) {
+                ((struct userData *)(*userData))->word = "World";
+        } else {
+                status = CELIX_START_ERROR;
+        }
+        return CELIX_SUCCESS;
+	}
+
+	celix_status_t bundleActivator_start(void * userData, bundle_context_pt context) {
+        struct userData * data = (struct userData *) userData;
+        printf("Hello %s\n", data->word);
+        return CELIX_SUCCESS;
+	}
+
+	celix_status_t bundleActivator_stop(void * userData, bundle_context_pt context) {
+        struct userData * data = (struct userData *) userData;
+        printf("Goodbye %s\n", data->word);
+        return CELIX_SUCCESS;
+	}       
+        
+	celix_status_t bundleActivator_destroy(void * userData, bundle_context_pt context) {
+    	free(userData);
+        return CELIX_SUCCESS;
+	}
+	
+###Building 
+TODO explain out of source building 
+
+
+###Running 
+
+TODO add deploy (with shell, shell_tui) and explain using full path + extension difference
with only a names
+
+	#${WS}/myproject/bundles/hello_world/deploy.cmake
+	deploy("myproject" BUNDLES 
+		${CELIX_BUNDLES_DIR}/shell.zip 
+		${CELIX_BUNDLES_DIR}/shell_tui.zip
+		hello_world
+	)
+	
+TODO explain add deploy_targets() to root CMakeLists.txt 
+
+TODO explain run.sh
+
+##Apache Celix Bundle Project in Eclipse
+TODO explain:
+
+ - eclipse setup (cmake -G)
+ - project structure (e.g where are my sources)
+ - building with make from eclipse
+ - running/debugging from eclipse
+ 
+ 
+
+
+##The Next Steps
+explain:
+
+ - service registration/lookup
+ - service tracker
+ - bundle with private & public libs
+ - bundle reusing existing libs as private and/or public
+ 
+ 
+
+
+	
+	
\ No newline at end of file



Mime
View raw message