From e57bd42e49e2bf93e535c8346d55bbfd3d7a75e3 Mon Sep 17 00:00:00 2001
From: "Joachim Wuttke (h)" <j.wuttke@fz-juelich.de>
Date: Wed, 2 Aug 2023 13:17:41 +0200
Subject: [PATCH] Shorten Unix build instructions

---
 .../building/unix/build-and-install.md        | 99 ++++++-------------
 .../installation/building/unix/third-party.md |  4 +-
 2 files changed, 30 insertions(+), 73 deletions(-)

diff --git a/hugo/content/installation/building/unix/build-and-install.md b/hugo/content/installation/building/unix/build-and-install.md
index 463ecc926d0..7fe100f72ed 100644
--- a/hugo/content/installation/building/unix/build-and-install.md
+++ b/hugo/content/installation/building/unix/build-and-install.md
@@ -18,86 +18,43 @@ it takes the following commands to build and install the software:
 
 ```bash
 $ cd <source_dir>
-$ mkdir build
+$ mkdir build # see note [1]
 $ cd build
-$ cmake [<options>] ..
-$ make -j4
+$ cmake [<options>] .. # see note [4]
+$ make -j4  # see note [2]
 $ ctest -j4
+$ make install # see note [3]
 ```
 
-The last step, which should be done *only* for linheinz and libformfactor:
-```bash
-$ sudo make install
-```
-
-These steps shall now be explained in more detail.
-
-#### Dedicated build directory
-
-```bash
-$ mkdir build
-$ cd build
-```
-
-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> ..
-```
-
-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:
+##### Note [1]: Build directory
 
-```bash
-$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DCMAKE_INSTALL_PREFIX=<install_dir> ..
-```
-
-**For MacOS & Homebrew users**
-```
-cmake -DCMAKE_PREFIX_PATH=/usr/local -DCMAKE_INSTALL_PREFIX=<install_dir> ..
-```
-
-#### The compilation
-
-```bash
-$ make -j4
-```
+The build process must take place "out of place", i.e. not directly in the source directory.
+Otherwise, location and name of the build directory are arbitrary.
+We nonetheless recommend to follow our convention,
+create a subdirectory under the source directory, and call it `build`.
 
-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.
+##### Note [2]: Make or Ninja
 
-#### Testing the build
+With GNU Make, the option `-j<n>` indicates the number of processors to be used in parallel.
 
-```bash
-$ ctest -j4
-...
-100% tests passed, 0 tests failed out of 61
-Total Test time (real) = 31.14 sec
-[100%] Build target check
-```
+In our experience, the alternative build software `Ninja` is faster and therefore to be preferred.
+To use Ninja,
+  * install it (e.g. Debian package ninja-build)
+  * call `cmake` with option `-GNinja`
+  * replace calls of `make -j<n>` by `ninja`.
 
-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.
+##### Note [3]: Install location
 
-#### Installing linheinz and libformfactor
+The install directory can be specified by suppling the option
+`-DCMAKE_INSTALL_PREFIX=<install_dir>` to the `cmake` command.
+Depending on the choice of the installation directory,
+it may or may not be necessary to run the command `make install`
+(or `ninja install`) under `sudo`.
 
-```bash
-$ sudo make install
-```
+##### Note [4]: Other CMake options
 
-The last command copies the compiled software into the installation
-directory `<install_dir>`, which has been specified earlier on during
-the CMake configuration.
+Besides the `cmake` options already mentioned, you may need
+`-DCMAKE_PREFIX_PATH=<paths>`
+where `<paths>` is a semicolon-separated list of directories
+specifying directories that are searched by CMake for
+the libraries and auxiliary programs that are needed for building BornAgain.
diff --git a/hugo/content/installation/building/unix/third-party.md b/hugo/content/installation/building/unix/third-party.md
index ced22bd7ee4..b3759a48f4e 100644
--- a/hugo/content/installation/building/unix/third-party.md
+++ b/hugo/content/installation/building/unix/third-party.md
@@ -83,9 +83,9 @@ brew install git cmake fftw gsl libcerf python boost libtiff qt6
 pip3 install matplotlib numpy
 ```
 
-Homebrew installs all packages to <pre>/usr/local</pre>. Possibly,
+Homebrew installs all packages to `/usr/local`. Possibly,
 this path has to be passed to CMake using the argument `-DCMAKE_PREFIX_PATH`
-(see the [build instructions]({{% relref "installation/building/unix/build-and-install" %}}).
+(see the [build instructions]({{% relref "installation/building/unix/build-and-install" %}})).
 
 Add Qt to your path environment variable:
 ```
-- 
GitLab