You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@celix.apache.org by pn...@apache.org on 2016/01/07 20:35:57 UTC
[2/2] celix git commit: CELIX-335: Add and updates building and
getting started documentation from the celix site trunk
CELIX-335: Add and updates building and getting started documentation from the celix site trunk
Project: http://git-wip-us.apache.org/repos/asf/celix/repo
Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/0dce0f2e
Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/0dce0f2e
Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/0dce0f2e
Branch: refs/heads/feature/CELIX-335_deploy_refactoring
Commit: 0dce0f2e622633734f1674a830711ef319d0f02d
Parents: 8101cd9
Author: Pepijn Noltes <pe...@gmail.com>
Authored: Thu Jan 7 20:35:13 2016 +0100
Committer: Pepijn Noltes <pe...@gmail.com>
Committed: Thu Jan 7 20:35:13 2016 +0100
----------------------------------------------------------------------
CMakeLists.txt | 2 +-
documents/building/building_and_install.md | 104 +++++++++
documents/getting_started/getting_started.md | 214 +++++++++++++++++++
.../getting_started/getting_started_img1.png | Bin 0 -> 46250 bytes
.../getting_started/getting_started_img2.png | Bin 0 -> 55615 bytes
.../getting_started/getting_started_img3.png | Bin 0 -> 127686 bytes
documents/memory_pools.png | Bin 74273 -> 0 bytes
7 files changed, 319 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c3494fa..d32f96f 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -15,7 +15,7 @@
# specific language governing permissions and limitations
# under the License.
-cmake_minimum_required (VERSION 2.6)
+cmake_minimum_required (VERSION 3.0)
project (Celix C CXX)
cmake_policy(SET CMP0012 NEW)
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/building/building_and_install.md
----------------------------------------------------------------------
diff --git a/documents/building/building_and_install.md b/documents/building/building_and_install.md
new file mode 100644
index 0000000..1e05176
--- /dev/null
+++ b/documents/building/building_and_install.md
@@ -0,0 +1,104 @@
+#Apache Celix - Building and Installing
+
+#Preparing
+The following packages (libraries + headers) should be installed on your system:
+
+* Development Environment
+ * build-essentials
+ * git
+ * java (for packaging bundles)
+ * cmake (3 or higher)
+* Apache Celix Dependencies
+ * curl
+ * jansson
+
+For a debian based systems, the following should work:
+
+<pre>
+sudo apt-get install -yq --no-install-recommends \
+ build-essential \
+ ninja \
+ curl \
+ git \
+ libjansson-dev \
+ libcurl4-openssl-dev \
+ java \
+ cmake
+</pre>
+
+For Fedora based systems (dnf), the following should work:
+<pre>
+sudo dnf install \
+ cmake \
+ ninja-build \
+ make \
+ git \
+ java \
+ libcurl-devel \
+ jansson-devel
+</pre>
+
+##Download the Apache Celix sources
+To get started you first have to download the Apache Celix sources. This can be done by cloning the Apache Celix git repository:
+
+```bash
+#Create a new workspace to work in, e.g:
+mkdir ${HOME}/workspace
+export WS=${HOME}/workspace
+cd ${WS}
+
+#clone the repro
+git clone --single-branch --branch develop https://github.com/apache/celix.git
+```
+
+##Building Apache Celix
+Apache Celix uses [CMake](https://cmake.org) as build system. CMake can generate (among others) makefiles or ninja build files.
+using ninja build files will result in a faster build.
+
+###Building using CMake and makefiles:
+```bash
+cd ${WS}/celix
+mkdir build
+cd build
+cmake ..
+make
+```
+
+###Building using CMake and Ninja
+```bash
+cd ${WS}/celix
+mkdir build
+cd build
+cmake -G Ninja ..
+ninja
+```
+
+##Editing Build options
+With use of CMake Apache Celix makes it possible to edit build options. This enabled users to configure a install location and selecting additional bundles.
+To edit the options use ccmake or cmake-gui. For cmake-gui an additional package install can be neccesary (Fedora: `dnf install cmake-gui`).
+
+```bash
+cd ${WS}/celix/build
+ccmake .
+#Edit options, e.g. enable BUILD_REMOTE_SHELL to build the remote (telnet) shell
+#Edit the CMAKE_INSTALL_PREFIX config to set the install location
+```
+
+For this guide we assume the CMAKE_INSTALL_PREFIX is `/usr/local`.
+
+##Installing Apache Celix
+
+```bash
+cd ${WS}/celix/build
+make
+sudo make install
+```
+
+##Running Apache Celix
+
+If Apache Celix is succesfully installed running
+ celix
+should give the following output:
+"Error: invalid or non-existing configuration file: 'config.properties'.No such file or directory"
+
+For more info how to build your own projects and/or running the Apache Celix examples see [Getting Started](getting_started/getting_started.md)
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/getting_started/getting_started.md
----------------------------------------------------------------------
diff --git a/documents/getting_started/getting_started.md b/documents/getting_started/getting_started.md
new file mode 100644
index 0000000..b99cae9
--- /dev/null
+++ b/documents/getting_started/getting_started.md
@@ -0,0 +1,214 @@
+#Apache Celix - Getting Started
+
+##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 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 (xterm) is expected to be able to follow this guide.
+
+##Building and Installing
+For Apache Celix see [Building And Installing](../building/building_and_installing.md)
+
+##Installing Eclipse CDT
+Download the latest eclipse CDT at [http://www.eclipse.org](http://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
+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 configuration for testing the bundle.
+
+To setup of the project, first create a new project dir to work in:
+
+```bash
+#Create a new workspace to work in, e.g:
+mkdir ${HOME}/workspace
+export WS=${HOME}/workspace
+
+mkdir ${WS}/myproject
+cd ${WS}/myproject
+```
+Then create a CMakeLists.txt file - the makefile variant of CMake -in project root directory:
+
+```cmake
+#${WS}/myproject/CMakeLists.txt
+
+#PART 1
+cmake_minimum_required(VERSION 3)
+project(myproject C)
+
+#PART 2
+ #Note. If celix is not installed in /usr/local dir, change the location accordingly.
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/local/share/celix/cmake/modules")
+find_package(CELIX REQUIRED)
+include_directories(${CELIX_INCLUDE_DIRS})
+
+#PART 3
+add_subdirectory(bundles/hello_world)
+```
+
+This CMakeLists.txt file, sets up the following:
+
+* 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.
+
+
+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:
+
+```cmake
+#Create directory structure for the hello_world bundles
+cd ${WS}/myproject
+mkdir -p bundles/hello_world/private/src
+```
+
+
+And add the following CMakeList.txt file:
+
+```cmake
+#${WS}/myproject/bundles/hello_world/CMakeLists.txt
+
+add_bundle(hello_world
+ VERSION 1.0.0
+ 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). The add_bundle function is an Apache Celix specific CMake extension.
+
+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 a bundle, whith the difference that is does not only control the start of a bundle, but also the stopping of a bundle.
+
+Creating/starting and stopping/destroying is seperated in bundle 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.
+
+```C
+//${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
+One of the highly recommended features of CMake is the ability to do out of source builds, the benefit is that all of the build results will go in a seperate directory without cluttering the (source) project. To create the build directory and build the project execute the following commands:
+
+```bash
+cd ${WS}
+mkdir myproject/build
+cd myproject/build
+cmake ..
+make all
+#Or
+#cmake -G Ninja ..
+#ninja
+```
+
+Hopefully you will some some build results scrolling over the screen and actual build results in the build directory. There should be a hello_world.zip in the bundles/hello_world directory, this the actual bundle. But a bundle on its own has no real value, so lets setup a deployment and run the Apache Celix framwork with this bundle.
+
+
+###Running
+
+To create a deployment for the hello_world bundle two things are needed:
+
+1. Add a `add_deploy` statement in the `bundles/hello_world/CMakeLists.txt` file declaring what to deploy and under which name.
+
+```cmake
+${WS}/myproject/bundles/hello_world/CMakeLists.txt
+deploy("myproject-deploy" BUNDLES
+ ${CELIX_BUNDLES_DIR}/shell.zip
+ ${CELIX_BUNDLES_DIR}/shell_tui.zip
+ hello_world
+)
+```
+
+Rerun make again form the build project. the make files genereated by CMake will ensure cmake is runned again to update the actual make files.
+
+```bash
+cd ${WS}/myproject-build
+make
+#or
+#ninja
+```
+
+Now a deploy directory myproject should be availabe 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.
+
+ cd ${WS}/myproject-build/deploy/myproject-deploy
+ sh run.sh
+
+The hello_world bundle should be started with the famous "Hello World" text printed. The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for printed the installed bundles, printing all known shell command, printing help of a specific command and stopping a specific bundle (note that bundle 0 is the framework):
+
+```
+lb
+help
+help inspect
+stop 0
+```
+
+##Apache Celix Bundle Project in Eclipse
+
+A nice feature of CMake is the ability to generate Eclipse project files, with this feature bundles can also be developed with use of Eclipse. This should help speed up the development process.
+To get started change directory to the build directory and generate a eclipse project file.
+
+ cd ${WS}/myproject/build
+ cmake -G "Eclipse CDT4 - Unix Makefiles" .
+
+Startup the Eclipse EDI and a chose the `${WS}`
+
+
+
+Import the project with existing project.
+
+
+
+To build the project, use Project->Build All. To run or debug from Eclipse navigate to the myproject deploy directory and right click on the 'myproject.launch' file. And select Run As or Debug As to run or debug the bundle.
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/getting_started/getting_started_img1.png
----------------------------------------------------------------------
diff --git a/documents/getting_started/getting_started_img1.png b/documents/getting_started/getting_started_img1.png
new file mode 100644
index 0000000..d3d9a92
Binary files /dev/null and b/documents/getting_started/getting_started_img1.png differ
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/getting_started/getting_started_img2.png
----------------------------------------------------------------------
diff --git a/documents/getting_started/getting_started_img2.png b/documents/getting_started/getting_started_img2.png
new file mode 100644
index 0000000..76cc3ad
Binary files /dev/null and b/documents/getting_started/getting_started_img2.png differ
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/getting_started/getting_started_img3.png
----------------------------------------------------------------------
diff --git a/documents/getting_started/getting_started_img3.png b/documents/getting_started/getting_started_img3.png
new file mode 100644
index 0000000..3d4cf42
Binary files /dev/null and b/documents/getting_started/getting_started_img3.png differ
http://git-wip-us.apache.org/repos/asf/celix/blob/0dce0f2e/documents/memory_pools.png
----------------------------------------------------------------------
diff --git a/documents/memory_pools.png b/documents/memory_pools.png
deleted file mode 100644
index f005d1d..0000000
Binary files a/documents/memory_pools.png and /dev/null differ