generate recipe readmes

chapter-01/recipe-01/README.md

@@ -1,94 +1,10 @@
 # Compiling a single source file into an executable
 
-These recipes shows how to run CMake to configure and build a simple project. The project consists of a single source file for a single executable.
-The same project is presented in C++, C and Fortran 90.
+These recipes show how to run CMake to configure and build a simple project.
+The project consists of a single source file for a single executable.  The same
+project is presented in C++, C and Fortran 90.
 
-## Ingredients
 
-- A C++ (or C or Fortran 90) compiler
-- CMake, any version higher than 3.0
-
-## Contents of `CMakeLists.txt`
-
-All that’s needed to configure and build this minimal project on GNU/Linux, Mac OS X and Windows is the following:
-
-```
-cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
-
-project(recipe-01 LANGUAGES CXX)
-
-add_executable(hello-world hello-world.cpp)
-```
-
-```
-cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
-```
-The first line sets a minimum required version for CMake. A fatal error will be issued if a version of CMake lower than that will be used.
-```
-project(recipe-01 LANGUAGES CXX)
-```
-The second line declares the name of the project, `recipe-0001`, and the project’s language.
-C++ is the default programming language, but we suggest to always explicitly state the project’s language in the `project` command.
-```
-add_executable(hello-world hello-world.cpp)
-```
-Eventually, we instruct CMake to generate the executable named `hello-world` by compiling and linking the source file `hello-world.cpp`.
-CMake will use default compiler and linker settings.
-
-## Configure
-
-Once in the directory containing the `CMakeLists.txt` file, simply run:
-```
-cmake .
-```
-CMake will output a series of status messages informing you on the configuration:[^1]
-```
--- The CXX compiler identification is GNU 5.4.0
--- Check for working CXX compiler: /home/roberto/.nix-profile/bin/c++
--- Check for working CXX compiler: /home/roberto/.nix-profile/bin/c++ -- works
--- Detecting CXX compiler ABI info
--- Detecting CXX compiler ABI info - done
--- Detecting CXX compile features
--- Detecting CXX compile features - done
--- Configuring done
--- Generating done
--- Build files have been written to: /home/roberto/Workspace/robertodr/cmake-recipes/recipe-0001
-```
-Notice that CMake wrote all the files it generated at the **root** of the project. This is an _in-source build_ and is generally undesirable,
-as it mixes the source and the build tree of the project. Fortunately, it is very easy to instruct CMake to generate its files for
-an _out-of-source_ build:
-```
-cmake -H. -Bbuild
-```
-will configure the project and save the generated files in the `build` directory.
-CMake has additional mechanism to ensure that a build is out-of-source, see [recipe-XYZU](recipe-XYZU/README.md)
-
-### What kind of configuration was generated?
-
-CMake is a build system _generator_. You describe what type of operations the build system, _e.g._ Unix Makefiles, Ninja, Visual Studio, etc.,
-will have to run to get your code compiled. In turn, CMake _generates_ the corresponding instructions for the chosen build system.
-By default, on GNU/Linux and Mac OS X systems, CMake employs the Unix Makefiles generator. On Windows, _what is used by default on Windows?_
-
-On GNU/Linux, CMake will by default generate Unix Makefiles to build the project:
-- `Makefile`. The set of instructions that `make` will run to build the project.
-- `CMakeFiles/`. Contains temporary files, used by CMake for detecting the OS, compiler, etc.
-   In addition, depending on the chosen _generator_ it also contains project-specific files.
-- `cmake_install.cmake`. _What is this?_
-- `CMakeCache.txt`. The CMake cache, as the file name suggests. This file is used by CMake when re-running the configuration.
-
-## Build
-
-We can now build by running:
-```
-cmake --build .
-```
-which wraps the native build command for the chosen _generator_ (`make`, in this case).
-The corresponding build output to screen:
-```
-Scanning dependencies of target hello-world
-[ 50%] Building CXX object CMakeFiles/hello-world.dir/hello-world.cpp.o
-[100%] Linking CXX executable hello-world
-[100%] Built target hello-world
-```
-
-[^1] This output was obtained with CMake version 3.7.2
+- [c-example](c-example/)
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-02/README.md

@@ -1,30 +1,28 @@
 # Switching Generators
 
