Merge pull request #500 from robertodr/abstracts

Abstracts for chapters 5, 7, and 9
dev-cafe · Sep 23, 2018 · 0f8f1fb · 0f8f1fb
2 parents 9ffcbfd + 749e008
commit 0f8f1fb
Show file tree

Hide file tree

Showing 48 changed files with 230 additions and 40 deletions.
diff --git a/chapter-05/recipe-01/README.md b/chapter-05/recipe-01/README.md
@@ -1,5 +1,9 @@
 # Using platform-independent file operations
 
-Abstract to be written ...
+This recipe will show how to run operations on files, such as uncompressing a
+archive or renaming a folder, in a platform-independent fashion.
+CMake can in fact be used in [command-line tool mode](https://cmake.org/cmake/help/v3.12/manual/cmake.1.html#command-line-tool-mode)
+and offers a number of wrappers to many common operations.
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-05/recipe-01/abstract.md b/chapter-05/recipe-01/abstract.md
@@ -0,0 +1,4 @@
+This recipe will show how to run operations on files, such as uncompressing a
+archive or renaming a folder, in a platform-independent fashion.
+CMake can in fact be used in [command-line tool mode](https://cmake.org/cmake/help/v3.12/manual/cmake.1.html#command-line-tool-mode)
+and offers a number of wrappers to many common operations.
diff --git a/chapter-05/recipe-02/README.md b/chapter-05/recipe-02/README.md
@@ -1,5 +1,9 @@
 # Running a custom command at configure time
 
-Abstract to be written ...
+We will show how to run a custom command at configure time using the built-in
+[`execute_process`] command offered by CMake.
+
+[`execute_process`]: https://cmake.org/cmake/help/latest/command/execute_process.html
+
 
 - [example](example/)
diff --git a/chapter-05/recipe-02/abstract.md b/chapter-05/recipe-02/abstract.md
@@ -0,0 +1,4 @@
+We will show how to run a custom command at configure time using the built-in
+[`execute_process`] command offered by CMake.
+
+[`execute_process`]: https://cmake.org/cmake/help/latest/command/execute_process.html
diff --git a/chapter-05/recipe-03/README.md b/chapter-05/recipe-03/README.md
@@ -1,5 +1,9 @@
 # Running a custom command at build time: I. Using `add_custom_command`
 
-Abstract to be written ...
+This recipe will show how to use [`add_custom_target`] to add new targets with
+custom build goals to the build system.
+
+[`add_custom_target`]: https://cmake.org/cmake/help/latest/command/add_custom_target.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-05/recipe-03/abstract.md b/chapter-05/recipe-03/abstract.md
@@ -0,0 +1,4 @@
+This recipe will show how to use [`add_custom_target`] to add new targets with
+custom build goals to the build system.
+
+[`add_custom_target`]: https://cmake.org/cmake/help/latest/command/add_custom_target.html
diff --git a/chapter-05/recipe-04/README.md b/chapter-05/recipe-04/README.md
@@ -1,5 +1,6 @@
 # Running a custom command at build time: II. Using `add_custom_target`
 
-Abstract to be written ...
+Running a custom command at build time: II. Using `add_custom_target`
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-05/recipe-04/abstract.md b/chapter-05/recipe-04/abstract.md
@@ -0,0 +1 @@
+Running a custom command at build time: II. Using `add_custom_target`
diff --git a/chapter-05/recipe-05/README.md b/chapter-05/recipe-05/README.md
@@ -1,5 +1,10 @@
 # Running custom commands for specific targets at build time
 
-Abstract to be written ...
+[`add_custom_command`] can be used to attach execution of additional commands
+for specific targets at specific moments during build time. This recipe will
+show you how.
+
+[`add_custom_command`]: https://cmake.org/cmake/help/latest/command/add_custom_command.html
+
 
 - [fortran-example](fortran-example/)
diff --git a/chapter-05/recipe-05/abstract.md b/chapter-05/recipe-05/abstract.md
@@ -0,0 +1,5 @@
+[`add_custom_command`] can be used to attach execution of additional commands
+for specific targets at specific moments during build time. This recipe will
+show you how.
+
+[`add_custom_command`]: https://cmake.org/cmake/help/latest/command/add_custom_command.html
diff --git a/chapter-05/recipe-06/README.md b/chapter-05/recipe-06/README.md
@@ -1,8 +1,12 @@
 # Probing compilation and linking
 
-We show the usage of `check_<lang>_source_compiles` to check that a small code
-snippet compiles. This will be contrasted with `try_compile`. Finally, we
-discuss how to troubleshoot `try_compile` to avoid false negatives and false positives.
+We show the usage of `check_<lang>_source_compiles` (where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCSourceCompiles.html),
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXSourceCompiles.html) or
+[Fortran](https://cmake.org/cmake/help/latest/module/CheckFortranSourceCompiles.html)) to check that a small code
+snippet compiles. This will be contrasted with [`try_compile`]. Finally, we
+discuss how to troubleshoot [`try_compile`] to avoid false negatives and false positives.
+
+[`try_compile`]: https://cmake.org/cmake/help/latest/command/try_compile.html
 
 
 - [cxx-example](cxx-example/)

diff --git a/chapter-05/recipe-06/abstract.md b/chapter-05/recipe-06/abstract.md
@@ -1,3 +1,7 @@
-We show the usage of `check_<lang>_source_compiles` to check that a small code
-snippet compiles. This will be contrasted with `try_compile`. Finally, we
-discuss how to troubleshoot `try_compile` to avoid false negatives and false positives.
+We show the usage of `check_<lang>_source_compiles` (where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCSourceCompiles.html),
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXSourceCompiles.html) or
+[Fortran](https://cmake.org/cmake/help/latest/module/CheckFortranSourceCompiles.html)) to check that a small code
+snippet compiles. This will be contrasted with [`try_compile`]. Finally, we
+discuss how to troubleshoot [`try_compile`] to avoid false negatives and false positives.
+
+[`try_compile`]: https://cmake.org/cmake/help/latest/command/try_compile.html
diff --git a/chapter-05/recipe-07/README.md b/chapter-05/recipe-07/README.md
@@ -1,10 +1,16 @@
 # Probing compiler flags
 
-We show the usage of `check_<lang>_compiler_flag` to check for the availability
-of compiler flags. The example will show how to set compiler flags for the
-sanitizers (address, memory, thread and undefined behavior) which require the
-flag to be passed also to the linker.
+We show the usage of `check_<lang>_compiler_flag`
+(where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCCompilerFlags.html),
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXCompilerFlags.html) or
+[Fortran](https://cmake.org/cmake/help/latest/module/CheckFortranCompilerFlags.html))
+to check for the availability of compiler flags.
+The example will show how to set compiler flags for the sanitizers (address,
+memory, thread and undefined behavior) which require the flag to be passed also
+to the linker.
 This function is available for Fortran since CMake 3.3.
 
+We will expand on this example in [Recipe 3 in Chapter 7](../../chapter-07/recipe-03)
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-05/recipe-07/abstract.md b/chapter-05/recipe-07/abstract.md
@@ -1,5 +1,11 @@
-We show the usage of `check_<lang>_compiler_flag` to check for the availability
-of compiler flags. The example will show how to set compiler flags for the
-sanitizers (address, memory, thread and undefined behavior) which require the
-flag to be passed also to the linker.
+We show the usage of `check_<lang>_compiler_flag`
+(where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCCompilerFlags.html),
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXCompilerFlags.html) or
+[Fortran](https://cmake.org/cmake/help/latest/module/CheckFortranCompilerFlags.html))
+to check for the availability of compiler flags.
+The example will show how to set compiler flags for the sanitizers (address,
+memory, thread and undefined behavior) which require the flag to be passed also
+to the linker.
 This function is available for Fortran since CMake 3.3.
+
+We will expand on this example in [Recipe 3 in Chapter 7](../../chapter-07/recipe-03)
diff --git a/chapter-05/recipe-08/README.md b/chapter-05/recipe-08/README.md
@@ -1,7 +1,9 @@
 # Probing execution
 
-We show how to use `check_<language>_source_runs` to compile, link and run a
-test executable.
+We show how to use `check_<language>_source_runs`
+(where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCSourceRuns.html) or
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXSourceRuns.html))
+to compile, link and run a test executable.
 This function is not available for Fortran!
 
 

