diff --git a/01-basic/A-hello-cmake/README.adoc b/01-basic/A-hello-cmake/README.adoc index 453b4101..8899b198 100644 --- a/01-basic/A-hello-cmake/README.adoc +++ b/01-basic/A-hello-cmake/README.adoc @@ -43,6 +43,7 @@ cmake_minimum_required(VERSION 3.5) A CMake build can include a project name to make referencing certain variables easier when using multiple projects. +(**CMake构建可以包含一个项目名称，以确保使用多个项目时，引用变量更容易**) [source,cmake] ---- @@ -56,6 +57,7 @@ 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] ---- @@ -88,6 +90,8 @@ The root or top level folder that you run the cmake command from is known as you CMAKE_BINARY_DIR and is the root folder for all your binary files. CMake supports building and generating your binary files both in-place and also out-of-source. +（**CMAKE_BINARY_DIR,为运行cmake命令的工作目录，是二进制目标文件的根文件目录，即二进制中间目标文件存放位置的顶级目录**） +（**cmake支持在本地或源文件之外，构建您的二进制文件**） #### In-Place Build @@ -153,7 +157,7 @@ A-hello-cmake$ tree ---- -#### Out-of-Source Build +#### Out-of-Source Build（**推荐**） Out-of-source builds allow you to create a single build folder that can be anywhere on your file system. All temporary build and object files are located in this directory keeping diff --git a/01-basic/B-hello-headers/README.adoc b/01-basic/B-hello-headers/README.adoc index 16db1174..0b003e75 100644 --- a/01-basic/B-hello-headers/README.adoc +++ b/01-basic/B-hello-headers/README.adoc @@ -40,22 +40,22 @@ Some of these include: [cols=",",options="header",] |======================================================================= |Variable |Info -|CMAKE_SOURCE_DIR |The root source directory +|CMAKE_SOURCE_DIR |The root source directory（最外层CMakeLists.txt所在目录） |CMAKE_CURRENT_SOURCE_DIR |The current source directory if using -sub-projects and directories. +sub-projects and directories.（当前处理的CMakeLists.txt所在的目录） -|PROJECT_SOURCE_DIR |The source directory of the current cmake project. +|PROJECT_SOURCE_DIR |The source directory of the current cmake project.（包含PROJECT()命令的最近一个CMakeLists.txt所在文件夹路径） |CMAKE_BINARY_DIR |The root binary / build directory. This is the -directory where you ran the cmake command. +directory where you ran the cmake command.（二进制文件所在的根目录） -|CMAKE_CURRENT_BINARY_DIR |The build directory you are currently in. +|CMAKE_CURRENT_BINARY_DIR |The build directory you are currently in.（当前正在处理的二进制目录路径） -|PROJECT_BINARY_DIR |The build directory for the current project. +|PROJECT_BINARY_DIR |The build directory for the current project.（当前工程所创建的build目录） |======================================================================= -## Source Files Variable +## 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, @@ -98,6 +98,8 @@ correct results if you add a new source file. When you have different include folders, you can make your compiler aware of them using the +target_include_directories()+ link:https://cmake.org/cmake/help/v3.0/command/target_include_directories.html[function]. When compiling this target this will add these directories to the compiler with the -I flag e.g. `-I/directory/path` +（*编译此目标时，将把该目录添加到编译器中，故这里的target应该指的是可执行程序，而目录指的是头文件所在目录*） + [source,cmake] ---- target_include_directories(target diff --git a/01-basic/C-static-library/README.adoc b/01-basic/C-static-library/README.adoc index 5f30a872..84f54c98 100644 --- a/01-basic/C-static-library/README.adoc +++ b/01-basic/C-static-library/README.adoc @@ -32,11 +32,15 @@ $ tree # Concepts -## Adding a Static Library +## Adding a Static Library（创建一个静态库） The +add_library()+ function is used to create a library from some source files. This is called as follows: +（*使用关键字STATIC-静态，这里的target为hello_library,不必与工程同名，只是声明一个静态库target名,这将创建一个名为libhello_library.a的静态库（在二进制文件目录下）*） + +（*使用的源文件目录，默认以CMakeLists.txt所在目录为起点*） + [source,cmake] ---- add_library(hello_library STATIC @@ -57,6 +61,12 @@ As mentioned in the previous example, we pass the source files directly to the In this example, we include directories in the library using the +target_include_directories()+ function with the scope set to +PUBLIC+. +（*这里的target目标，为hello_library,其实是库target名*） + +（*为target包含的目录为～/include,所以库的源文件只需#include "static/Hello.h"（这就是target's include directory）,而不需使用绝对路径*） + +（*这里的范围属性scope，设置成PUBIC,表示当编译这个target或连接link了这个target的其他target时，将该目录添加到target或连接了该target的其他target的包含目录中，所以这也是为什么连接了库的源文件只需#include "static/Hello.h"*） + [source,cmake] ---- target_include_directories(hello_library @@ -72,9 +82,9 @@ This will cause the included directory used in the following places: The meaning of scopes are: -* +PRIVATE+ - the directory is added to this target's include directories -* +INTERFACE+ - the directory is added to the include directories for any targets that link this library. -* +PUBLIC+ - As above, it is included in this library and also any targets that link this library. +* +PRIVATE+ - the directory is added to this target's include directories（将目录添加到该target的包含目录中） +* +INTERFACE+ - the directory is added to the include directories for any targets that link this library.（该目录将添加到连接此target的任何其他target的包含目录中,不包括本target） +* +PUBLIC+ - As above, it is included in this library and also any targets that link this library.（如上所述，它包括在此target中，也包括连接此target的任何其他target） [TIP] @@ -100,6 +110,10 @@ you use multiple libraries in your project. When creating an executable that will use your library you must tell the compiler about the library. This can be done using the +target_link_libraries()+ function. +(*创建可执行文件，之传递了一个main.cpp，我们还需建可执行文件与库连接起来，我们使用target_link_libraries函数来告诉编译器*) + +（*这里只需将范围属性设置成PRIVATE*） + [source,cmake] ---- add_executable(hello_binary diff --git a/01-basic/D-shared-library/README.adoc b/01-basic/D-shared-library/README.adoc index adda5866..8f6db350 100644 --- a/01-basic/D-shared-library/README.adoc +++ b/01-basic/D-shared-library/README.adoc @@ -32,12 +32,14 @@ $ tree # Concepts -## Adding a Shared Library +## Adding a Shared Library（创建一个动态库） As with the previous example on static libraries, the +add_library()+ function is also used to create a shared library from some source files. This is called as follows: +（*使用关键自SHARED-动态，这将创建一个名为libhello_library.so的动态库文件*） + [source,cmake] ---- add_library(hello_library SHARED @@ -59,6 +61,12 @@ add_library(hello::library ALIAS hello_library) As shown below, this allows you to reference the target using the alias name when linking it against other targets. +## 添加包含目录 + +---- +target_include_directories(hello_library PUBLIC {PROJECT_SOURCE_DIR}/include) +---- + ## Linking a Shared Library Linking a shared library is the same as linking a static library. When creating your diff --git a/01-basic/F-build-type/README.adoc b/01-basic/F-build-type/README.adoc index 5635286e..83a076fe 100644 --- a/01-basic/F-build-type/README.adoc +++ b/01-basic/F-build-type/README.adoc @@ -10,12 +10,25 @@ CMake has a number of built in build configurations which can be used to compile your project. These specify the optimization levels and if debug information is to be included in the binary. +(*CMake中有许多内置的构建配置，用来编译你的工程project。它们指定了优化级别以及是否将调试信息包含在二进制文件中*) + The levels provided are: * Release - Adds the `-O3 -DNDEBUG` flags to the compiler + + （*发行版，顾名思义，程序完成开发后的发布版本，对代码做了优化，速度快，但无法跟踪代码，不能打断点调试*） + * Debug - Adds the `-g` flag + + （*调试版，即对代码不做任何优化，但可以调试项目中的任意文件。速度相对较慢、体积也更大*） + * MinSizeRel - Adds `-Os -DNDEBUG` + + （*Release的近似版，代码也同样记过优化，但同时也支持添加断点进行调试*） + * RelWithDebInfo - Adds `-O2 -g -DNDEBUG` flags + + （最小体积版本，与Release版近似，但更偏重于优化文件大小，而非运行速度） The files in this tutorial are below: @@ -31,11 +44,11 @@ $ tree # Concepts -## Set Build Type +## Set Build Type （构建类型） The build type can be set using the following methods. - - Using a gui tool such as ccmake / cmake-gui + - Using a gui tool such as ccmake / cmake-gui （CMake图形界面） image::cmake-gui-build-type.png[cmake-gui build type] diff --git a/01-basic/G-compile-flags/README.adoc b/01-basic/G-compile-flags/README.adoc index 7e55abc5..3aeeba7b 100644 --- a/01-basic/G-compile-flags/README.adoc +++ b/01-basic/G-compile-flags/README.adoc @@ -6,6 +6,8 @@ toc::[] # Introduction +（*compile flags——编译标志。可执行文件的生成离不开编译，那么如何编译，如使用C++或C的那个版本？这就要用到编译标志了*） + CMake supports setting compile flags in a number of different ways: * using +target_compile_definitions()+ function diff --git a/01-basic/H-third-party-library/README.adoc b/01-basic/H-third-party-library/README.adoc index 9e8fcdc8..a2edf3d9 100644 --- a/01-basic/H-third-party-library/README.adoc +++ b/01-basic/H-third-party-library/README.adoc @@ -1,4 +1,4 @@ -= Including Third Party Library += Including Third Party Library（包含第三方库） :toc: :toc-placement!: @@ -13,6 +13,14 @@ the `find_package()` function. This will search for CMake modules in the format default search path will include `/usr/share/cmake/Modules`. On my system this includes support for approximately 142 common third party libraries. +（*几乎所有非平凡的项目都要求包含第三方库、头文件或程序。CMake支持使用find_package()函数（间接）查找这些工具的路径*） + +（*这将从CMAKE_MODULE_PATH中的文件夹列表搜索格式为FindXXX.cmake的CMake模块，如果没找到将会查找XXXConfig.cmake或XXX-config.cmake,在这些格式的文件里定义了许多变量，用于指定要包含的库和头文件的路径*） + +（*CMAKE_MODULE_PATH指定的默认路径为/usr/share/cmake-/Modules;在我的系统中，包含对大约142个通用第三方库的支持*） + +（*find_package()支持两种模式，一是Module模式，二是Config模式；如果Module模式搜索失败，则会转入Config模式，搜索路径是/usr/local/lib/cmake/(find_package的搜索路径是一系列的集合)*） + The files in this tutorial are below: @@ -40,6 +48,8 @@ As mentioned above the `find_package()` function will search for CMake modules i format of the arguments to `find_package` will depend on the module you are looking for. This is typically documented at the top of the `FindXXX.cmake` file. +（*find_package()参数的确切格式取决于要查找的模块，这通常记录在FindXXX.cmake文件的顶部*） + A basic example of finding boost is below: [source,cmake] @@ -49,10 +59,21 @@ find_package(Boost 1.46.1 REQUIRED COMPONENTS filesystem system) The arguments are: - * Boost - Name of the library. This is part of used to find the module file FindBoost.cmake + * Boost - Name of the library. This is part of used to find the module file FindBoost.cmake（是用于查找模块文件FindBoost.cmake的一部分） + + *Boost库是为C++语言标准库提供扩展的一些程序库的总称，由Boost社区组织开发、维护。Boost库可以与C++标准库完美共同工作，并为其提供扩展功能* + * 1.46.1 - The minimum version of boost to find + + *需要的boost库的最低版本* + * REQUIRED - Tells the module that this is required and to fail if it cannot be found + + *告诉模块这是必须的，如果找不到会报错* + * COMPONENTS - The list of components to find in the library. + + *在Boost中要找的部分* Boost includes can take more arguments and also make use of other variables. More complex setups are provided in later examples. @@ -63,6 +84,8 @@ More complex setups are provided in later examples. Most included packages will set a variable `XXX_FOUND`, which can be used to check if the package is available on the system. +(*大多数被包含（被找到）的包将设置变量XXX_FOUND，用于检查软件包在系统上是否可用*) + In this example the variable is `Boost_FOUND`: [source,cmake] @@ -75,13 +98,15 @@ else() endif() ---- -## Exported Variables +## Exported Variables（导出变量） After a package is found it will often export variables which can inform the user where to find the library, header, or executable files. Similar to the `XXX_FOUND` variable, these are package specific and are typically documented at the top of the `FindXXX.cmake` file. +（*找到包后，将自动导出变量，这些变量通常记录在FindXXX.cmake文件的顶部。这些变量可以通知用户在哪里可以找到库、头文件或可执行文件*） + The variables exported in this example include: * `Boost_INCLUDE_DIRS` - The path to the boost header files. @@ -89,11 +114,13 @@ The variables exported in this example include: In some cases you can also check these variables by examining the cache using ccmake or cmake-gui. -## Alias / Imported targets +## Alias / Imported targets（别名/导入目标） Most modern CMake libraries link:https://cmake.org/cmake/help/v3.6/prop_tgt/IMPORTED.html#prop_tgt:IMPORTED[export] +ALIAS+ targets in their module files. The benefit of imported targets are that they can also populate include directories and linked libraries. +（*大多数现代CMake库在其模块文件（FindXXX.cmake）导出别名目标。导入目标的好处是它们也可以填充包含目录和链接的库。*） + For example, starting from v3.5+ of CMake, the Boost module supports this. Similar to using your own ALIAS target for libraires, an +ALIAS+ in a module can make referencing found targets easier. @@ -104,7 +131,7 @@ of the subsystem. For example you can use: * `Boost::system` for the boost system library. * `Boost::filesystem` for filesystem library. -As with your own targets, these targets include their dependencies, so linking against +As with your own targets, these targets include their dependencies（依赖关系）, so linking against `Boost::filesystem` will automatically add `Boost::boost` and `Boost::system` dependencies. To link against an imported target you can use the following: diff --git a/01-basic/I-compiling-with-clang/README.adoc b/01-basic/I-compiling-with-clang/README.adoc index 3d4ae9c3..3c00d114 100644 --- a/01-basic/I-compiling-with-clang/README.adoc +++ b/01-basic/I-compiling-with-clang/README.adoc @@ -10,6 +10,8 @@ When building with CMake it is possible to set the C and C++ compiler. This exam is the same as the link:../A-hello-cmake[hello-cmake] example except that it shows the most basic method of changing the compiler from the default gcc to http://clang.llvm.org/[clang]. +（*以下介绍了将编译器从默认的gcc更改为clang的最基本的方式*） + The files in this tutorial are below: ``` diff --git a/01-basic/J-building-with-ninja/README.adoc b/01-basic/J-building-with-ninja/README.adoc index 039374ae..92630f5f 100644 --- a/01-basic/J-building-with-ninja/README.adoc +++ b/01-basic/J-building-with-ninja/README.adoc @@ -24,13 +24,17 @@ $ tree # Concepts -### Generators +### Generators（生成器） CMake https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html[generators] are responsible for writing the input files (e.g. Makefiles) for the underlying build system. Running `cmake --help` will show the generators available. For cmake v2.8.12.2 the generators supported on my system include: +（*CMake生成器就是通过CMakelists.txt文件生成适用于不同项目类型的makefile文件，然后makefile文件被不同的编译器使用进行编译*） + +（*当然C/C++有许多开发环境，故也有多种生成器*） + [source,bash] ---- Generators @@ -57,6 +61,8 @@ CMake includes different types of generators such as Command-Line, IDE, and Extr These generators are for command-line build tools, like Make and Ninja. The chosen tool chain must be configured prior to generating the build system with CMake. +(*这些生成器用于命令行构建工具。在使用CMake生成构建系统之前，须配置所选的工具链*) + The supported generators include: * Borland Makefiles @@ -72,6 +78,8 @@ The supported generators include: These generators are for Integrated Development Environments that include their own compiler. Examples are Visual Studio and Xcode which include a compiler natively. +（*这些生成器用于含有自己的编译器的IDE（集成开发环境），不需自己配置工具链*） + The supported generators include: * Visual Studio 6 @@ -88,6 +96,8 @@ The supported generators include: These are generators create a configuration to work with an alternative IDE tool and must be included with either an IDE or Command-Line generator. +（*这些生成器创建一个配置来使用一个可选的IDE工具，并且必须包含在IDE或命令行生成器中。 *） + The supported generators include: * CodeBlocks diff --git a/02-sub-projects/A-basic/README.adoc b/02-sub-projects/A-basic/README.adoc index 98b1f2b9..1b49d28d 100644 --- a/02-sub-projects/A-basic/README.adoc +++ b/02-sub-projects/A-basic/README.adoc @@ -51,6 +51,9 @@ $ tree In this example I have moved the header files to a subfolder under each projects +include+ directory, while leaving the target include as the root +include+ folder. This is a good idea to prevent filename clashes because you have to include a file like below: + +*不是直接将头文件放在include下，而是放在include/header/header.h,并且将target的包含目录设置为～/include，这样在一个项目含有多个头文件时可以有效防止文件名冲突* + [source,cpp] ---- #include "sublib1/sublib1.h" @@ -65,7 +68,7 @@ This also means that if you install your library for other users the default ins ## Adding a Sub-Directory A CMakeLists.txt file can include and call sub-directories which include a CMakeLists.txt -files. +files.(利用 `add_subdirectory()` 函数一个CMakeLists.txt文件可以包含和调用一个含有CMakeLists.txt文件的子目录) [source,cmake] ---- @@ -80,6 +83,7 @@ When a project is created using the `project()` command, CMake will automaticall create a number of variables which can be used to reference details about the project. These variables can then be used by other sub-projects or the main project. For example, to reference the source directory for a different project you can use. +（当使用 `project()` 创建一个项目时，CMake会自动创建一系列可以用来引用该项目相关信息的变量。这些变量可以被子项目或主项目使用） [source,cmake] ---- @@ -97,7 +101,7 @@ The variables created by CMake include: |CMAKE_PROJECT_NAME |the name of the first project set by the `project()` command, i.e. the top level project. -|PROJECT_SOURCE_DIR |The source director of the current project. +|PROJECT_SOURCE_DIR |The source directory of the current project. |PROJECT_BINARY_DIR |The build directory for the current project. @@ -111,7 +115,7 @@ In this example the binary directories created would be `sublibrary1_BINARY_DIR` |======================================================================= -## Header only Libraries +## Header only Libraries（*只含头文件的库，利用INTERFACE*） If you have a library that is created as a header only library, cmake supports the +INTERFACE+ target to allow creating a target without any build output. More details can be found from @@ -134,12 +138,12 @@ target_include_directories(${PROJECT_NAME} ) ---- -## Referencing Libraries from Sub-Projects +## Referencing Libraries from Sub-Projects（*引用子目录中的库*） If a sub-project creates a library, it can be referenced by other projects by calling the name of the target in the `target_link_libraries()` command. This means that you don't have to reference the full path of the new library and it -is added as a dependency. +is added as a dependency.（*在某项目中创建的target名，可在子目录或主目录中调用，可以说其作用域为整个项目*） [source,cmake] ---- @@ -150,7 +154,7 @@ target_link_libraries(subbinary ---- Alternatively, you can create an alias target which allows you to reference the -target in read only contexts. +target in read only contexts.（*当然target的别名同样是全局作用域，只不过是只读的*） To create an alias target run: diff --git a/03-code-generation/README.adoc b/03-code-generation/README.adoc index fe6201b6..4498987a 100644 --- a/03-code-generation/README.adoc +++ b/03-code-generation/README.adoc @@ -1,6 +1,6 @@ = Code Generation -Code generation can be useful to create source code in different languages from a common description file. This can reduce the amount of manual code to write and increase interoperability. +Code generation can be useful to create source code in different languages from a common description file. This can reduce the amount of manual code to write and increase interoperability.（代码生成对于从公共描述文件创建不同语言的源代码非常有用。这可以减少要编写的手动代码量，并提高互操作性。） Examples showing code generation using variables from CMake and also using some common tools. diff --git a/03-code-generation/configure-files/README.adoc b/03-code-generation/configure-files/README.adoc index 6715c7d4..d6a10ae2 100644 --- a/03-code-generation/configure-files/README.adoc +++ b/03-code-generation/configure-files/README.adoc @@ -8,7 +8,7 @@ toc::[] During the call to cmake it is possible to create files that use variables from the CMakeLists.txt and cmake cache. During CMake generation the file is copied to a -new location and any cmake variables are replaced. +new location and any cmake variables are replaced.(可以创建使用来自CMakeLists.txt和cmake cache(cmake内存)中的变量的文件。并且在CMake生成过程中，该文件被复制到新位置，并替换任何cmake变量) The files in this tutorial are below: @@ -32,6 +32,7 @@ $ tree To do variable substitution in a file you can use the `configure_file()` function in CMake. This core arguments for this function are source file and destination file. +（利用 `configure_file（）` 函数实现变量替换。其函数的核心参数是源文件和目标文件（说明路径）。该函数使用后，就可以在源文件里以 `${}` 或 `@@` 的形式使用在CMakeLists.txt里定义的变量。预处理时（猜测，因为即使在“”里都可以被替换），这些变量将会在目标文件里被替换成实际内容。） [source,cmake] ---- @@ -43,6 +44,7 @@ configure_file(path.h.in ${PROJECT_BINARY_DIR}/path.h @ONLY) The first example above, allows the variable to be defined like a CMake variables using the `${}` syntax or an `@@` in the ver.h.in file. After generation a new file ver.h will be available in the `PROJECT_BINARY_DIR`. +（上面的第一个例子，源文件是ver.h.in，目标文件是ver.h(省略路径)，只做变量替换，其他内容不变。第二个例子有一个参数 @ONLY，意思是只识别带有 @@ 形式的变量。） ``` const char* ver = "${cf_example_VERSION}";