Skip to content

Commit f3f4d97

Browse files
nicolaslgnicolaslg
committed
updated the developer guide
1 parent 0861705 commit f3f4d97

File tree

2 files changed

+121
-48
lines changed

2 files changed

+121
-48
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313

1414

1515
## Last changes
16-
- We currently change our installation procedure. In particular, we externalize some of gmds depencies. See the [developer documentation](docs/mkd/developers_doc.md) for more details.
17-
- Important work is done on the Python API, see the the [pygmds](pygmds/README.md) module.
16+
- We changed our installation procedure. In particular, we externalized some of gmds depencies. See the [developer documentation](docs/mkdocs/dev-guide/developers_doc.md) for more details.
17+
- Important work is done on the Python API, see the [pygmds](pygmds/README.md) module.
1818
- Our blocking structure is evolving to be more robust and efficient for the blocking procedure. See the [blocking](blocking/README.md) module.
1919

2020
## GMDS in a nuthsell

‎docs/mkdocs/dev-guide/developers_doc.md‎

Lines changed: 119 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,145 @@
11
# Developer documentation
22

33
## Setting your development environment
4-
gmds depends on many external components. In order to develop gmds, they need to be installed properly in
4+
gmds depends on many external components. In order to compile gmds they need to be installed properly in
55
order to be used with CMake.
66

