compilation.md

@@ -8,6 +8,71 @@ subdirectories:
  * *docs* : the html documentation generated from the sources
  * *build* : (empty) where to build the LMGC90 libraries
 
+## Forerword
+
+LMGC90 is used as a Python module. It is thus strongly recommended to use
+a virtual environment to install and use the module inside. There are
+several two main type of python environment currently supported:
+* python environment using built-in module [venv](https://docs.python.org/3/library/venv.html)
+* [conda](https://conda-forge.org) environment
+
+Some tools help with the management of environments. For example VSCode is equipped
+with plugins allowing to select/create conda or venv environment for your projects.
+
+Conda is a tool allowing to manage its environments whereas for the `venv` the
+`virtualenvwrapper` package can help to do that.
+
+Later some `environement.yml` and `requirements.txt` files will be used. They
+pin a maximum version of the different dependencies to avoid some compatibility
+problems in the future ; but if the need arise, do not hesitate to try to tweak
+them to fit your needs.
+
+## With Conda
+
+To create a conda environment called `pylmgc90` with every pre-requisites
+installed inside it, the move your terminal to the source directory
+and create the environment from the yaml file. There are some differences
+between the different operating system.
+So Windows users must use:
+```shell
+cd lmgc90_user_xxxx
+conda env create -f environment_win.yml
+```
+On others system:
+```shell
+cd lmgc90_user_xxxx
+conda env create -f environment.yml
+```
+
+Then activate the environment and install LMGC90:
+```shell
+conda activate pylmgc90
+python -m pip install .
+```
+
+## With a venv and pip
+
+If you have no venv yet create one and activate it. For example with virtualenvwrapper:
+```shell
+mkvirtualenv pylmgc90
+workon pylmgc90
+```
+Or a single environment:
+```shell
+python -m venv venv
+source ./venv/bin/activate
+```
+
+Then with your environment activated, go to the source directory
+of LMGC90, install the pre-requisites and the `pylmgc90` module:
+```shell
+cd lmgc90_user_xxxx
+python -m pip install -r ./requirements.txt
+python -m pip install .
+```
+
+## Full compilation
+
 If an error arises during the compilation step please first check if there is not a solution
 in the [FAQ](Faq#compile_error)
 
@@ -20,6 +85,7 @@ Run the following commands:
 cd build
 cmake ..
 make
+make install
 ```
 
 _In case of error during the `make` step on macOS, check [this part of the FAQ](faq#an-error-arise-when-building-on-mac-os)_
@@ -37,18 +103,8 @@ cmake .. -DPython_EXECUTABLE=[absolute path to python]
 make
 ```
 
-Or if the user prefers to use *virtual environment* (with or without a manager like [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/#) or [miniconda](https://virtualenvwrapper.readthedocs.io/en/latest/#), then there is two changes:
-1. the path to the environment must be provided to cmake
-2. lmgc90 must be installed in the environment.
-
-For example when using *virtualenvwrapper* and with an environment called *lmgc90* the compilation steps becomes:
-```shell
-workon lmgc90
-cd build
-cmake .. -DVENV_PATH=$VIRTUAL_ENV
-make
-make install
-```
+If nothing is specified then the current python will be used (which should
+be a python from a virtual environment).
 
 #### Optional compilation ####
 
@@ -58,12 +114,12 @@ configuration parameters. For examples to be able to deactivate HDF5 file writin
 too much trouble to install all dependencies),
 you have to compile with:
 ```shell
-cmake . -DWITH_HDF5=False
+cmake . -DLMGC90_WITH_HDF5=False
 make
 ```
 And to enable shared memory parallelization, then you need to run:
 ```shell
-cmake . -DWITH_OPENMP=True
+cmake . -DLMGC90_WITH_OPENMP=True
 make
 ```