Skip to content

Commit c815aa0

Browse files
Peter9192Peter9192
authored
Merge pull request #31 from ESMValGroup/installation
Add installation episode
2 parents 5ff6b53 + 4145308 commit c815aa0

File tree

2 files changed

+310
-82
lines changed

2 files changed

+310
-82
lines changed

‎_episodes/02-installation.md‎

Lines changed: 190 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,227 @@
11
---
22
title: "Installation"
3-
teaching: 0
4-
exercises: 0
3+
teaching: 10
4+
exercises: 20
55
questions:
66
- "What are the prerequisites for installing ESMValTool?"
7-
- "How do I confirm that the installation was succesful?"
7+
- "How do I confirm that the installation was successful?"
88
objectives:
9-
- "Execute a succesful ESMValTool installation"
9+
- "Install ESMValTool"
10+
- "Demonstate that the installation was successful"
1011
keypoints:
11-
- "ESMValTool is installed from source code that lives in the [GitHub repository](https://github.com/ESMValGroup/ESMValTool)"
12-
- "All the required packages can be installed using conda and the [environment.yml file](https://github.com/ESMValGroup/ESMValTool/blob/master/environment.yml)"
13-
- "You can find more information about installation in the [documentation](https://esmvaltool.readthedocs.io/en/latest/getting_started/install.html)"
12+
- "All the required packages can be installed using conda"
13+
- "You can find more information about installation in the documentation"
1414
---
15+
## Overview
1516