7-
On linux systems, and macos, we suggest to use [spack](https://spack.io/) for installing your depencies.
7+
Some are optionnal depending on the gmds functionnalities we want to activate;
8+
they include for example:
9+
- `lcov` is used to perform code coverage locally to your computer;
10+
- `py-pybind11` is mandatory for the python API;
11+
- `glpk` is a linear programming solver that we used in some of our *gmds* basic components;
12+
- `googletest` is used for our testing infrastructure;
13+
- `cgal` is required for the blocking component.
14+
15+
On linux systems and macos we suggest using [spack](https://spack.io/) for installing the dependencies.
816
We use this system for our CI workflows. In a nutshell, spack allows you to install a set of libraries in a
917
specific directory. You can see it as an equivalent of *Python environment*. In our context,
1018
we will simply install the set of dependencies we need and use them in our CMake build system. As an example,
11-
let's take a look how to install the basic set of gmds components, plus the blocking component with the Python API and
12-
without CGNS dependency.
19+
let's take a look at how to install the basic set of gmds components, plus the blocking component with the Python API and
20+
with the CGNS writer.
21+
22+
### Installation of dependencies with spack
23+
The following procedure can be found in the [build_spack_gmds.sh](https://github.com/LIHPC-Computational-Geometry/spack_recipes/blob/main/build_spack_gmds.sh)
24+
script. You can run the following commands from an empty directory; you will end up with three directories `spack, spack_recipes and gmds`.
25+
Spack's [prerequisites](https://spack.readthedocs.io/en/v0.20.3/getting_started.html) for the version of your choice
26+
should be installed.
1327

14-
### Raw installation of dependencies with spack
15-
First of all, we download spack and change its way of installing libraries (second line with the `sed` command).
16-
After that, any library `toto` installed with spack will be located in `absolute_path/spack/opt/spack/toto/`.
28+
We download a spack release; optionally you can remove the configuration files
29+
stored in the `.spack` directory located in your home if you have previously used spack and want a fresh start:
1730
```bash
18-
git clone --depth=1 -b releases/latest https://github.com/spack/spack.git
19-
sed -i 's#"${ARCHITECTURE}/${COMPILERNAME}-${COMPILERVER}/${PACKAGE}-${VERSION}-${HASH}"#"${PACKAGE}"#g' spack/etc/spack/defaults/config.yaml
20-
. ./spack/share/spack/setup-env.sh
31+
#==========================================
32+
# First get a spack release
33+
git clone --depth=1 -b v0.20.3 https://github.com/spack/spack.git
34+
35+
#==========================================
36+
# can be mandatory if you have already used spack on your computer
37+
# delete the .spack directory in the home of the user in order to
38+
# have a fresh start
39+
```
40+
41+
The way to build software in spack is described in what is called `recipes`, and ours
42+
are located in this project:
43+
```bash
44+
#==========================================
45+
# get our recipes
46+
git clone --branch gmds_temp --depth=1 https://github.com/LIHPC-Computational-Geometry/spack_recipes.git
47+
````
48+
49+
Spack can be configured; you can modify the installation directory to shorten the paths at the cost
50+
of disabling the possibility to have several installations of a same package with differing
51+
options/versions (if choosing that any library `toto` installed with spack will be located in `absolute_path/spack/opt/spack/toto/`.)
52+
```bash
53+
# Optionnal: modifying the install_tree variable to make it shorter and more human readable;
54+
# the HASH part in install directory names is removed which can lead to collisions.
55+
# The spack/etc/spack/defaults/config.yaml file can be modified by hand
56+
# - in spack version 0.20
57+
#sed -i 's#"{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}"#"{name}"#g' spack/etc/spack/defaults/config.yaml
58+
```
59+
60+
Spack comes with builtin recipes; still we have to register additional ones:
61+
- recipes for our own software, in particular gmds itself;
62+
- superseded recipes that replace the builtin ones; we aim to keep this number low and directly contribute
63+
to the spack upstream project
64+
```bash
65+
# to register our recipes; it assumes that spack_recipes and spack are located at
66+
# the same level. You can use the "spack repo add" commands instead of copying the repos.yaml file
67+
#spack repo add ./spack_recipes/meshing_repo
68+
#spack repo add ./spack_recipes/supersede_repo
69+
cp spack_recipes/config/repos.yaml spack/etc/spack/defaults/repos.yaml
70+
```
71+
72+
We will start using spack itself
73+
```bash
74+
#==========================================
75+
# configure spack using spack commands; it modifies the .spack directory in the user home
76+
source spack/share/spack/setup-env.sh
77+
spack clean -a
2178
```
22-
Now, we can install the different packages that are required by *gmds*. There are many ways of doing it.
23-
We use here the most basic one, that consists in successively asking spack to install all the
24-
required dependencies. Here:
25-
- `lcov` is used to perform code coverage locally to your computer;
26-
- `py-pybind11` is mandatory for the python API;
27-
- `glpk` is a linear programming solver that we used in some of our *gmds* basic components;
28-
- `googletest` is used for our testing infrastructure;
29-
- `cgal` is required for the blocking component.
3079

80+
First register cmake
3181
```bash
82+
# registering cmake
3283
spack external find cmake
33-
spack install lcov
34-
spack install py-pybind11
35-
spack install glpk
36-
spack install googletest
37-
spack install cgal
38-
spack install --only dependencies gmds+kmds+blocking ^kokkos+openmp ^cgns~mpi
3984
```
40-
Once all those libraries installed, *gmds* can be compiled with CMake using the following options
41-
```cmake
42-
-DWITH_PYTHON_API=ON
43-
-DENABLE_BLOCKING=ON
44-
-DWITH_CGNS=OFF
45-
-DWITH_TEST=ON
46-
-DGLPK_INC=/absolute_path/spack/opt/spack/glpk/include
47-
-DGLPK_LIB=/absolute_path/spack/opt/spack/glpk/lib
48-
-DCMAKE_PREFIX_PATH=/absolute_path/spack/opt/spack/googletest;/absolute_path/spack/opt/spack/py-pybind11;/absolute_path/spack/opt/spack/cgal;/absolute_path/spack/opt/spack/gmp;/absolute_path/spack/opt/spack/mpfr;/absolute_path/spack/opt/spack/boost
85+
86+
And then compilers; you need a compiler that handles both C and CXX:
87+
```bash
88+
# registering compilers
89+
spack compiler find
90+
# spack uses the highest version of the compiler found by default; if it is incomplete,
91+
# for example the C compiler is installed but not the CXX one the installations will fail.
92+
# Compilers found can be investigated by (see `spack help compiler` commands)
93+
#spack compiler list
94+
#spack compiler info gcc
95+
# An undesirable version can be removed by editing ~/.spack/linux/compilers.yaml or using
96+
#spack compiler remove gcc@12
4997
```
5098

51-
### Usage of specific spack recipes
99+
Now we get gmds:
100+
```bash
101+
# install for dev purposes
102+
git clone [email protected]:LIHPC-Computational-Geometry/gmds.git
103+
```
52104

53-
Instead of manually and individually installing all the *gmds* dependencies, we can gather *gmds* requirements
54-
into a *spack recipe*. This recipe will be used by the spack engine to prepare and build the full environment.
105+
And we build gmds from the sources we just cloned, including all the necessary dependencies
55106

56-
Our meshing recipes are stored in a github repository that you have to clone and add in the list of spack repositories.
57107
```bash
58-
git clone --branch gmds_temp --depth=1 https://github.com/LIHPC-Computational-Geometry/spack_recipes_meshing.git
59-
spack repo add ./spack_recipes_meshing/meshing_repo
60-
spack repo add ./spack_recipes_meshing/supersede_repo
108+
# you will probably want build_type=Debug or RelWithDebInfo.
109+
# Choose the variants you need, you can check them using `spack info gmds`.
110+
# The dev_path option does not seem to handle relative paths.
111+
112+
# +mpi should actually be ok, but currently the default openmpi install fails
113+
# It is activated by default in the hdf5 and cgns recipes, so choose not to use it if necessary
114+
spack install gmds+python+blocking+cgns dev_path=$PWD/gmds build_type=Debug ^cgns~mpi ^hdf5~mpi
61115
```
62-
Then you can install the gmds dependencies using lines like:
116+
117+
### Configuring the IDE
118+
Now in order to develop we need to configure an IDE. This can be done in two ways:
119+
1. Extracting the options from spack. Files named `gmds/spack-*` were created in the gmds directory; we can extract the necessary
120+
data to configure an IDE, in particular the `CMAKE_PREFIX_PATH` and the cmake options given to gmds.
63121
```bash
64-
spack external find cmake
65-
spack install py-pybind11
66-
spack install --only dependencies gmds+blocking
122+
# to configure an IDE
123+
# spack created files and directories named gmds/spack-* in the gmds source tree, where the necessary
124+
# options are set up
125+
# get the CMAKE_PREFIX_PATH with ';' as separators
126+
cat gmds/spack-build-env.txt | grep CMAKE_PREFIX_PATH | awk -F "=" {'print $2'} | awk -F ";" {'print $1'} | sed 's/:/;/g'
127+
128+
# get the cmake options that were explicitly set by spack; add -DWITH_TEST:BOOL=ON
129+
# to activate the tests
130+
cat gmds/spack-configure-args.txt
67131
```
68-
Right now, the python binding configuration, as well as the CGNS options, are not managed in the gmds spack recipe. That's
69-
why, we separately install `pybind11` and the last line will install `cgns` too.
132+
133+
2. Specifying the options by hand; note that you can proceed this way whatever the method used to install
134+
the dependencies:
135+
```cmake
136+
-DWITH_PYTHON_API:BOOL=ON
137+
-DENABLE_BLOCKING:BOOL=ON
138+
-DWITH_CGNS:BOOL=ON
139+
-DWITH_TEST:BOOL=ON
140+
-DCMAKE_PREFIX_PATH=/absolute_path/spack/opt/spack/googletest;/absolute_path/spack/opt/spack/py-pybind11;/absolute_path/spack/opt/spack/cgal;/absolute_path/spack/opt/spack/gmp;/absolute_path/spack/opt/spack/mpfr;/absolute_path/spack/opt/spack/boost;/absolute_path/spack/opt/spack/glpk;/absolute_path/spack/opt/spack/cgns
141+
```
142+
70143
## Creation of an optional module
71144

72145
Once a component created, we use a [github workflow](git_workflow.md) in order to structure the code development.

0 commit comments

Comments
 (0)