diff --git a/.github/scripts/yamlheader.md b/.github/scripts/yamlheader.md deleted file mode 100644 index a37817e..0000000 --- a/.github/scripts/yamlheader.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -jupyter: - kernelspec: - display_name: Python 3 - language: python - name: python3 ---- - diff --git a/.gitignore b/.gitignore index a903838..ddd50d3 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ node_modules book.pdf *~ build +linkcheck # external repositories k4marlinwrapper/ diff --git a/conf.py b/conf.py index 936f28e..6366b0e 100644 --- a/conf.py +++ b/conf.py @@ -49,6 +49,6 @@ ) -myst_heading_anchors = 3 +myst_heading_anchors = 4 myst_enable_extensions = ["colon_fence"] diff --git a/developing-key4hep-software/WritingAlgorithms.md b/developing-key4hep-software/WritingAlgorithms.md index fb46e90..928c4e8 100644 --- a/developing-key4hep-software/WritingAlgorithms.md +++ b/developing-key4hep-software/WritingAlgorithms.md @@ -26,8 +26,8 @@ of being able to run in a multithreaded environment (almost) trivially[^1]. ## Setup We will need Gaudi, k4FWCore and all their dependencies. Installing these by -ourselves is not easy but there are software stacks on cvmfs, see the -{doc}`/setup-and-getting-started/README.md` to set up the key4hep stack. +ourselves is not easy but there are software stacks on cvmfs, see this +[page](../setup-and-getting-started/README.md) to set up the key4hep stack. The easiest way of having a working repository is to copy the template repository that we provide in key4hep: diff --git a/spack-build-instructions-for-librarians/spack-setup.md b/spack-build-instructions-for-librarians/spack-setup.md index f27e5e0..2d7063e 100644 --- a/spack-build-instructions-for-librarians/spack-setup.md +++ b/spack-build-instructions-for-librarians/spack-setup.md @@ -1,8 +1,8 @@ -## Setting up Spack +# Setting up Spack -### Downloading a spack instance +## Downloading a spack instance Spack is easy to set up: simply clone the key4hep fork, and use one of the provided spack "environments", that is spack configuration that is created automatically from the current key4hep/key4hep-spack repository. @@ -16,14 +16,14 @@ spack env activate key4hep-spack/environments/key4hep-release-user # or other en These instructions assume that a Centos7 machine with a running CVMFS client is used (for other OSs see below). Since Spack cannot bootstrap with the system compiler on Centos7, a setup script for Clingo ( a spack dependency ) is provided. -### Using Spack Environments +## Using Spack Environments The [spack environments](https://spack.readthedocs.io/en/latest/environments.html) available in `key4hep-spack/environments` bundle the spack configuration, setting up a suitable compiler from cvmfs, the key4hep package recipes, whether to create a view, etc. It is recommended to always use spack in an environment. New environments can be easily created by copying and modifying existing ones, but some use relative links to common configuration files in `key4hep-spack/environments/key4hep-common`, so they should be kept in the `key4hep/environments` directory. The basic environment is `key4hep-release`, which is used for the central installations and therefore uses `/cvmfs` as install area. `key4hep-debug` is a variation for debug builds. The default compiler is gcc, but an environment that uses clang is provided under `key4hep-release-clang`. For local builds that use cvmfs read-only, `key4hep-release-user` can be used. -### Using the key4hep-release-user environment +## Using the key4hep-release-user environment The key4hep user environment has the `key4hep-stack` bundle package in its spec list. By concretizing it, spack selects the latest compatible versions, re-using installations from cvmfs @@ -51,13 +51,13 @@ spack install ``` -### Configuring Spack +## Configuring Spack Alternatively, and for other platforms, spack can be configured in a few steps. These steps are essentially what is used to create the pre-configured spack instance in this script: https://github.com/key4hep/key4hep-spack/blob/master/scripts/ci_setup_spack.sh While this still puts the configuration files in the global scope of spack, it is recommended to use them in an environment, as provided by key4hep-spack. -#### Installing Spack +### Installing Spack Spack itself is very easy to install - simply clone the repository with git. ```bash @@ -65,7 +65,7 @@ git clone https://github.com/spack/spack.git source spack/share/spack/setup-env.sh ``` -#### Installing the key4hep package recipes +### Installing the key4hep package recipes The spack repository for key4hep packages is installed the same way: @@ -74,7 +74,7 @@ git clone https://github.com/key4hep/key4hep-spack.git spack repo add key4hep-spack ``` -### Configuring `packages.yaml` +## Configuring `packages.yaml` In order to choose the right package versions and build options, spack sometimes needs a few [hints and nudges](https://spack.readthedocs.io/en/latest/build_settings.html). With the new concretizer (default as of spack version 0.17) this should be mostly obsolete. key4hep-spack ships a spack config file that should give a good build customization out of the box, but can also be customized further. It just needs to be copied to the configuration where spack searches for configurations: @@ -85,7 +85,7 @@ cp key4hep-spack/environments/key4hep-common/packages.yaml spack/etc/spack/ -#### Configuring `upstreams.yaml` +### Configuring `upstreams.yaml` The cvmfs installation can be used as an "upstream installation", by adding the following configuration: @@ -98,7 +98,7 @@ EOT ``` -#### Setting up additional compilers +### Setting up additional compilers Often it is practical to use a compiler already installed upstream. Spack provides the `spack compiler find` command for this, but the compiler needs to be loaded into the PATH: