fixes for asciidoc

01-basic/A-hello-cmake/README.adoc

@@ -0,0 +1,107 @@
+:toc:
+:toc-placement!:
+
+toc::[]
+
+[[hello-cmake]]
+Hello CMake
+-----------
+
+Shows a very basic hello world example.
+
+[[concepts]]
+Concepts
+~~~~~~~~
+
+[[minimum-cmake-version]]
+Minimum CMake version
+^^^^^^^^^^^^^^^^^^^^^
+
+[source,cmake]
+
+When creating a project using CMake, you can specify the minimum version
+of CMake that is supported.
+
+----
+cmake_minimum_required(VERSION 2.6)
+----
+
+[[projects]]
+Projects
+^^^^^^^^
+
+A CMake build can include a project name to make referencing certain
+variables easier when using multiple projects.
+
+[source,cmake]
+----
+project (hello_cmake)
+----
+
+[[creating-an-executable]]
+Creating an Executable
+^^^^^^^^^^^^^^^^^^^^^^
+
+The +add_executable()+ command specifies that an executable should be
+build from the specified source files, in this example main.cpp. The
+first argument to the +add_executable()+ function is the name of the
+executable to be built, and the second argument is the list of source files to compile.
+
+[source,cmake]
+----
+add_executable(hello_cmake main.cpp)
+----
+
+
+[NOTE]
+====
+A shorthand that some people use is to have the project name and
+executable name the same. This allows you to specify the CMakeLists.txt
+as follows,
+
+[source,cmake]
+----
+cmake_minimum_required(VERSION 2.6)
+project (hello_cmake)
+add_executable(${PROJECT_NAME} main.cpp)
+----
+
+In this example, the +project()+ function, will create a variable
++${PROJECT_NAME}+ with the value hello_cmake. This can then be passed to
+the +add_executable()+ function to output a 'hello_cmake' executable.
+====
+
+[[building-the-example]]
+Building the Example
+~~~~~~~~~~~~~~~~~~~~
+
+[source,bash]
+----
+$ mkdir build
+
+$ cd build
+
+$ cmake ..
+-- The C compiler identification is GNU 4.8.4
+-- The CXX compiler identification is GNU 4.8.4
+-- Check for working C compiler: /usr/bin/cc
+-- Check for working C compiler: /usr/bin/cc -- works
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Check for working CXX compiler: /usr/bin/c++
+-- Check for working CXX compiler: /usr/bin/c++ -- works
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /workspace/cmake-examples/01-basic/hello_cmake/build
+
+$ make
+Scanning dependencies of target hello_cmake
+[100%] Building CXX object CMakeFiles/hello_cmake.dir/hello_cmake.cpp.o
+Linking CXX executable hello_cmake
+[100%] Built target hello_cmake
+
+$ ./hello_cmake
+Hello CMake!
+----

01-basic/B-hello-headers/README.adoc

@@ -0,0 +1,168 @@
+:toc:
+:toc-placement!:
+
+toc::[]
+
+
+[[hello-cmake]]
+Hello CMake
+-----------
+
+Shows a hello world example, which uses a different folder for source and include
+files.
+
+[[concepts]]
+Concepts
+~~~~~~~~
+
+[[directory-paths]]
+Directory Paths
+^^^^^^^^^^^^^^^
+
+CMake syntax specifies a number of https://cmake.org/Wiki/CMake_Useful_Variables[variables]
+which can be used to help find useful directories in your project or source tree.
+Some of these include:
+
+[cols=",",options="header",]
+|=======================================================================
+|Variable |Info
+|CMAKE_SOURCE_DIR |The root source directory
+
+|CMAKE_CURRENT_SOURCE_DIR |The current source directory if using
+sub-projects and directories
+
+|PROJECT_SOURCE_DIR |The source director of the current cmake project.
+
+|CMAKE_BINARY_DIR |The root binary / build directory. This is the
+directory you run the cmake command from
+
+|CMAKE_CURRENT_BINARY_DIR |The build directory you are currently in.
+
+|PROJECT_BINARY_DIR |The build directory for the current project.
+|=======================================================================
+
+[[including-directories]]
+Including Directories
+^^^^^^^^^^^^^^^^^^^^^
+
+When you have different include folders, you can make your compiler aware of them using the
++include_directories()+ function. This will add these directories to the
+compiler with the -I flag e.g. `-I/directory/path`
+
+[source,cmake]
+----
+include_directories(
+    ${PROJECT_SOURCE_DIR}/inc
+    )
+----
+
+
+
+[[setting-source-files]]
+Source Files Variable
+^^^^^^^^^^^^^^^^^^^^
+
+Creating a variable which includes the source files allows you to be
+clearer about these files and easily add them to multiple commands, for example,
+the +add_executable()+ function.
+
+[source,cmake]
+----
+# Create a sources variable with a link to all cpp files to compile
+set(SOURCES
+    src/Hello.cpp
+    src/main.cpp
+)
+
+add_executable(${PROJECT_NAME} ${SOURCES})
+----
+
+[NOTE]
+====
+An alternative to setting specific file names in the +SOURCES+ variable is
+to use a GLOB command to find files using wildcard pattern matching.
+
+
+[source,cmake]
+----
+file(GLOB SOURCES "src/*.cpp")
+----
+====
+
+[[building-the-example]]
+Building the Example
+~~~~~~~~~~~~~~~~~~~~
+
+[source,bash]
+----
+$ mkdir build
+
+$ cd build
+
+$ cmake ..
+-- The C compiler identification is GNU 4.8.4
+-- The CXX compiler identification is GNU 4.8.4
+-- Check for working C compiler: /usr/bin/cc
+-- Check for working C compiler: /usr/bin/cc -- works
+-- Detecting C compiler ABI info
+-- Detecting C compiler ABI info - done
+-- Check for working CXX compiler: /usr/bin/c++
+-- Check for working CXX compiler: /usr/bin/c++ -- works
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build
+
+$ make
+Scanning dependencies of target hello_headers
+[ 50%] Building CXX object CMakeFiles/hello_headers.dir/src/Hello.cpp.o
+[100%] Building CXX object CMakeFiles/hello_headers.dir/src/main.cpp.o
+Linking CXX executable hello_headers
+[100%] Built target hello_headers
+
+$ ./hello_headers
+Hello Headers!
+----
+
+[[verbose-output]]
+Verbose Output
+^^^^^^^^^^^^^^
+
+In the previous examples, when running the make command the output only
+shows the status of the build. To see the full output for debugging
+purposes you can add +VERBOSE=1+ flag when running make.
+
+The VERBOSE output is show below, and a examination of the output shows
+the include directories being added to the c++ compiler command.
+
+[source,bash]
+----
+$ make clean
+
+$ make VERBOSE=1
+/usr/bin/cmake -H/home/matrim/workspace/cmake-examples/01-basic/hello_headers -B/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build --check-build-system CMakeFiles/Makefile.cmake 0
+/usr/bin/cmake -E cmake_progress_start /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles/progress.marks
+make -f CMakeFiles/Makefile2 all
+make[1]: Entering directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+make -f CMakeFiles/hello_headers.dir/build.make CMakeFiles/hello_headers.dir/depend
+make[2]: Entering directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+cd /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build && /usr/bin/cmake -E cmake_depends "Unix Makefiles" /home/matrim/workspace/cmake-examples/01-basic/hello_headers /home/matrim/workspace/cmake-examples/01-basic/hello_headers /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles/hello_headers.dir/DependInfo.cmake --color=
+make[2]: Leaving directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+make -f CMakeFiles/hello_headers.dir/build.make CMakeFiles/hello_headers.dir/build
+make[2]: Entering directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+/usr/bin/cmake -E cmake_progress_report /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles 1
+[ 50%] Building CXX object CMakeFiles/hello_headers.dir/src/Hello.cpp.o
+/usr/bin/c++    -I/home/matrim/workspace/cmake-examples/01-basic/hello_headers/inc    -o CMakeFiles/hello_headers.dir/src/Hello.cpp.o -c /home/matrim/workspace/cmake-examples/01-basic/hello_headers/src/Hello.cpp
+/usr/bin/cmake -E cmake_progress_report /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles 2
+[100%] Building CXX object CMakeFiles/hello_headers.dir/src/main.cpp.o
+/usr/bin/c++    -I/home/matrim/workspace/cmake-examples/01-basic/hello_headers/inc    -o CMakeFiles/hello_headers.dir/src/main.cpp.o -c /home/matrim/workspace/cmake-examples/01-basic/hello_headers/src/main.cpp
+Linking CXX executable hello_headers
+/usr/bin/cmake -E cmake_link_script CMakeFiles/hello_headers.dir/link.txt --verbose=1
+/usr/bin/c++       CMakeFiles/hello_headers.dir/src/Hello.cpp.o CMakeFiles/hello_headers.dir/src/main.cpp.o  -o hello_headers -rdynamic
+make[2]: Leaving directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+/usr/bin/cmake -E cmake_progress_report /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles  1 2
+[100%] Built target hello_headers
+make[1]: Leaving directory `/home/matrim/workspace/cmake-examples/01-basic/hello_headers/build'
+/usr/bin/cmake -E cmake_progress_start /home/matrim/workspace/cmake-examples/01-basic/hello_headers/build/CMakeFiles 0
+----

01-basic/C-static-library/README.adoc

@@ -0,0 +1 @@
+

01-basic/D-shared-library/README.adoc

@@ -0,0 +1 @@
+

04-static-analysis/README.adoc

@@ -1,3 +1,8 @@
+:toc:
+:toc-placement!:
+
+toc::[]
+
 [[static-analysis]]
 Static Analysis
 ---------------
@@ -20,4 +25,3 @@ analysis tool. However standalone tools also exist.
 The examples here include using the following tools:
 
 * http://cppcheck.sourceforge.net/[CppCheck]
-

04-static-analysis/cppcheck/README.adoc

@@ -1,12 +1,21 @@
+
+:toc:
+:toc-placement!:
+
+toc::[]
+
 [[cppcheck-static-analysis]]
 CppCheck Static Analysis
 ------------------------
 
-This example is for calling the
+This example shows how to call the
 http://cppcheck.sourceforge.net/[CppCheck] tool to do static analysis.
 
-It shows how to add cppcheck with a target for each sub-projects and
-also how to generate an overall "make analysis" target to do static
+It includes code to
+
+  * Find the cppcheck binary
+  * Add cppcheck with a target for each sub-projects
+  * Generate an overall `make analysis` target to do static
 analysis on all sub-projects.
 
 [[requirements]]
@@ -33,19 +42,23 @@ Adding Custom Package Modules
 Adding a custom module
 ++++++++++++++++++++++
 
-The cmake/modules/FindCppCheck.cmake file contains the code to find and
-add variables for a custom package module. Custom modules can be used to
+include::cmake/modules/FindCppCheck.cmake
+
+The `cmake/modules/FindCppCheck.cmake` file contains the code to initialise a
+custom package module. Custom modules can be used to
 find programs, libraries and header files to include in your program.
 
-[source,cmake]
+The following is a breakdown of the file:
+
+[source,cmake,numbered]
 ----
 find_program(CPPCHECK_BIN NAMES cppcheck)
 ----
 
-Search the path for the program "cppcheck" and store the result in the
-CPPCHECK_BIN variable
+Search the path for the cppcheck binary. Once found store the result in the
++CPPCHECK_BIN+ variable
 
-[source,cmake]
+[source,cmake,numbered]
 ----
 set (CPPCHECK_THREADS "-j 4" CACHE STRING "The -j argument to have cppcheck use multiple threads / cores")
 
@@ -58,14 +71,14 @@ Set some custom arguments that can be later passed to cppcheck.
 ----
 include(FindPackageHandleStandardArgs)
 FIND_PACKAGE_HANDLE_STANDARD_ARGS(
-    CPPCHECK 
-    DEFAULT_MSG 
+    CPPCHECK
+    DEFAULT_MSG
     CPPCHECK_BIN
     CPPCHECK_THREADS
     CPPCHECK_ARG)
 
 mark_as_advanced(
-    CPPCHECK_BIN  
+    CPPCHECK_BIN
     CPPCHECK_THREADS
     CPPCHECK_ARG)
 ----
@@ -84,7 +97,7 @@ set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules
                       ${CMAKE_MODULE_PATH})
 ----
 
-The $\{CMAKE_MODULE_PATH} points towards a folder which contains custom
+The variable +${CMAKE_MODULE_PATH}+ points towards a folder which contains custom
 cmake modules.
 
 To then add the package module you can call
@@ -111,7 +124,7 @@ set(ALL_ANALYSIS_TARGETS "${ALL_ANALYSIS_TARGETS}" PARENT_SCOPE)
 add_analysis macro
 ^^^^^^^^^^^^^^^^^^
 
-The add_analysis macro in cmake/analysis.cmake is the core idea for this
+The +add_analysis()+ macro in `cmake/analysis.cmake` is the core idea for this
 example. If cppcheck is available then a list of arguments are compiled
 and added to a custom command that calls cppcheck on the sources. These
 are then added to a custom target.
@@ -124,7 +137,7 @@ foreach(dir ${dirs})
 endforeach()
 ----
 
-Find the include files from and calls to include_directories() in the
+Find the include files from and calls to +include_directories()+ in the
 same project.
 
 [source,cmake]
@@ -134,19 +147,19 @@ set(ALL_ANALYSIS_TARGETS "${ALL_ANALYSIS_TARGETS}" PARENT_SCOPE)
 ----
 
 Export the target name into a variable that can later be used to add a
-global "make analysis" target.
+global `make analysis` target.
 
 [source,cmake]
 ----
 if (${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VESION} GREATER 2.7)
     separate_arguments(tmp_args UNIX_COMMAND ${CPPCHECK_ARG})
 else ()
-    # cmake 2.6 has different arguments 
-    string(REPLACE " " ";" tmp_args ${CPPCHECK_ARG})         
+    # cmake 2.6 has different arguments
+    string(REPLACE " " ";" tmp_args ${CPPCHECK_ARG})
 endif ()
 ----
 
-Change the CPPCHECK_ARG so that the can be added to command correctly in
+Change the +CPPCHECK_ARG+ so that the can be added to command correctly in
 the custom command.
 
 [source,cmake]
@@ -174,7 +187,7 @@ you have provided. The sources that are analysed come from a _sources
 variable. This should be the name of the variable which holds your list
 of source files.
 
-To call the add_analysis marco add the following to your projects
+To call the +add_analysis()+ marco add the following to your projects
 CMakeLists.txt file:
 
 [source,cmake]
@@ -188,20 +201,20 @@ Creating a target to call other targets
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In the root CMakeLists.txt a custom target is created, which will call
-all other analysis targets. This allows you to call "make analysis" and
+all other analysis targets. This allows you to call `make analysis` and
 scan all sub projects.
 
 To achieve this 2 things should be added to the root CMakeLists.txt
 
-First add an empty variable ALL_ANALYSIS_TARGETS before calling your
-add_subdirectories() function.
+First add an empty variable +ALL_ANALYSIS_TARGETS+ before calling your
++add_subdirectories()+ function.
 
 [source,cmake]
 ----
 set (ALL_ANALYSIS_TARGETS)
 ----
 
-Second add the following after your add_subdirectories() call.
+Second add the following after your +add_subdirectories()+ call.
 
 [source,cmake]
 ----
@@ -236,7 +249,7 @@ $ cmake ..
 -- Check for working CXX compiler: /usr/bin/c++ -- works
 -- Detecting CXX compiler ABI info
 -- Detecting CXX compiler ABI info - done
--- Found CPPCHECK: /usr/bin/cppcheck  
+-- Found CPPCHECK: /usr/bin/cppcheck
 adding cppcheck analysys target for subproject1
 adding cppcheck analysys target for subproject2
 analysis analysis targets are subproject1_analysis;subproject2_analysis
@@ -244,7 +257,7 @@ analysis analysis targets are subproject1_analysis;subproject2_analysis
 -- Generating done
 -- Build files have been written to: /home/matrim/workspace/cmake-examples/04-static-analysis/cppcheck/build
 
-$ make analysis 
+$ make analysis
 Scanning dependencies of target subproject1_analysis
 Running cppcheck: subproject1
 Checking main1.cpp...
@@ -277,8 +290,8 @@ main2.cpp includes an out-of-bounds error which shows the error.
 ------------------------------------------------------------------------------------
 
 By default cppcheck only prints warnings and exits with a successful
-exit code. If the $\{CPPCHECK_ARG} variable is set with
-"--error-exitcode=1", the make analysis will finish early as follows.
+exit code. If the +${CPPCHECK_ARG}+ variable is set with
+`--error-exitcode=1`, the make analysis will finish early as follows.
 
 [source,bash]
 ----
@@ -312,8 +325,8 @@ sub folders, such as below:
 │   │   │   ├── main.cpp
 ------------------------------
 
-You must add the following to the src/CMakeLists.txt file to correctly
-generate the "make analysis" target
+You must add the following to the `src/CMakeLists.txt` file to correctly
+generate the `make analysis` target
 
 [source,cmake]
 ----

README.adoc

@@ -1,3 +1,8 @@
+:toc:
+:toc-placement!:
+
+toc::[]
+
 [[cmake-examples]]
 cmake-examples
 --------------
@@ -31,4 +36,3 @@ Some specific examples may require other tools including:
 * boost `$ sudo apt-get libboost-all-dev`
 * protobuf `$ sudo apt-get install libprotobuf-dev`
 * cppcheck `$ sudo apt-get install cppcheck`
-