From a0e42a51204980dff9cfd75da847f20eaf750cd0 Mon Sep 17 00:00:00 2001
From: Joachim Wuttke <j.wuttke@fz-juelich.de>
Date: Tue, 15 Mar 2022 23:01:54 +0100
Subject: [PATCH] Update build-and-install

---
 .../building/unix/build-and-install.md        | 64 ++++++++++++++-----
 1 file changed, 47 insertions(+), 17 deletions(-)

diff --git a/hugo/content/installation/building/unix/build-and-install.md b/hugo/content/installation/building/unix/build-and-install.md
index a642acc2eb4..65bb4996c54 100644
--- a/hugo/content/installation/building/unix/build-and-install.md
+++ b/hugo/content/installation/building/unix/build-and-install.md
@@ -5,11 +5,21 @@ weight = 30
 
 ## Build and install BornAgain
 
-BornAgain comes with configuration files for the cross-platform build system [CMake](https://cmake.org/). Using CMake, it takes the following commands to build and install BornAgain:
+The following instructions must be executed for the three software projects
+- libheinz,
+- libformfactor,
+- BornAgain,
+in this order.
+
+Each source package comes with configuration files for the
+cross-platform build system [CMake](https://cmake.org/). Using CMake,
+it takes the following commands to build and install the software:
+
 ```bash
-$ mkdir <build_dir>
-$ cd <build_dir>
-$ cmake [<options>] <source_dir>
+$ cd <source_dir>
+$ mkdir build
+$ cd build
+$ cmake [<options>] ..
 $ make -j4
 $ ctest -j4
 $ sudo make install
@@ -20,36 +30,46 @@ These steps shall now be explained in more detail.
 #### Dedicated build directory
 
 ```bash
-$ mkdir <build_dir>
-$ cd <build_dir>
+$ mkdir build
+$ cd build
 ```
 
-The build process must take place in a dedicated directory <build_dir>. After the installation is complete, <build_dir> can be safely removed.
+The build process must take place in a dedicated directory,
+for which we suggest the canonical name `build`, and which
+should be a subdirectory of the software's source directory.
 
 #### CMake command for the build configuration
 
 ```bash
-$ cmake -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+$ cmake -DCMAKE_INSTALL_PREFIX=<install_dir> ..
 ```
 
-This command checks your system for the presence of the third party libraries necessary for compilation. In the case of a complex system setup, with libraries of different versions scattered across multiple places (/opt/local, /usr/local etc), you may want to help CMake in finding the correct library paths by running it with additional parameters:
+This command checks your system for the presence of the third party
+libraries necessary for compilation. In the case of a complex system
+setup, with libraries of different versions scattered across multiple
+places (/opt/local, /usr/local etc), you may want to help CMake in
+finding the correct library paths by running it with additional
+parameters:
 
 ```bash
-$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DCMAKE_INSTALL_PREFIX=<install_dir> ..
 ```
 
 {{< alert theme="info" >}}
 **Note for MacOS users**
 
-MacOS users who have installed third party libraries using the MacPorts package manager have to use an additional key during the CMake configuration to specify the location of MacPort's libraries (e.g. `/opt/local`):
+MacOS users who have installed third party libraries using the
+MacPorts package manager have to use an additional key during the
+CMake configuration to specify the location of MacPort's libraries
+(e.g. `/opt/local`):
 ```
-cmake -DCMAKE_PREFIX_PATH=/opt/local -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+cmake -DCMAKE_PREFIX_PATH=/opt/local -DCMAKE_INSTALL_PREFIX=<install_dir> ..
 ```
 
 
 **For Homebrew users**
 ```
-cmake -DCMAKE_PREFIX_PATH=/usr/local -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+cmake -DCMAKE_PREFIX_PATH=/usr/local -DCMAKE_INSTALL_PREFIX=<install_dir> ..
 ```
 {{< /alert >}}
 
@@ -58,7 +78,7 @@ cmake -DCMAKE_PREFIX_PATH=/usr/local -DCMAKE_INSTALL_PREFIX=<install_dir> <sourc
 
 Use additional CMake key during configuration
 ```
-cmake -DBORNAGAIN_USE_PYTHON3=OFF -DCMAKE_INSTALL_PREFIX=<install_dir> <source_dir>
+cmake -DBORNAGAIN_USE_PYTHON3=OFF -DCMAKE_INSTALL_PREFIX=<install_dir> ..
 ```
 {{< /alert >}}
 
@@ -68,7 +88,9 @@ cmake -DBORNAGAIN_USE_PYTHON3=OFF -DCMAKE_INSTALL_PREFIX=<install_dir> <source_d
 $ make -j4
 ```
 
-This command starts the compilation process with a maximum of 4 parallel threads. Depending on your CPU, you can increase this parameter (`-j[N]`) to decrease the compilation time.
+This command starts the compilation process with a maximum of 4
+parallel threads. Depending on your CPU, you can increase this
+parameter (`-j[N]`) to decrease the compilation time.
 
 #### Testing the build
 
@@ -80,11 +102,19 @@ Total Test time (real) = 31.14 sec
 [100%] Build target check
 ```
 
-Running the functional tests is an optional but recommended step. The command `ctest` will compile several additional tests and run them one by one. The option `-j[N]` uses up to `N` threads to run these tests in parallel. Every test contains the simulation of a typical sample and compares the result with a reference file. Having `100% tests passed` ensures that your local installation is correct.
+Running the functional tests is an optional but recommended step. The
+command `ctest` will compile several additional tests and run them one
+by one. The option `-j[N]` uses up to `N` threads to run these tests
+in parallel. Every test contains the simulation of a typical sample
+and compares the result with a reference file. Having `100% tests
+passed` ensures that your local installation is correct.
 
 #### Installing the framework
+
 ```bash
 $ sudo make install
 ```
 
-The last command copies the compiled libraries and usage examples into the installation directory `<install_dir>`, which has been specified earlier on during the CMake configuration.
+The last command copies the compiled software into the installation
+directory `<install_dir>`, which has been specified earlier on during
+the CMake configuration.
-- 
GitLab