-A single `CMakeLists.txt` can be used to configure projects for different toolstacks on different platforms.
-CMake is a build system _generator_. starting from a description of the operations the build system, _e.g._ Unix Makefiles, Ninja, Visual Studio, etc.,
-will have to run to get your code compiled, CMake _generates_ the corresponding instructions for the chosen build system.
+A single `CMakeLists.txt` can be used to configure projects for different
+toolstacks on different platforms.  CMake is a build system _generator_.
+Starting from a description of the operations the build system, _e.g._ Unix
+Makefiles, Ninja, Visual Studio, etc., will have to run to get your code
+compiled, CMake _generates_ the corresponding instructions for the chosen build
+system.
 
-CMake supports an [extensive list](https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html) of native build tools for the different platforms. It is possible to get a list of
-the available ones for the currently installed version of CMake on the current platform by running:
+CMake supports an [extensive
+list](https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html) of
+native build tools for the different platforms. It is possible to get a list of
+the available ones for the currently installed version of CMake on the current
+platform by running:
 ```
 cmake --help
 ```
-This recipe builds upon [recipe-0001](../recipe-0001/README.md) to show how to achieve this on GNU/Linux, Mac OS X and Windows.
 
-## Ingredients
+As an example, to use the Ninja generator, configure with:
 
-- A C++ compiler.
-- CMake, any version higher than 3.0.
-- A GNU/Linux system with `make` and Ninja installed.
-- A Mac OS X system with `make` and Ninja installed.
-- A Windows system with Visual Studio, MinGW and Ninja installed.
-
-## Configure
-
-The default generators are:
-- Unix Makefiles on GNU/Linux
-- Unix Makefiles on Mac OS X
-- FIXME on Windows
 ```
 cmake -H. -Bbuild -GNinja
 ```
+
+
+- [c-example](c-example/)
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-03/README.md