diff --git a/chapter-05/recipe-08/abstract.md b/chapter-05/recipe-08/abstract.md
@@ -1,3 +1,5 @@
-We show how to use `check_<language>_source_runs` to compile, link and run a
-test executable.
+We show how to use `check_<language>_source_runs`
+(where `<lang>` can be [C](https://cmake.org/cmake/help/latest/module/CheckCSourceRuns.html) or
+[CXX](https://cmake.org/cmake/help/latest/module/CheckCXXSourceRuns.html))
+to compile, link and run a test executable.
 This function is not available for Fortran!
diff --git a/chapter-05/recipe-09/README.md b/chapter-05/recipe-09/README.md
@@ -1,6 +1,8 @@
 # Fine-tuning configuration and compilation with generator expressions
 
-We show how to rewrite conditionals into generator expressions.
+We show how to rewrite conditionals into [`generator expressions`].
+
+[`generator expressions`]: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html
 
 
 - [cxx-example](cxx-example/)

diff --git a/chapter-05/recipe-09/abstract.md b/chapter-05/recipe-09/abstract.md
@@ -1 +1,3 @@
-We show how to rewrite conditionals into generator expressions.
+We show how to rewrite conditionals into [`generator expressions`].
+
+[`generator expressions`]: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html
diff --git a/chapter-07/recipe-01/README.md b/chapter-07/recipe-01/README.md
@@ -1,5 +1,10 @@
 # Code reuse with functions and macros
 
-Abstract to be written ...
+This recipe will show how to use [functions] and [macros] in CMake and discuss
+the differences between the two.
+
+[functions]: https://cmake.org/cmake/help/latest/command/function.html#command:function
+[macros]: https://cmake.org/cmake/help/latest/command/macro.html#command:macro
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-07/recipe-01/abstract.md b/chapter-07/recipe-01/abstract.md
@@ -0,0 +1,5 @@
+This recipe will show how to use [functions] and [macros] in CMake and discuss
+the differences between the two.
+
+[functions]: https://cmake.org/cmake/help/latest/command/function.html#command:function
+[macros]: https://cmake.org/cmake/help/latest/command/macro.html#command:macro
diff --git a/chapter-07/recipe-02/README.md b/chapter-07/recipe-02/README.md
@@ -1,5 +1,9 @@
 # Splitting CMake sources into modules
 
-Abstract to be written ...
+We will show how to separate custom CMake code into our own [modules], rather
+than keeping everything in a central `CMakeLists.txt`.
+
+[modules]: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#modules
+
 
 - [example](example/)
diff --git a/chapter-07/recipe-02/abstract.md b/chapter-07/recipe-02/abstract.md
@@ -0,0 +1,4 @@
+We will show how to separate custom CMake code into our own [modules], rather
+than keeping everything in a central `CMakeLists.txt`.
+
+[modules]: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#modules
diff --git a/chapter-07/recipe-03/README.md b/chapter-07/recipe-03/README.md
@@ -1,5 +1,7 @@
 # Writing a function to test and set compiler flags
 
-Abstract to be written ...
+Elaborating on [Recipe 7 in Chapter 5](../../chapter-05/recipe-07), we will show
+how to write a function to test and set compiler flags for your project.
+
 
 - [c-cxx-example](c-cxx-example/)
diff --git a/chapter-07/recipe-03/abstract.md b/chapter-07/recipe-03/abstract.md
@@ -0,0 +1,2 @@
+Elaborating on [Recipe 7 in Chapter 5](../../chapter-05/recipe-07), we will show
+how to write a function to test and set compiler flags for your project.
diff --git a/chapter-07/recipe-04/README.md b/chapter-07/recipe-04/README.md
@@ -1,5 +1,9 @@
 # Defining a function or macro with named arguments
 
-Abstract to be written ...
+We will show how to enhance the example in [Recipe 1, _Code reuse with functions and macros_](../recipe-01)
+by letting the function accept _named arguments_. We will use the built-in [`cmake_parse_arguments`] command.
+
+[`cmake_parse_arguments`]: https://cmake.org/cmake/help/latest/command/cmake_parse_arguments.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-07/recipe-04/abstract.md b/chapter-07/recipe-04/abstract.md
@@ -0,0 +1,4 @@
+We will show how to enhance the example in [Recipe 1, _Code reuse with functions and macros_](../recipe-01)
+by letting the function accept _named arguments_. We will use the built-in [`cmake_parse_arguments`] command.
+
+[`cmake_parse_arguments`]: https://cmake.org/cmake/help/latest/command/cmake_parse_arguments.html
diff --git a/chapter-07/recipe-05/README.md b/chapter-07/recipe-05/README.md
@@ -1,5 +1,10 @@
 # Redefining functions and macros
 
-Abstract to be written ...
+This recipe shows how to redefine functions and macros. Our example will show
+how to emulate the [`include_guard`] command, which is built-in since CMake
+3.10, on systems running an older version of CMake.
+
+[`include_guard`]: https://cmake.org/cmake/help/latest/command/include_guard.html
+
 
 - [example](example/)
diff --git a/chapter-07/recipe-05/abstract.md b/chapter-07/recipe-05/abstract.md
@@ -0,0 +1,5 @@
+This recipe shows how to redefine functions and macros. Our example will show
+how to emulate the [`include_guard`] command, which is built-in since CMake
+3.10, on systems running an older version of CMake.
+
+[`include_guard`]: https://cmake.org/cmake/help/latest/command/include_guard.html
diff --git a/chapter-07/recipe-06/README.md b/chapter-07/recipe-06/README.md
@@ -1,5 +1,7 @@
 # Deprecating functions, macros, and variables
 
-Abstract to be written ...
+We will show how to deprecate CMake functions, macros, and variables. This can
+be quite helpful when modernizing your CMake-based build system.
+
 
 - [example](example/)
diff --git a/chapter-07/recipe-06/abstract.md b/chapter-07/recipe-06/abstract.md
@@ -0,0 +1,2 @@
+We will show how to deprecate CMake functions, macros, and variables. This can
+be quite helpful when modernizing your CMake-based build system.
diff --git a/chapter-07/recipe-07/README.md b/chapter-07/recipe-07/README.md
@@ -1,5 +1,10 @@
 # Limiting scope with `add_subdirectory`
 
-Abstract to be written ...
+This recipe discusses how to organize the CMake build system for large code
+projects. We will show how to use [`add_subdirectory`] to limit the scope of
+variables, lower CMake code complexity, and simplify maintenance.
+
+[`add_subdirectory`]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-07/recipe-07/abstract.md b/chapter-07/recipe-07/abstract.md
@@ -0,0 +1,5 @@
+This recipe discusses how to organize the CMake build system for large code
+projects. We will show how to use [`add_subdirectory`] to limit the scope of
+variables, lower CMake code complexity, and simplify maintenance.
+
+[`add_subdirectory`]: https://cmake.org/cmake/help/latest/command/add_subdirectory.html
diff --git a/chapter-07/recipe-08/README.md b/chapter-07/recipe-08/README.md
@@ -1,5 +1,12 @@
 # Avoiding global variables using `target_sources`
 
-Abstract to be written ...
+This recipe discusses an alternative way to organize the CMake build system for large code
+projects. We will show how to use [`target_sources`] and [`include`] to limit the scope of
+variables, lower CMake code complexity, and simplify maintenance.
+We will compare this approach with the one taken in [Recipe 7](../recipe-07)
+
+[`target_sources`]: https://cmake.org/cmake/help/latest/command/target_sources.html
+[`include`]: https://cmake.org/cmake/help/latest/command/include.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-07/recipe-08/abstract.md b/chapter-07/recipe-08/abstract.md
@@ -0,0 +1,7 @@
+This recipe discusses an alternative way to organize the CMake build system for large code
+projects. We will show how to use [`target_sources`] and [`include`] to limit the scope of
+variables, lower CMake code complexity, and simplify maintenance.
+We will compare this approach with the one taken in [Recipe 7](../recipe-07)
+
+[`target_sources`]: https://cmake.org/cmake/help/latest/command/target_sources.html
+[`include`]: https://cmake.org/cmake/help/latest/command/include.html
diff --git a/chapter-07/recipe-09/README.md b/chapter-07/recipe-09/README.md
@@ -1,5 +1,7 @@
 # Organizing Fortran projects
 
-Abstract to be written ...
+The example in this recipe shows how to use CMake to organize the build system
+for a Fortran project.
+
 
 - [fortran-example](fortran-example/)
diff --git a/chapter-07/recipe-09/abstract.md b/chapter-07/recipe-09/abstract.md
@@ -0,0 +1,2 @@
+The example in this recipe shows how to use CMake to organize the build system
+for a Fortran project.
diff --git a/chapter-09/recipe-01/README.md b/chapter-09/recipe-01/README.md
@@ -1,6 +1,8 @@
 # Building Fortran projects that use C/C++ libraries
 
-Abstract to be written ...
+We will show how CMake can be used for a mixed-language project where a Fortran
+executable uses libraries written in C or C++.
+
 
 - [fortran-c-example](fortran-c-example/)
 - [fortran-cxx-example](fortran-cxx-example/)

diff --git a/chapter-09/recipe-01/abstract.md b/chapter-09/recipe-01/abstract.md
@@ -0,0 +1,2 @@
+We will show how CMake can be used for a mixed-language project where a Fortran
+executable uses libraries written in C or C++.
diff --git a/chapter-09/recipe-02/README.md b/chapter-09/recipe-02/README.md
@@ -1,5 +1,10 @@
 # Building C/C++ projects that use Fortran libraries
 
-Abstract to be written ...
+This recipe is complementary to the [Recipe 1](../recipe-01). We will show how a C/C++ project
+can use Fortran libraries with CMake taking care of name mangling and compiler ABI compatibility.
+This will be achieved using the [`FortranCInterface`] standard CMake module.
+
+[`FortranCInterface`]: https://cmake.org/cmake/help/latest/module/FortranCInterface.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-09/recipe-02/abstract.md b/chapter-09/recipe-02/abstract.md
@@ -0,0 +1,5 @@
+This recipe is complementary to the [Recipe 1](../recipe-01). We will show how a C/C++ project
+can use Fortran libraries with CMake taking care of name mangling and compiler ABI compatibility.
+This will be achieved using the [`FortranCInterface`] standard CMake module.
+
+[`FortranCInterface`]: https://cmake.org/cmake/help/latest/module/FortranCInterface.html
diff --git a/chapter-09/recipe-03/README.md b/chapter-09/recipe-03/README.md
@@ -1,5 +1,9 @@
 # Building C++ and Python projects using Cython
 
-Abstract to be written ...
+We will show how to build a project extending Python using C++ and Cython with CMake.
+We will use the [`UseCython`] non-standard module.
+
+[`UseCython`]: https://github.com/thewtex/cython-cmake-example/tree/master/cmake
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-09/recipe-03/abstract.md b/chapter-09/recipe-03/abstract.md
@@ -0,0 +1,4 @@
+We will show how to build a project extending Python using C++ and Cython with CMake.
+We will use the [`UseCython`] non-standard module.
+
+[`UseCython`]: https://github.com/thewtex/cython-cmake-example/tree/master/cmake
diff --git a/chapter-09/recipe-04/README.md b/chapter-09/recipe-04/README.md
@@ -1,5 +1,9 @@
 # Building C++ and Python projects using Boost.Python
 
-Abstract to be written ...
+We will show an alternative methodology of extending Python with C++ using [Boost Python] and how
+such a project can be easily handled with CMake.
+
+[Boost Python]: https://www.boost.org/doc/libs/1_68_0/libs/python/doc/html/index.html
+
 
 - [cxx-example](cxx-example/)
diff --git a/chapter-09/recipe-04/abstract.md b/chapter-09/recipe-04/abstract.md
@@ -0,0 +1,4 @@
+We will show an alternative methodology of extending Python with C++ using [Boost Python] and how
+such a project can be easily handled with CMake.
+
+[Boost Python]: https://www.boost.org/doc/libs/1_68_0/libs/python/doc/html/index.html
diff --git a/chapter-09/recipe-05/README.md b/chapter-09/recipe-05/README.md
@@ -1,5 +1,12 @@
 # Building C++ and Python projects using pybind11
 
-Abstract to be written ...
+This recipe is yet another alternative example of extending Python with C++.
+This time we will leverage the [pybind11] project, which requires C++11, at
+least.
+Our example will retrieve [pybind11] using [`FetchContent`]
+
+[pybind11]: https://pybind11.readthedocs.io/en/stable/
+[`FetchContent`]: https://cmake.org/cmake/help/latest/module/FetchContent.html
+
 
 - [cxx-example](cxx-example/)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Running a custom command at build time: II. Using `add_custom_target`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Elaborating on [Recipe 7 in Chapter 5](../../chapter-05/recipe-07), we will show
		how to write a function to test and set compiler flags for your project.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		We will show how to deprecate CMake functions, macros, and variables. This can
		be quite helpful when modernizing your CMake-based build system.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		The example in this recipe shows how to use CMake to organize the build system
		for a Fortran project.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		We will show how CMake can be used for a mixed-language project where a Fortran
		executable uses libraries written in C or C++.