Skip to content

Commit d6ef39b

Browse files
robertodrrobertodr
authored
Merge pull request #495 from bast/abstracts-6-8-10
Abstracts for chapters 6, 8, and 10
2 parents 272be6b + 384c32b commit d6ef39b

File tree

32 files changed

+179
-33
lines changed

32 files changed

+179
-33
lines changed

‎chapter-06/recipe-01/README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Generating sources at configure time
22

3-
Abstract to be written ...
3+
In this and some of the following recipes, we will illustrate how to generate a
4+
simple source file at configure time. The example generated source file defines
5+
a function to report the build system configuration.
6+
47

58
- [fortran-c-example](fortran-c-example/)

‎chapter-06/recipe-01/abstract.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
In this and some of the following recipes, we will illustrate how to generate a
2+
simple source file at configure time. The example generated source file defines
3+
a function to report the build system configuration.

‎chapter-06/recipe-02/README.md

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,28 @@
11
# Generating source code at configure time using Python
22

33
In this recipe, we generate `print_info.c` from the template `print_info.c.in`
4-
by emulating the CMake function `configure_file` with a custom Python script.
4+
by emulating the CMake function
5+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
6+
with a custom Python script.
57

68
The goal of this recipe is to learn how we can generate source code at
79
configure time.
810

