compilation.md

@@ -12,14 +12,14 @@ subdirectories:
 
 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)
+two main type of python environment currently supported:
+* python environment using built-in module [venv](https://docs.python.org/3/library/venv.html) or virtualenvwrapper
 * [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
+Conda is a tool allowing to manage its own 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
@@ -27,13 +27,13 @@ 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
+## Compiling with Conda
 
 To create a conda environment called `pylmgc90` with every pre-requisites
-installed inside it, the move your terminal to the source directory
+installed inside it, then 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:
+Windows users must use:
 ```shell
 cd lmgc90_user_xxxx
 conda env create -f environment_win.yml
@@ -50,18 +50,27 @@ conda activate pylmgc90
 python -m pip install .
 ```
 
-## With a venv and pip
+The last line will build the lmgc90 project based on the instructions given in the `pyproject.toml` file. Feel free to modify some options in this file, for example to activate OpenMP support. 
 
-If you have no venv yet create one and activate it. For example with virtualenvwrapper:
-```shell
-mkvirtualenv pylmgc90
-workon pylmgc90
-```
-Or a single environment:
+## Compiling in a venv using pip
+
+If you have no venv yet, create one and activate it: 
 ```shell
 python -m venv venv
 source ./venv/bin/activate
 ```
+An alternative to venv is virtualenvwrapper (which allows you to better manage your venv).
+* First you have to install virtualenvwrapper (only once): `apt install virtualenvwrapper` or `pip install virtualenvwrapper`.  
+  Then you have to configure it adding this 2 lines to your .bashrc (or .zshrc):
+  ```shell
+  export WORKON_HOME=~/.my_venvs
+  source /usr/share/virtualenvwrapper/virtualenvwrapper.sh 
+  ```
+* then create your env
+  ```shell
+  mkvirtualenv pylmgc90
+  workon pylmgc90
+  ```
 
 Then with your environment activated, go to the source directory
 of LMGC90, install the pre-requisites and the `pylmgc90` module:
@@ -70,15 +79,12 @@ cd lmgc90_user_xxxx
 python -m pip install -r ./requirements.txt
 python -m pip install .
 ```
+The last line will build the lmgc90 project based on the instructions given in the `pyproject.toml` file. Feel free to modify some options in this file, for example to activate OpenMP support. 
 
-## 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)
+## Handmade compilation on Unix like system (linux, MacOS, WSL) ##
 
-You must run a set of commands from the terminal to build LMGC90 software for your system.
-
-## Unix like system (linux, MacOS, WSL) ##
+Instead of using `pyproject.toml` file, you must run a set of commands from the terminal to build LMGC90 software for your system.  
+We recommend using python environment even in this case (see above). 
 
 Run the following commands:
 ```shell
@@ -87,7 +93,7 @@ cmake ..
 make
 make install
 ```
-
+If an error arises during the compilation step please first check if there is not a solution in the [FAQ](Faq#compile_error)  
 _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)_
 
 #### Python selection ####
@@ -102,7 +108,6 @@ cd build
 cmake .. -DPython_EXECUTABLE=[absolute path to python]
 make
 ```
-
 If nothing is specified then the current python will be used (which should
 be a python from a virtual environment).