From f3113829b77b769bd10b2d6ac89e2084e566ba0a Mon Sep 17 00:00:00 2001 From: ttroy50 Date: Sun, 22 Nov 2015 01:36:29 +0000 Subject: [PATCH] fixes for asciidoc --- 01-basic/A-hello-cmake/README.adoc | 107 +++++++++++++++ 01-basic/B-hello-headers/README.adoc | 168 ++++++++++++++++++++++++ 01-basic/C-static-library/README.adoc | 1 + 01-basic/D-shared-library/README.adoc | 1 + 04-static-analysis/README.adoc | 6 +- 04-static-analysis/cppcheck/README.adoc | 73 +++++----- README.adoc | 6 +- 7 files changed, 330 insertions(+), 32 deletions(-) create mode 100644 01-basic/A-hello-cmake/README.adoc create mode 100644 01-basic/B-hello-headers/README.adoc create mode 100644 01-basic/C-static-library/README.adoc create mode 100644 01-basic/D-shared-library/README.adoc diff --git a/01-basic/A-hello-cmake/README.adoc b/01-basic/A-hello-cmake/README.adoc new file mode 100644 index 0000000..966945c --- /dev/null +++ b/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! +---- diff --git a/01-basic/B-hello-headers/README.adoc b/01-basic/B-hello-headers/README.adoc new file mode 100644 index 0000000..92b7c5c --- /dev/null +++ b/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 +---- diff --git a/01-basic/C-static-library/README.adoc b/01-basic/C-static-library/README.adoc new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/01-basic/C-static-library/README.adoc @@ -0,0 +1 @@ + diff --git a/01-basic/D-shared-library/README.adoc b/01-basic/D-shared-library/README.adoc new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/01-basic/D-shared-library/README.adoc @@ -0,0 +1 @@ + diff --git a/04-static-analysis/README.adoc b/04-static-analysis/README.adoc index f472668..3ed4116 100644 --- a/04-static-analysis/README.adoc +++ b/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] - diff --git a/04-static-analysis/cppcheck/README.adoc b/04-static-analysis/cppcheck/README.adoc index 6f1f905..db35aeb 100644 --- a/04-static-analysis/cppcheck/README.adoc +++ b/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] ---- diff --git a/README.adoc b/README.adoc index a53e5c2..f6f94b2 100644 --- a/README.adoc +++ b/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` -