Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 25 additions & 53 deletions _episodes/07-development-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Development and contribution"
teaching: 10
exercises: 20
compatibility: ESMValTool v2.14.0
compatibility: ESMValTool v2.15.0

questions:
- "What is a development installation?"
Expand Down Expand Up @@ -109,73 +109,46 @@ nothing to commit, working tree clean
~~~
{: .output}

### 2 ESMValTool dependencies

Please don’t forget if an esmvaltool environment is already created
following the lesson
[Installation]({{ page.root }}{% link _episodes/02-installation.md %}),
we should choose another name for the new environment in this lesson.

ESMValTool uses `mamba` for the recommended installation.
For a minimal mamba installation, see section **Install Mamba** in lesson
[Installation]({{ page.root }}{% link _episodes/02-installation.md %}).

It is good practice to update the version of mamba on your machine before
setting up ESMValTool. This can be done as follows:

~~~bash
mamba update --name base mamba conda
~~~

To simplify the installation process, an environment file ``environment.yml`` is
provided in the ESMValTool directory. We create an environment by running:

~~~bash
mamba env create --name esmvaltool --file environment.yml
~~~

The environment is called ``esmvaltool`` by default.
If an ``esmvaltool`` environment is already created following the lesson
[Installation]({{ page.root }}{% link _episodes/02-installation.md %}),
we should choose another name for the new environment in this lesson by:
### 2 ESMValTool installation

It is recommended to use [pixi](https://pixi.prefix.dev/) to manage ESMValTool
dependencies. There are different ways to install pixi which you can find on the
[pixi installation instructions](https://pixi.prefix.dev/latest/installation/)
website. One way to install pixi is for example:
~~~bash
mamba env create --name a_new_name --file environment.yml
curl -fsSL https://pixi.sh/install.sh | sh
~~~
This will create a new conda environment and install ESMValTool (with all
dependencies that are needed for development purposes) into it with a single command.

For more information see
[Mamba User Guide](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html).

Now, we should activate the environment:

After installing pixi you run the following command to install all of the
required dependencies for running and developing Python diagnostics:
~~~bash
conda activate esmvaltool
pixi shell --frozen
~~~
where ``esmvaltool`` is the name of the environment (replace by ``a_new_name``
in case another environment name was used).

### 3 ESMValTool installation

ESMValTool can be installed in a ``develop`` mode by running:
Using the '--frozen' flag instructs pixi to use the versions of the packages
listed in the ``pixi.lock`` file. Using this option makes all pixi
commands run faster and makes your analyses more reproducible.

As we want to add new code later in the epsiode, we want to install ``pre-commit``.
This will make sure that our changes will be formatted correctly when we commit
them.
~~~bash
pip install --no-deps --editable '.[develop]'
pre-commit install
~~~

This will add the ``esmvaltool`` directory to the Python path in editable mode and
install the development dependencies. We should check if the installation
works properly. To do this, run the tool with:
To check if the installation of pixi works properly, we run ESMValTool with:

~~~bash
esmvaltool --help
~~~

If the installation is successful, ESMValTool prints a help message to the console.

Further information and instructions using pixi can be found in the [ESMValTool
documentation](https://docs.esmvaltool.org/en/latest/quickstart/installation.html#install-from-source).
And if you need to exit the pixi environment, run ``exit`` or ``Ctrl+D``.


### 4 Updating ESMValTool
### 3 Updating ESMValTool

The ``main`` branch has the latest features of ESMValTool. Please make sure
that the source code on your machine is up-to-date. If you obtain the source
Expand Down Expand Up @@ -249,9 +222,8 @@ no syntax errors in our recipes and config files
- [lintr](https://github.com/jimhester/lintr) for diagnostic scripts written in R
- [codespell](https://pypi.org/project/codespell/) to check grammar

The good news is that ``pre-commit`` has been already installed
when we chose development installation.
``pre-commit`` is a command line and runs all of those tools. It also fixes some of those errors.
The good news is that ``pre-commit`` which we already installed earlier is a command line
and runs all of those tools. It also fixes some of those errors.
To explore other tools, have a look at ESMValTool documentation on
[Code quality](https://docs.esmvaltool.org/en/latest/community/
code_documentation.html#code-quality).
Expand Down
Loading