911
We should point out that this recipe has a serious limitation and cannot
10-
emulate `configure_file` fully. The approach that we present here cannot
11-
generate an automatic dependency which would regenerate `print_info.c` at build
12-
time. In other words, if you remove the generated `print_info.c` after the
13-
configure step, this file will not be regenerated and the build step will fail.
14-
To proper mimic the behavior of `configure_file` we would
15-
require `add_custom_command` and `add_custom_target`, which we will use in the
16-
subsequent recipe 3, *Generating source code at build time using Python*, where
17-
we will overcome this limitation.
12+
emulate
13+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
14+
fully. The approach that we present here cannot generate an automatic
15+
dependency which would regenerate `print_info.c` at build time. In other words,
16+
if you remove the generated `print_info.c` after the configure step, this file
17+
will not be regenerated and the build step will fail. To proper mimic the
18+
behavior of
19+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
20+
we would require
21+
[`add_custom_command`](https://cmake.org/cmake/help/latest/command/add_custom_command.html)
22+
and
23+
[`add_custom_target`](https://cmake.org/cmake/help/latest/command/add_custom_target.html),
24+
which we will use in the subsequent [Recipe 3, *Generating source code at build
25+
time using Python*](../recipe-03), where we will overcome this limitation.
1826

1927

2028
- [fortran-c-example](fortran-c-example/)

‎chapter-06/recipe-02/abstract.md

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,23 @@
11
In this recipe, we generate `print_info.c` from the template `print_info.c.in`
2-
by emulating the CMake function `configure_file` with a custom Python script.
2+
by emulating the CMake function
3+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
4+
with a custom Python script.
35

46
The goal of this recipe is to learn how we can generate source code at
57
configure time.
68

79
We should point out that this recipe has a serious limitation and cannot
8-
emulate `configure_file` fully. The approach that we present here cannot
9-
generate an automatic dependency which would regenerate `print_info.c` at build
10-
time. In other words, if you remove the generated `print_info.c` after the
11-
configure step, this file will not be regenerated and the build step will fail.
12-
To proper mimic the behavior of `configure_file` we would
13-
require `add_custom_command` and `add_custom_target`, which we will use in the
14-
subsequent recipe 3, *Generating source code at build time using Python*, where
15-
we will overcome this limitation.
10+
emulate
11+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
12+
fully. The approach that we present here cannot generate an automatic
13+
dependency which would regenerate `print_info.c` at build time. In other words,
14+
if you remove the generated `print_info.c` after the configure step, this file
15+
will not be regenerated and the build step will fail. To proper mimic the
16+
behavior of
17+
[`configure_file`](https://cmake.org/cmake/help/latest/command/configure_file.html)
18+
we would require
19+
[`add_custom_command`](https://cmake.org/cmake/help/latest/command/add_custom_command.html)
20+
and
21+
[`add_custom_target`](https://cmake.org/cmake/help/latest/command/add_custom_target.html),
22+
which we will use in the subsequent [Recipe 3, *Generating source code at build
23+
time using Python*](../recipe-03), where we will overcome this limitation.

‎chapter-06/recipe-03/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Generating source code at build time using Python
22

3-
Abstract to be written ...
3+
In this example, we generate C++ code
4+
by using Python at build time.
5+
46

57
- [cxx-example](cxx-example/)

‎chapter-06/recipe-03/abstract.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
In this example, we generate C++ code
2+
by using Python at build time.

‎chapter-06/recipe-04/README.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# Recording the project version information for reproducibility
22

3-
Abstract to be written ...
3+
In this example, we define the project version number inside of the CMake
4+
sources. Our goal is to record the program version to a header file at the
5+
moment when we configure the project. The generated header file can then be
6+
included in the code at the right place and time, to print the code version to
7+
the output file(s) or screen.
8+
49

510
- [c-example](c-example/)
611
- [fortran-example](fortran-example/)

‎chapter-06/recipe-04/abstract.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
In this example, we define the project version number inside of the CMake
2+
sources. Our goal is to record the program version to a header file at the
3+
moment when we configure the project. The generated header file can then be
4+
included in the code at the right place and time, to print the code version to
5+
the output file(s) or screen.

‎chapter-06/recipe-05/README.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
# Recording the project version from a file
22

3-
Abstract to be written ...
3+
The goal of this recipe is similar to [Recipe 4, *Recording the project version information for reproducibility*](../recipe-04),
4+
but the starting point is different; our plan is to read the version information from a
5+
file, rather than setting it inside of `CMakeLists.txt`.
6+
7+
The motivation for keeping the version in a separate file, outside of CMake
8+
sources, is to allow other build frameworks or development tools to use the
9+
information, independent of CMake, without duplicating the information in
10+
several files.
11+
412

513
- [cxx-example](cxx-example/)

‎chapter-06/recipe-05/abstract.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
The goal of this recipe is similar to [Recipe 4, *Recording the project version information for reproducibility*](../recipe-04),
2+
but the starting point is different; our plan is to read the version information from a
3+
file, rather than setting it inside of `CMakeLists.txt`.
4+
5+
The motivation for keeping the version in a separate file, outside of CMake
6+
sources, is to allow other build frameworks or development tools to use the
7+
information, independent of CMake, without duplicating the information in
8+
several files.

‎chapter-06/recipe-06/README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Recording the Git hash at configure time
22

3-
Abstract to be written ...
3+
The Git hash of a commit uniquely determines the state of the source code in a
4+
Git repository. Therefore, to uniquely brand the executable, we will burn the
5+
Git hash into the executable by recording the hash string in a header file that
6+
can be included and used at the right place in the code.
7+
48

59
- [cxx-example](cxx-example/)

‎chapter-06/recipe-06/abstract.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
The Git hash of a commit uniquely determines the state of the source code in a
2+
Git repository. Therefore, to uniquely brand the executable, we will burn the
3+
Git hash into the executable by recording the hash string in a header file that
4+
can be included and used at the right place in the code.

‎chapter-06/recipe-07/README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Recording the Git hash at build time
22

3-
Abstract to be written ...
3+
In [Recipe 6, *Recording the Git hash at configure time*](../recipe-06),
4+
we recorded the state of the code repository
5+
(Git hash) at configure time. In this recipe, we wish to go a step further and
6+
demonstrate how to record the Git hash (or, generally, perform other actions)
7+
at build time, to make sure that these actions are run every time we build the
8+
code, since we may configure only once but build several times.
9+
410

511
- [cxx-example](cxx-example/)

‎chapter-06/recipe-07/abstract.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
In [Recipe 6, *Recording the Git hash at configure time*](../recipe-06),
2+
we recorded the state of the code repository
3+
(Git hash) at configure time. In this recipe, we wish to go a step further and
4+
demonstrate how to record the Git hash (or, generally, perform other actions)
5+
at build time, to make sure that these actions are run every time we build the
6+
code, since we may configure only once but build several times.

‎chapter-08/recipe-01/README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Using the superbuild pattern
22

3-
Abstract to be written ...
3+
This recipe introduces the superbuild pattern with a very simple example. We
4+
will show how to use the
5+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject.html)
6+
command to build a simple "Hello, World" program.
7+
48

59
- [cxx-example](cxx-example/)

‎chapter-08/recipe-01/abstract.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
This recipe introduces the superbuild pattern with a very simple example. We
2+
will show how to use the
3+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject.html)
4+
command to build a simple "Hello, World" program.

‎chapter-08/recipe-02/README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Managing dependencies with a superbuild: I. The Boost libraries
22

3-
Abstract to be written ...
3+
This recipe shows how to leverage the superbuild pattern to ship your code with
4+
the confidence that a missing dependency will not stop the configuration. We
5+
will reuse the code example from [Recipe 8 in Chapter
6+
3](../../chapter-03/recipe-08), but reorganize it in the form of a superbuild.
7+
48

59
- [cxx-example](cxx-example/)

‎chapter-08/recipe-02/abstract.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
This recipe shows how to leverage the superbuild pattern to ship your code with
2+
the confidence that a missing dependency will not stop the configuration. We
3+
will reuse the code example from [Recipe 8 in Chapter
4+
3](../../chapter-03/recipe-08), but reorganize it in the form of a superbuild.

‎chapter-08/recipe-03/README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Managing dependencies with a superbuild: II. The FFTW library
22

3-
Abstract to be written ...
3+
In this recipe we show
4+
how to download, build, and install the
5+
[FFTW library](http://www.fftw.org) using a superbuild.
6+
47

58
- [c-example](c-example/)

‎chapter-08/recipe-03/abstract.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
In this recipe we show
2+
how to download, build, and install the
3+
[FFTW library](http://www.fftw.org) using a superbuild.

‎chapter-08/recipe-04/README.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# Managing dependencies with a superbuild: III. The Google Test framework
22

3-
Abstract to be written ...
3+
In this recipe we reuse the code from [Recipe 3 in Chapter 4](../../chapter-04/recipe-03)
4+
and fetch and build the [Google Test](https://github.com/google/googletest) framework
5+
using [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html),
6+
which provides a compact and
7+
versatile module to assemble project dependencies at configure time. For additional insight
8+
and for CMake below 3.11, we will also discuss how to emulate [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) using
9+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject_Add.html)
10+
at configure time.
11+
412

513
- [cxx-example](cxx-example/)
614
- [cxx-example-3.5](cxx-example-3.5/)

‎chapter-08/recipe-04/abstract.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
In this recipe we reuse the code from [Recipe 3 in Chapter 4](../../chapter-04/recipe-03)
2+
and fetch and build the [Google Test](https://github.com/google/googletest) framework
3+
using [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html),
4+
which provides a compact and
5+
versatile module to assemble project dependencies at configure time. For additional insight
6+
and for CMake below 3.11, we will also discuss how to emulate [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) using
7+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject_Add.html)
8+
at configure time.

‎chapter-08/recipe-05/README.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Managing your project as a superbuild
22

3-
Abstract to be written ...
3+
This recipe shows how to use
4+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject_Add.html)
5+
to handle dependencies available from open source Git repositories.
6+
7+
As an example we will build a project which depends on https://github.com/dev-cafe/message.
8+
49

510
- [cxx-example](cxx-example/)

‎chapter-08/recipe-05/abstract.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This recipe shows how to use
2+
[`ExternalProject_Add`](https://cmake.org/cmake/help/latest/module/ExternalProject_Add.html)
3+
to handle dependencies available from open source Git repositories.
4+
5+
As an example we will build a project which depends on https://github.com/dev-cafe/message.

‎chapter-10/recipe-01/README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Installing your project
22

3-
Abstract to be written ...
3+
This recipe demonstrates how to install files, libraries, and executables.
4+
5+
In this recipe, we introduce a small example project which is used in the
6+
remaining recipes of this chapter.
7+
48

59
- [cxx-example](cxx-example/)

‎chapter-10/recipe-01/abstract.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
This recipe demonstrates how to install files, libraries, and executables.
2+
3+
In this recipe, we introduce a small example project which is used in the
4+
remaining recipes of this chapter.

‎chapter-10/recipe-02/README.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Generating export headers
22

3-
Abstract to be written ...
3+
In this recipe we wish to:
4+
- Build both a shared and static library from the same set of source files.
5+
- Ensure that only the visibility of symbols in the shared library is properly delimited.
6+
7+
To demonstrate this, we revisit [Recipe 3 in Chapter 1](../../chapter-01/recipe-03).
8+
49

510
- [cxx-example](cxx-example/)

‎chapter-10/recipe-02/abstract.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
In this recipe we wish to:
2+
- Build both a shared and static library from the same set of source files.
3+
- Ensure that only the visibility of symbols in the shared library is properly delimited.
4+
5+
To demonstrate this, we revisit [Recipe 3 in Chapter 1](../../chapter-01/recipe-03).

‎chapter-10/recipe-03/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Exporting your targets
22

3-
Abstract to be written ...
3+
This recipe shows how CMake can let us export our targets so
4+
that other projects using CMake can pick them up easily.
5+
46

57
- [cxx-example](cxx-example/)

‎chapter-10/recipe-03/abstract.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
This recipe shows how CMake can let us export our targets so
2+
that other projects using CMake can pick them up easily.

‎chapter-10/recipe-04/README.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Installing a superbuild project
22

3-
Abstract to be written ...
3+
This recipe shows how to install a superbuild which depends on a library which
4+
may or may not be available on the system.
5+
46

57
- [cxx-example](cxx-example/)

‎chapter-10/recipe-04/abstract.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
This recipe shows how to install a superbuild which depends on a library which
2+
may or may not be available on the system.

0 commit comments

Comments
 (0)