@@ -1 +1,7 @@
 # Building and Linking Static and Shared Libraries
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)
+- [cxx-objlib-example](cxx-objlib-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-04/README.md

@@ -1,2 +1,5 @@
 # Controlling Compilation with Conditionals
 
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-01/recipe-05/README.md

@@ -1 +1,5 @@
 # How to Present Options to the User
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-01/recipe-06/README.md

@@ -1 +1,7 @@
 # How to Specify the Compiler
+
+Abstract to be written ...
+
+- [c-example](c-example/)
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-07/README.md

@@ -1 +1,7 @@
 # Switching the Build Type
+
+Abstract to be written ...
+
+- [c-example](c-example/)
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-08/README.md

@@ -2,45 +2,7 @@
 
 This recipe shows how to set compiler flags for targets using
 `target_compile_options()`. The compiler options set are only valid for GCC and
-Clang, thus building this project **fails**  on Visual Studio.
+Clang, thus building this project **fails** on Visual Studio.
 
-The ideal way of setting compiler flags:
-- Define a set of `${PROJECT_NAME}_<LANG>_FLAGS_<CONFIG>`. These will be your
-  own flags for the project.
-  Notice that it is possible to add your own build types. [See here](https://stackoverflow.com/a/11437693)
 
-If using C++ or C, use the mechanism, available in CMake 3.1 and later,
-to set the language standard and the features:
-- Set compiler flags for the language standard using
-  ```
-  set_target_properties(foo
-    PROPERTIES
-      CXX_STANDARD 11
-      CXX_EXTENSIONS OFF
-      CXX_STANDARD_REQUIRED ON
-    )
-  ```
-- Request features, with the `PUBLIC`, `PRIVATE` and `INTERFACE` specifiers
-  ```
-  target_compile_features(foo
-    PUBLIC
-      cxx_strong_enums
-    PRIVATE
-      cxx_lambdas
-      cxx_range_for
-    )
-  ```
-  This makes explicit what is needed to build and to use the target. Moreover,
-  CMake has a nice mechanism to take care of optional compile features.
-- Set compiler flags per target `target_compile_options()` using `PUBLIC`,
-  `PRIVATE`, `INTERFACE` and _generator expressions_
-  ```
-  target_compile_options(foo
-    PRIVATE
-      "$<$<CONFIG:DEBUG>:${${PROJECT_NAME}_<LANG>_FLAGS_DEBUG}>"
-  )
-  target_compile_options(foo
-    PRIVATE
-      "$<$<CONFIG:RELEASE>:${${PROJECT_NAME}_<LANG>_FLAGS_RELEASE}>"
-  )
-  ```
+- [cxx-example](cxx-example/)

chapter-01/recipe-09/README.md

@@ -1,11 +1,6 @@
 # Setting the Standard for the Language
 
-**WARNING**
-
-These recipes require at least CMake 3.1 to work properly since they introduce the following CMake variables:
-- CMAKE_CXX_STANDARD
-- CMAKE_CXX_STANDARD_REQUIRED
-- CMAKE_CXX_EXTENSIONS
-- CMAKE_C_STANDARD
-- CMAKE_C_STANDARD_REQUIRED
+Abstract to be written ...
 
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-01/recipe-10/README.md

@@ -1 +1,5 @@
 # Using Control Flow Constructs
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-02/recipe-01/README.md

@@ -1 +1,5 @@
 # Discovering the operating system
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-02/recipe-02/README.md

@@ -1 +1,5 @@
 # Dealing with platform-dependent source code
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-02/recipe-03/README.md

@@ -1 +1,6 @@
 # Dealing with compiler-dependent source code
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-02/recipe-04/README.md

@@ -1 +1,5 @@
 # Discovering the host processor architecture
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-02/recipe-05/README.md

@@ -1 +1,5 @@
 # Discovering the host processor instruction set
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-02/recipe-06/README.md

@@ -1 +1,5 @@
 # Enabling vectorization for the Eigen library
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-03/recipe-01/README.md

@@ -1 +1,5 @@
 # Detecting the Python Interpreter
+
+Abstract to be written ...
+
+- [fortran-example](fortran-example/)

chapter-03/recipe-02/README.md

@@ -3,3 +3,6 @@
 Code example copy-pasted from the Python docs on embedding:
 - For Python 2.7 https://docs.python.org/2.7/extending/embedding.html
 - For Python 3.5 https://docs.python.org/3.5/extending/embedding.html
+
+
+- [c-example](c-example/)

chapter-03/recipe-03/README.md

@@ -1,3 +1,6 @@
 # Detecting Python Modules
 
 To test run: `./pure-embedding use_numpy print_ones 15 34`
+
+
+- [cxx-example](cxx-example/)

chapter-03/recipe-04/README.md

@@ -1 +1,5 @@
 # Detecting the BLAS and LAPACK Math Libraries
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-03/recipe-05/README.md

@@ -1,3 +1,6 @@
 # Detecting the OpenMP Parallel Environment
 
-- FindOpenMP.cmake added support for Fortran in version 3.1
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)
+- [fortran-example](fortran-example/)

chapter-03/recipe-06/README.md

@@ -1 +1,7 @@
 # Detecting the MPI Parallel Environment
+
+Abstract to be written ...
+
+- [c-example](c-example/)
+- [c-example-3.5](c-example-3.5/)
+- [cxx-example](cxx-example/)

chapter-03/recipe-07/README.md

@@ -1,3 +1,7 @@
 # Detecting the Eigen Library
 
 Show how to use the Eigen library and link to BLAS/LAPACK.
+
+
+- [cxx-example](cxx-example/)
+- [cxx-example-3.5](cxx-example-3.5/)

chapter-03/recipe-08/README.md

@@ -1 +1,5 @@
 # Detecting the Boost Libraries
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-03/recipe-09/README.md

@@ -1,3 +1,7 @@
 # Detecting the HDF5 Libraries
 
-Fortran example will cover how to discover if the Fortran 2003 interface was compiled or not showing the `try_compile` command.
+Fortran example will cover how to discover if the Fortran 2003 interface was
+compiled or not showing the `try_compile` command.
+
+
+- [fortran-example](fortran-example/)

chapter-03/recipe-10/README.md

@@ -1 +1,6 @@
 # Writing CMake Code to Detect External Libraries
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)
+- [cxx-example-3.5](cxx-example-3.5/)

chapter-04/recipe-01/README.md

@@ -1 +1,5 @@
 # Creating a simple unit test example
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-04/recipe-02/README.md

@@ -1 +1,5 @@
 # Define a unit test using the Catch2 library
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-04/recipe-03/README.md

@@ -1 +1,5 @@
 # Define a unit test and link against Google test
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-04/recipe-04/README.md

@@ -1 +1,5 @@
 # Define a unit test and link against Boost test
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-04/recipe-05/README.md

@@ -1 +1,5 @@
 # Dynamic analysis to detect memory defects
+
+Abstract to be written ...
+
+- [cxx-example](cxx-example/)

chapter-04/recipe-06/README.md

@@ -1 +1,5 @@
 # Testing expected failures
+
+Abstract to be written ...
+
+- [example](example/)