Add HowTo Debug documentation

Signed-off-by: Alexander Wenzel <Alexander.AW.Wenzel@bmw.de>

14 files changed, 232 insertions, 0 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index b1b068d..d670614 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -42,6 +42,7 @@ if(WITH_DOC)
   		COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt-system.conf.5.html ${CMAKE_SOURCE_DIR}/doc/dlt-system.conf.5.txt 
   		COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_book.html ${CMAKE_SOURCE_DIR}/doc/dlt_book.txt
   		COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_extended_network_trace.html ${CMAKE_SOURCE_DIR}/doc/dlt_extended_network_trace.txt  
+  		COMMAND asciidoc -a TOC1 -o ${CMAKE_BINARY_DIR}/doc/manuals/dlt_howto_debug.html ${CMAKE_SOURCE_DIR}/doc/dlt_howto_debug.txt  
   		WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc
 	)
 
diff --git a/doc/dlt_howto_debug.txt b/doc/dlt_howto_debug.txt
new file mode 100644
index 0000000..7d0d8e6
--- /dev/null
+++ b/doc/dlt_howto_debug.txt
@@ -0,0 +1,231 @@
+How To - Debug DLT Daemon
+=========================
+Lassi Marttala <Lassi.LM.Marttala@partner.bmw.de> 
+0.0.1, 2013/03/18: Initial version
+
+image::images/genivi_chrome_1_transparent.png[width=128]
+
+== How to set up Eclipse, tools and project for debugging dlt-daemon
+This document describes how to set up an Eclipse development environment with minimal tool set and set up a project to compile and debug dlt-daemon.
+
+This document was written using KUbuntu 12.10 desktop. Any dpkg based Linux distribution should work equally well.
+
+The purpose is to provide the user with a clean working environment, where:
+
+* Build directory can be completely separated from source directory
+* There is no need to create need project files every time a user wishes to clean their working tree
+* dlt-daemon, library and all tools can be compiled from Eclipse UI without command line
+* Debugger can be easily launched for any of the binaries in dlt-daemon project
+
+Anything in 
+----
+code
+----
+in this document is considered a command line command. Please use your preferred terminal emulator.
+
+=== Prerequisites
+Instructions on how to install needed base tools for compilation.
+
+==== Linux Desktop
+You can use any Linux Desktop environment that provides the needed packages for compilation of dlt-daemon and for running Eclipse. This document assumes you already have a dpkg-based Linux Desktop running, such as Debian, Ubuntu, Kubuntu or Xubuntu.
+
+==== C/C++ Compilers and Linker
+----
+sudo apt-get install gcc g++
+----
+This will install GNU C and C++ compilers, the linker and basic libraries for compilation.
+
+Purpose: Needed for compilation of C and C++ programs.
+
+==== Zlib-devel
+----
+sudo apt-get install zlib1g-dev
+----
+This will install the zlib compression library and development headers.
+
+Purpose: Needed for compiling dlt-system with file compression support.
+
+==== CMake
+----
+sudo apt-get install cmake
+----
+This will install cmake and any needed dependencies.
+
+Purpose: DLT utilizes cmake for build management.
+
+==== Git
+----
+sudo apt-get install git
+----
+This will install git version control tool. 
+
+Purpose: dlt-daemon version control is managed using git. Git is needed to clone the source code repository.
+
+==== Java
+----
+sudo apt-get install default-jdk
+----
+This will install the default Java Development Kit for you Linux Distribution. For Kubuntu this is OpenJDK 7.
+
+Purpose: Eclipse needs Java to run. JDK is not strictly needed. You might be able to substitute with _*default-jre*_. This is untested, thought.
+
+=== Install Eclipse
+Download _"Eclipse IDE for C/C++ Developers"_  from http://www.eclipse.org/.
+
+At the time of writing, _"Eclipse CDT Juno"_ was the latest version.
+
+Extract the package to a directory. You should now have directory named "eclipse", which contains a binary called "eclipse". You should be able to start Eclipse by double clicking on the binary. In case there are problems, make sure you have proper permissions for the directory, sub-directories and that the binary has "executable"-flag set.
+----
+chmod u+x eclipse 
+----
+if required.
+
+On first start-up, Eclipse will ask for a workspace directory. Select a directory, under which you want to keep your Eclipse project directories.
+
+image:images/eclipse-workspace.png[]
+
+After the startup, you are greeted with a "Welcome"-screen. Dismiss the window and you should be now in an empty C/C++ development perspective:
+image:images/eclipse-cpp-perspective.png[]
+
+You have a working Eclipse now. Next we need to get the source code for dlt-daemon.
+
+=== Acquire dlt-daemon Source
+Create a directory under which you want to store your source code. Then change to it.
+----
+mkdir ~/git
+cd ~/git
+----
+
+Clone the dlt-daemon repository, from the OSS server:
+----
+git clone http://git.projects.genivi.org/dlt-daemon.git
+----
+
+Test that the current software is compilable.
+----
+cd dlt-daemon
+mkdir build
+cd build
+cmake ..
+make
+----
+
+If these commands succeeded, you can continue. If there were errors, please remedy them before proceeding.
+
+Clean up the git directory. The following command will delete all files that are not part of the repository. Please use caution.
+----
+git clean -fdx 
+----
+
+Now you have a working source directory. We can proceed to setting up the Eclipse project.
+
+Your source directory will be called DLT_GIT_DIR from now on in this document.
+
+=== Eclipse Project
+Now, return to your Eclipse. You should have the default C/C++ perspective open.
+
+Click on "File -> New -> C Project"
+
+A new dialogue will open:
+
+image:images/eclipse-create-c-project.png[]
+
+Name the project _"dlt-daemon"_.
+
+Select: _"Makefile project -> Empty Project"_ from the left and _"-- Other Toolchain --"_ from the right. 
+
+Make a note of the project location. This will be know *DLT_PROJECT_DIR* from now on in this document.
+
+Click _"Next"._
+
+Click _"Advanced settings..."_ in the following dialog.
+
+image:images/eclipse-project-props-1.png[]
+
+In the _"C/C++ Build"_-page, set build directory to *$\{workspace_loc:/dlt-daemon\}/build
+
+image:images/eclipse-project-props-3.png[]
+
+In the _"C/C++ Build -> Settings"_-page, _"Binary Parsers"_-tab *Check* _"Elf Parser"_
+
+image:images/eclipse-project-props-4.png[]
+
+In the _"C/C++ General -> Preprocessor Includes"_-page, _"Providers"_-tab, *check* both _"CDT GCC"_-options.
+
+*Click* "OK".
+
+*Click* "Finish"
+
+We still need to define a new custom tool, to generate the needed makefiles, from cmake-files:
+
+From the main menu of Eclipse, *click* _"Run -> External Tools External Tools Configurations."_.
+
+In the new window, *click* in the top-left small icon _"New Launch Configuration"_.
+
+image:images/eclipse-external-tools-props-1.png[]
+
+Name the new tool "cmake".
+
+Point it to the cmake binary.
+
+Working directory should be DLT_PROJECT_DIR/build
+
+Arguments should include "-DCMAKE_BUILD_TYPE=DEBUG" and final argument should be your DLT_GIT_DIR
+
+image:images/eclipse-external-tools-props-2.png[]
+
+In the _"Build"_-tab, *uncheck* _"Build before launch"_
+
+*Click* _"Apply"_ +
+*Click* _"Close"_
+
+At this point, make sure that DLT_PROJECT_DIR/build, exists. If it doesn', create an empty directory. +
+Refresh the project by selecting the project from the left and hit "F5".
+
+Let's test it!
+
+Click _"Run -> External Tools -> cmake"_. cmake should now configure the project and finish with:
+
+_"Build files have been written to: DLT_PROJECT_DIR/build"_
+
+Click _"Project -> Build All"_. The normal "make" progress should commence and you should be left with build project.
+
+Click _"Run -> Debug"_. You should be greeted with dialog like this:
+
+image:images/eclipse-debug-which.png[]
+
+Select _"dlt-daemon"_ from the list and *click* _"OK"_.
+
+Select _"gdb/mi"_ from the following dialog, and *click* _"OK"_.
+
+Click _"Yes"_ when Eclipse asks if you want to switch to the debug perspective.
+
+image:images/eclipse-debug-perspective.png[]
+
+*Congratulations! You are now in debugger.*
+
+*Click* the red square to terminate the application, and click the _"C/C++ Perspective"_ from the top right.
+
+There's one more thing we need to do, to make your life easier.
+
+*Right click* on the _"dlt-daemon"_-project and select _"Import"_ .
+
+In the following dialog, select _"General -> File system"_ and *click* _"Next"_
+
+image:images/eclipse-import-links.png[]
+
+*Click* _"Browse"_ and navigate to your DLT_GIT_DIR. 
+
+*Check* _"dlt-daemon"_ root directory. 
+
+*Click* _"Advanced"_ and *Check* _"Create links"_ and _"Create virtual folders"_. 
+
+*Click* _"Filter types..."_ and only check the file types you want to see _"*.c, *.h"_ is sufficient for most cases.
+
+*Click* _"Finish"_
+
+You now have the source code also easily accessible from the project tree:
+
+image:images/eclipse-cpp-perspective-2.png[]
+
+*All done!*
\ No newline at end of file
diff --git a/doc/images/eclipse-cpp-perspective-2.png b/doc/images/eclipse-cpp-perspective-2.png
new file mode 100644
index 0000000..6e445c2
--- /dev/null
+++ b/doc/images/eclipse-cpp-perspective-2.png
diff --git a/doc/images/eclipse-cpp-perspective.png b/doc/images/eclipse-cpp-perspective.png
new file mode 100644
index 0000000..c1f936e
--- /dev/null
+++ b/doc/images/eclipse-cpp-perspective.png
diff --git a/doc/images/eclipse-create-c-project.png b/doc/images/eclipse-create-c-project.png
new file mode 100644
index 0000000..947321b
--- /dev/null
+++ b/doc/images/eclipse-create-c-project.png
diff --git a/doc/images/eclipse-debug-perspective.png b/doc/images/eclipse-debug-perspective.png
new file mode 100644
index 0000000..a408aa3
--- /dev/null
+++ b/doc/images/eclipse-debug-perspective.png
diff --git a/doc/images/eclipse-debug-which.png b/doc/images/eclipse-debug-which.png
new file mode 100644
index 0000000..8acb3f5
--- /dev/null
+++ b/doc/images/eclipse-debug-which.png
diff --git a/doc/images/eclipse-external-tools-props-1.png b/doc/images/eclipse-external-tools-props-1.png
new file mode 100644
index 0000000..7bd5b37
--- /dev/null
+++ b/doc/images/eclipse-external-tools-props-1.png
diff --git a/doc/images/eclipse-external-tools-props-2.png b/doc/images/eclipse-external-tools-props-2.png
new file mode 100644
index 0000000..aa3d7c5
--- /dev/null
+++ b/doc/images/eclipse-external-tools-props-2.png
diff --git a/doc/images/eclipse-import-links.png b/doc/images/eclipse-import-links.png
new file mode 100755
index 0000000..efcfc1a
--- /dev/null
+++ b/doc/images/eclipse-import-links.png
diff --git a/doc/images/eclipse-project-props-1.png b/doc/images/eclipse-project-props-1.png
new file mode 100644
index 0000000..fb1b77a
--- /dev/null
+++ b/doc/images/eclipse-project-props-1.png
diff --git a/doc/images/eclipse-project-props-3.png b/doc/images/eclipse-project-props-3.png
new file mode 100644
index 0000000..3a12626
--- /dev/null
+++ b/doc/images/eclipse-project-props-3.png
diff --git a/doc/images/eclipse-project-props-4.png b/doc/images/eclipse-project-props-4.png
new file mode 100644
index 0000000..51fece4
--- /dev/null
+++ b/doc/images/eclipse-project-props-4.png
diff --git a/doc/images/eclipse-workspace.png b/doc/images/eclipse-workspace.png
new file mode 100644
index 0000000..ae9d206
--- /dev/null
+++ b/doc/images/eclipse-workspace.png