16-
> ## Attention
17-
>
18-
> * This episode is based on the ESMValTool installation instructions, for more information and advanced cases you can visit the ESMValTool [documentation](https://esmvaltool.readthedocs.io/en/latest/getting_started/install.html).
19-
> * For this episode it is assumed you have knowledge of [git](https://git-scm.com/) you can refresh your knowledge in the corresponding [git carpentries course](http://swcarpentry.github.io/git-novice/).
20-
{: .callout}
17+
In this tutorial we will be using the [Conda](https://conda.io/projects/conda/en/latest/index.html)
18+
package manager to install the ESMValTool.
19+
Other installation methods are also available, they can be found in the
20+
[documentation](https://docs.esmvaltool.org/en/latest/quickstart/installation.html).
21+
ESMValTool also contains diagnostics written in [Julia](https://julialang.org/).
22+
Because Julia cannot be installed by Conda, we will install Julia separately.
23+
We will first learn how to install Conda, Julia, and finally the ESMValTool.
24+
We end this chapter by testing that the installation was successful.
2125

22-
## Obtaining the source code
26+
## Install Conda
2327

24-
The ESMValTool source code is available on a public GitHub repository:
25-
https://github.com/ESMValGroup/ESMValTool
28+
ESMValTool is distributed using [Conda](https://conda.io/). We will be using the Miniconda minimal installer for conda. We suggest a Python 3 based installer, though if you happen to already have Conda installed it should also work with Python 2. For more information about installing conda, see [the conda installation documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
2629

27-
The easiest way to obtain it is to clone the repository using git.
28-
To clone the public repository open a terminal window and type:
30+
### Linux
2931

30-
~~~
31-
git clone https://github.com/ESMValGroup/ESMValTool.git
32-
~~~
33-
{: .source}
32+
1. Please download Miniconda3 for Linux at [the miniconda page](https://docs.conda.io/en/latest/miniconda.html). The 64 bit version should work on any recent system. If you have problems in the next step(s) you can alternatively try a 32 bit version.
3433

35-
By default, this command will create a folder called ESMValTool containing the
36-
source code of the tool.
34+
2. Next, run the installer from the place where you downloaded it
3735

38-
Move into the directory to continue installation.
36+
```bash
37+
bash Miniconda3-latest-Linux-x86_64.sh
38+
```
3939

40-
> ## Attention
41-
>
42-
> Make sure that the master branch is checked out before continuing intallation:
43-
> ~~~
44-
> git checkout master
45-
> ~~~
46-
> {: .source}
47-
{: .callout}
40+
3. Follow the instructions in the installer. The defaults should normally suffice.
4841

49-
## Prerequisites
42+
4. You will need to restart your terminal for the changes to have effect.
5043

51-
It is recommended to use conda to manage ESMValTool dependencies.
52-
For a minimal conda installation go to https://conda.io/miniconda.html. To
53-
simplify the installation process, an environment definition file is provided
54-
in the repository (``environment.yml`` in the root folder).
44+
5. Verify you have a working conda installation by listing all installed packages
5545

56-
> ## Attention
57-
> It is preferable to use a local, fully user-controlled conda installation.
58-
> If you have conda installed already, make sure it is up to date by running ``conda update -n base conda``.
59-
{: .callout}
46+
```bash
47+
conda list
48+
```
6049

61-
From now on, we will assume that the installation is going to be done through
62-
conda.
50+
Should output something like
6351

64-
Ideally, you should create a conda environment for ESMValTool, so it is
65-
independent from any other Python tools present in the system.
52+
```
53+
# packages in environment at ~/miniconda3:
54+
#
55+
# Name Version Build Channel
56+
...
57+
conda 4.8.3 py37_0
58+
...
59+
```
60+
{: .output}
6661

67-
To create an environment, go to the directory containing the ESMValTool source
68-
code (called ESMValTool if you did not choose a different name) and run
62+
### MacOSX
6963

70-
~~~
71-
conda env create --name esmvaltool --file environment.yml
72-
~~~
73-
{: .source}
64+
1. Please download Miniconda3 for MacOSX at [the miniconda page](https://docs.conda.io/en/latest/miniconda.html).
7465

75-
The environment is called ``esmvaltool`` by default, but it is possible to use
76-
the option ``--name ENVIRONMENT_NAME`` to define a custom name. You can activate
77-
the environment using the command:
66+
2. Next, run the installer from the place where you downloaded it
7867

79-
~~~
80-
conda activate esmvaltool
81-
~~~
82-
{: .source}
68+
```bash
69+
bash Miniconda3-latest-MacOSX-x86_64.sh
70+
```
8371

84-
If you run into trouble, please try recreating the environment. More information can be found in the (conda documentation)[https://docs.conda.io/en/latest/].
72+
3. Follow the instructions in the installer. The defaults should normally suffice.
8573

74+
4. You will need to restart your terminal for the changes to have effect.
8675

87-
## Software installation
76+
5. Verify you have a working conda installation by listing all installed packages
8877

89-
Once all prerequisites are fulfilled, ESMValTool can be installed by running
90-
the following commands in the directory containing the ESMValTool source code:
78+
```bash
79+
conda list
80+
````
9181
92-
~~~
93-
pip install .
94-
~~~
95-
{: .source}
82+
Should output something like
9683
97-
## Test the installation
84+
```
85+
# packages in environment at ~/miniconda3:
86+
#
87+
# Name Version Build Channel
88+
...
89+
conda 4.8.3 py37_0
90+
...
91+
```
92+
{: .output}
9893

99-
The next step is to check that the installation works properly.
100-
To do this, run the tool with:
10194

102-
~~~
103-
esmvaltool --help
104-
~~~
105-
{: .source}
95+
### Windows
10696

107-
If everything was installed properly, ESMValTool should have printed a
108-
help message to the console.
97+
ESMValTool does not directly support Windows, but succesful usage has been reported through the [Windows Subsystem for Linux(WSL)](https://docs.microsoft.com/en-us/windows/wsl/), available in Windows 10.
10998

110-
For a more complete installation verification, run the automated tests and
111-
confirm that no errors are reported:
99+
To install the WSL please follow the instructions [on the Windows Documentation page](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
112100

113-
~~~
114-
python setup.py test --installation
115-
~~~
116-
{: .source}
101+
After installing the WSL, installation can be done using the Linux installation instructions.
117102

118-
{% include links.md %}
103+
## Install Julia
104+
105+
Complete instructions for installing Julia can be found on the
106+
[Julia installation page](https://julialang.org/downloads/platform/#linux_and_freebsd).
107+
In this tutorial, we will use the following steps.
108+
First, open a bash terminal and create a directory to install Julia in and cd into it
109+
110+
```bash
111+
mkdir ~/julia
112+
cd ~/julia
113+
```
114+
115+
Next, download the file
116+
[`julia-1.0.5-linux-x86_64.tar.gz`](https://julialang-s3.julialang.org/bin/linux/x64/1.0/julia-1.0.5-linux-x86_64.tar.gz)
117+
by clicking the link or going to the [Julia downloads page](https://julialang.org/downloads/).
118+
Download the file directly to the `~/julia` directory or move it there after downloading.
119+
To extract the file, you can use the following command:
120+
121+
```bash
122+
tar -xvzf julia-1.0.5-linux-x86\_64.tar.gz
123+
```
124+
125+
This will extract the files to a directory named `~/julia/julia-1.0.5`.
126+
To run Julia, you need to add the full path of Julia's `bin` folder to PATH environment variable.
127+
To do this, you can edit the `~/.bashrc` (or `~/.bash_profile`) file.
128+
Open the file in your favorite editor and add a new line as follows at the bottom of the file:
129+
130+
```bash
131+
export PATH="$PATH:$HOME/julia/julia-1.0.5/bin"
132+
```
133+
134+
Finally, for the settings to take effect, either reload your bash profile
135+
136+
```bash
137+
source ~/.bashrc
138+
```
139+
140+
(or `source ~/.bash_profile`), or close the bash terminal window and open a new one.
141+
142+
To check that the Julia executable can be found, run
119143
144+
```bash
145+
which julia
146+
```
147+
148+
to display the path to the Julia executable, it should be
149+
150+
```
151+
~/julia/julia-1.0.5/bin/julia
152+
```
153+
{: .output}
154+
155+
To test that Julia is installed correctly, run
156+
157+
```bash
158+
julia
159+
```
160+
161+
to start the interactive Julia interpreter. Press `Ctrl+D` to exit.
162+
163+
## Install the ESMValTool package
164+
165+
To install the ESMValTool package, run
166+
167+
```bash
168+
conda create -n esmvaltool -c conda-forge -c esmvalgroup esmvaltool
169+
```
170+
171+
This will create a new
172+
[Conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
173+
called `esmvaltool`, with the ESMValTool package and all of its dependencies installed in it.
174+
175+
> ## Conda common problems
176+
>
177+
> Below are some common problems that could happen while installing.
178+
>
179+
> - Installation takes long time
180+
> - Downloads and compilations can take several minutes to complete, please be patient.
181+
> - You might have bad luck and the dependencies can not be resolved at the moment, please try again later or [raise an issue](https://github.com/ESMValGroup/ESMValTool/issues/new/choose)
182+
> - If you have an old conda installation you could get a `UnsatisfiableError` message. Please install a newer version of conda and try again
183+
> - Downloads fail due to company proxy, see [conda docs](https://docs.anaconda.com/anaconda/user-guide/tasks/proxy/) how to resolve
184+
>
185+
{: .callout}
186+
187+
## Test that the installation was successful
188+
189+
To test that the installation was successful, run
190+
191+
```bash
192+
conda activate esmvaltool
193+
```
194+
195+
to activate the conda environment called `esmvaltool`.
196+
In the shell prompt the active conda environment should have been changed from `(base)` to `(esmvaltool)`.
197+
198+
Next, run
199+
200+
```bash
201+
esmvaltool --help
202+
```
203+
204+
to display the command line help.
205+
206+
> ## Version of ESMValTool
207+
>
208+
> Can you figure out which version of ESMValTool has been installed?
209+
>
210+
> > ## Solution
211+
> >
212+
> > The `esmvaltool --help` command lists `-v` or `--version` as optional argument to get the version
213+
> >
214+
> > In my case when I run
215+
> > ~~~
216+
> > esmvaltool --version
217+
> > ~~~
218+
> > {: .bash}
219+
> > I get that my installed ESMValTool version is
220+
> > ~~~
221+
> > 2.0.0b9
222+
> > ~~~
223+
> > {: .output}
224+
> {: .solution}
225+
{: .challenge}
226+
227+
{% include links.md %}

0 commit comments

Comments
 (0)