celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject svn commit: r1624106 - /celix/site/trunk/content/documentation/getting_started.md
Date Wed, 10 Sep 2014 19:47:13 GMT
Author: pnoltes
Date: Wed Sep 10 19:47:13 2014
New Revision: 1624106

URL: http://svn.apache.org/r1624106
Log:
CELIX-144: Updated getting started documentation up to creating the hello world bundle activator

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

Modified: celix/site/trunk/content/documentation/getting_started.md
URL: http://svn.apache.org/viewvc/celix/site/trunk/content/documentation/getting_started.md?rev=1624106&r1=1624105&r2=1624106&view=diff
==============================================================================
--- celix/site/trunk/content/documentation/getting_started.md (original)
+++ celix/site/trunk/content/documentation/getting_started.md Wed Sep 10 19:47:13 2014
@@ -1,15 +1,15 @@
 ##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. 
+This page is intended for first time users of Apache Celix. It should guide you through building
& installing Apache Celix, setting up a new project, creating your first bundle, setting
up the project for use with Eclipse project 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. 
+Some experience with a command line interface (xterm) is expected to be able to follow this
guide. 
 
-The following packages (libraries + headers) should be installed on the system:
+The following packages (libraries + headers) should be installed on your system:
 
 *	Development Environment
-	*	build-essentials (duh)
+	*	build-essentials 
 	* 	subversion
 	*	cmake
 * 	Apache Celix Dependencies
@@ -18,7 +18,7 @@ The following packages (libraries + head
 	*	curl
 	*	jansson
 
-For a debian based systems, the following command could help:
+For a debian based systems, the following should work:
 <pre>
 apt-get install -yq --no-install-recommends \
 	build-essential \
@@ -33,11 +33,9 @@ apt-get install -yq --no-install-recomme
 
 
 ##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:
+To get started you 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. Also choose a workspace
diretory to work in and the environment variable WS to this location. After that execute the
following commands (ignore emtpy lines and lines starting with #):
 
-	#Create a new workspace to work in
-	
-	#e.g 
+	#Create a new workspace to work in, e.g:
 	#mkdir ${HOME}/workspace
 	#export WS=${HOME}/workspace
 	
@@ -52,7 +50,7 @@ To get started we first have to install 
 	#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. 
+	#		use the ccmake command instead of cmake, this will will present a ncursus based ui
 	#TODO check which bundles or on default. probably not shell & shell_tui...
 	cd celix-build
 	cmake ../celix-src
@@ -62,66 +60,82 @@ To get started we first have to install 
 	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)).
+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. For 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:
+Now that Apache Celix and Eclipse is installed, we are ready to create a new Apache Celix
Bundle project. In this project cmake will be create a singe hello world bundle with a deployment
configurtion for testing the bundle.
+
+For Apache Celix and an Apache Celix Bundle project CMake is used as build system. CMake
is a cross platform build. This getting started guide will only shows a small part of CMake,
for a more detailed introduction on CMake consult the [CMake documentation](http://www.cmake.org/documentation).

+
+The installation of Apache Celix, also added additional CMake files to extend the default
functionality of CMake in order to support the creating and testing of Apache Celix Bundles.

+
+To setup of the project, first 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:
+Then create a CMakeLists.txt file, the Makefile variant of CMake, in project root directory:
 	
 	#${WS}/myproject/CMakeLists.txt
 	
-	#PART1
+	#PART 1
 	cmake_minimum_required(VERSION 2.8)
 	project(myproject C)
-	cmake_policy(SET CMP0012 NEW)
 	
-	#PART2
+	#PART 2
 	set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/share/celix/cmake/modules")
 	find_package(CELIX REQUIRED)
 	include_directories(${CELIX_INCLUDE_DIRS})
 
-	#PART3
+	#PART 3
 	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).
+This CMakeLists.txt file, sets up the following:
 
-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 1 
+	* The minimum cmake version required. 
+	* The project name
+	* The type of source files to expect, in this case C.
+* Part 2
+ 	* The CMake module path to be used (e.g. where CMake find_package module can be found)
+	* That Celix package should be searched, configured and that the Celix package is required.

+	* That for all build targets in this CMakeLists.txt file or any sub directory CMakeLists.txt
files the Apache Celix headers directory should be included.
+* Part 3
+	* The CMakelists.txt file in the subdirectory bundles/hello_world should also be processed.
+	
 
-Part 3 will look in the specified subdirectory for another CMakeLists.txt and continue from
there. 
+It is a good pratice to create a seperate CMakeLists.txt file for every bundle you want to
build. For the hello_world bundle a CMakeLists.txt file should be created in the bundles/hello_world
sub directory.
 
+Create the sub directory:
 
 	#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 
-
+And add the following CMakeList.txt file:
 	
 	#${WS}/myproject/bundles/hello_world/CMakeLists.txt
 	
-	set(BUNDLE_SYMBOLICNAME "hello_world")
+	set(BUNDLE_SYMBOLICNAME "com.example.hello_world")
 	set(BUNDLE_VERSION "1.0.0")
-	set(BUNDLE_NAME "Say Hello")
+	set(BUNDLE_NAME "hello_world")
 
 	
 	bundle(hello_world
 		SOURCES(private/src/activator)
 	)	
 	
+This CMakeLists.txt file declares that a bundle should be build based on the build result
(shared library) of the declared sources (in this caese the private/src/activator.c source)
in the bundle marcro (The bundle marcro is an Apache Celix specific CMake extension). Also
the version, symbolicname (unique name) and name to be used when creating the bundle is declared.
+
+The last part for the hello_world bundle is the bundle activator source. The bundle activator
is the entry point for an Apache Celix Bundle. Think of the bundle activator as the main function
for an bundle, whith the difference that is not only control the start of a bundle, but also
the stoppoing of a bundle. 
+
+Creating/starting and stopping/destroying is seperated in bunlde activator. This is done
to make a clear seperation between the instantion/creation of a structure (e.g. object) and
exposure of that instantation to other parts of the program. The same, but then reserve hold
for seperating stopping and destroying a bundle. For more detailed information why this is
important, please read the [Java theory and practice: Safe construction techniques](https://www.ibm.com/developerworks/library/j-jtp0618/)
article (altough this is oriented around Java, the principles applies any form of instantation
and exposure).
 
-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>



Mime
View raw message