Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise pygmt development installation instructions #865

Merged
merged 7 commits into from
Feb 12, 2021
Merged

Revise pygmt development installation instructions #865

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f1a759a
Revise pygmt development installation instructions
weiji14 Feb 11, 2021
e29f375
Proofread installation instructions and wrap to 79 chars
weiji14 Feb 12, 2021
a243a13
Add quickstart instructions for installing pygmt in a conda environment
weiji14 Feb 12, 2021
da502f5
Apply suggestions from code review
weiji14 Feb 12, 2021
caf8db0
Update doc/install.rst
weiji14 Feb 12, 2021
aa0310b
Merge branch 'master' into fix-pip-install-dev
weiji14 Feb 12, 2021
c68319a
Set fallback scm version to 0+unknown
weiji14 Feb 12, 2021
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
100 changes: 68 additions & 32 deletions doc/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,31 +17,32 @@ Installing
Which Python?
-------------

You'll need **Python 3.7 or greater** to run PyGMT. Old Python versions may
work, but there is no guarantee that PyGMT will work as expected with old versions.
You'll need **Python 3.7 or greater** to run PyGMT. Older Python versions may
work, but there is no guarantee that PyGMT will work as expected.

We recommend using the `Anaconda <https://www.anaconda.com/distribution>`__ Python
distribution to ensure you have all dependencies installed and the ``conda``
package manager available.
We recommend using the `Anaconda <https://www.anaconda.com/distribution>`__
Python distribution to ensure you have all dependencies installed and the
``conda`` package manager available.
Installing Anaconda does not require administrative rights to your computer and
doesn't interfere with any other Python installations in your system.


Which GMT?
----------

PyGMT requires Generic Mapping Tools (GMT) version 6 as a minimum, which is the latest
released version that can be found at
PyGMT requires Generic Mapping Tools (GMT) version 6 as a minimum, which is the
latest released version that can be found at
the `GMT official site <https://www.generic-mapping-tools.org>`__.
We need the latest GMT (>=6.1.1) since there are many changes being made to GMT itself in
response to the development of PyGMT, mainly the new
We need the latest GMT (>=6.1.1) since there are many changes being made to GMT
itself in response to the development of PyGMT, mainly the new
`modern execution mode <https://docs.generic-mapping-tools.org/latest/cookbook/introduction.html#modern-and-classic-mode>`__.

Compiled conda packages of GMT for Linux, macOS and Windows are provided through
`conda-forge <https://anaconda.org/conda-forge/gmt>`__.
Compiled conda packages of GMT for Linux, macOS and Windows are provided
through `conda-forge <https://anaconda.org/conda-forge/gmt>`__.
Advanced users can also
`build GMT from source <https://github.com/GenericMappingTools/gmt/blob/master/BUILDING.md>`__
instead, which is not so recommended but we would love to get feedback from anyone who tries.
instead, which is not so recommended but we would love to get feedback from
anyone who tries.

We recommend following the instructions further on to install GMT 6.

Expand All @@ -58,61 +59,96 @@ PyGMT requires the following libraries:

The following are optional (but recommended) dependencies:

* `IPython <https://ipython.org/>`__: For embedding the figures in Jupyter notebooks.
* `IPython <https://ipython.org/>`__: For embedding the figures in Jupyter
notebooks.


Installing GMT and other dependencies
-------------------------------------

Before installing PyGMT, we must install GMT itself along with the other dependencies.
The easiest way to do this is using the ``conda`` package manager.
Before installing PyGMT, we must install GMT itself along with the other
dependencies. The easiest way to do this is via the ``conda`` package manager.
We recommend working in an isolated
`conda environment <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`__
to avoid issues with competing versions of its dependencies.
to avoid issues with conflicting versions of dependencies.

First, we must configure conda to get packages from the
`conda-forge channel <https://conda-forge.org/>`__::

conda config --prepend channels conda-forge

Now we can create a new conda environment with Python and all our dependencies installed
(we'll call it ``pygmt`` but you can change it to whatever you want)::
Now we can create a new conda environment with Python and all our dependencies
installed (we'll call it ``pygmt`` but feel free to change it to whatever you
want)::

conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt

Activate the environment by running::
Activate the environment by running the following (**do not forget this step!**))::
weiji14 marked this conversation as resolved.
Show resolved Hide resolved

conda activate pygmt

From now on, all commands will take place inside the conda virtual environment and won't
affect your default installation.
From now on, all commands will take place inside the conda virtual environment
called 'pygmt' and won't affect your default 'base' installation.


Installing PyGMT
----------------

Now that you have GMT installed and your conda environment activated, you can
use ``conda`` to install the latest release of PyGMT from `conda-forge <https://anaconda.org/conda-forge/pygmt>`__::
Now that you have GMT installed and your conda virtual environment activated,
you can install PyGMT using any of the following methods:

Using conda (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~

This installs the latest stable release of PyGMT from
`conda-forge <https://anaconda.org/conda-forge/pygmt>`__::

conda install pygmt
seisman marked this conversation as resolved.
Show resolved Hide resolved

or use ``pip`` to install from `PyPI <https://pypi.org/project/pygmt>`__::
Using pip
~~~~~~~~~

This installs the latest stable release from
`PyPI <https://pypi.org/project/pygmt>`__::

pip install pygmt

Alternatively, you can install the development version from the GitHub repository::
Alternatively, you can install the latest development version from
`TestPyPI <https://test.pypi.org/project/pygmt>`__::

pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt

pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip
or from PyGMT's GitHub repository (slower as it downloads the whole archive)::
weiji14 marked this conversation as resolved.
Show resolved Hide resolved

This will allow you to use the ``pygmt`` library from Python.
pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt

Any of the above methods (conda/pip) should allow you to use the ``pygmt``
weiji14 marked this conversation as resolved.
Show resolved Hide resolved
library from Python.


Testing your install
--------------------

Quick check
~~~~~~~~~~~

To ensure that PyGMT and its depedencies are installed correctly, run the
following in your Python interpreter::

import pygmt
pygmt.show_versions()

Or run this in the command line::

python -c "import pygmt; pygmt.show_versions()
weiji14 marked this conversation as resolved.
Show resolved Hide resolved


Full test (optional)
~~~~~~~~~~~~~~~~~~~~

PyGMT ships with a full test suite.
You can run our tests after you install it but you will need a few extra dependencies as
well (be sure to have your conda env activated)::
You can run our tests after you install it but you will need a few extra
dependencies as well (be sure to have your conda environment activated)::

conda install pytest pytest-mpl ipython

Expand All @@ -132,9 +168,9 @@ This can happen if you have multiple versions of GMT installed.

You can tell PyGMT exactly where to look for ``libgmt`` by setting the
``GMT_LIBRARY_PATH`` environment variable.
This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or ``gmt.dll``
can be found for Linux, macOS and Windows respectively.
e.g. in a terminal run::
This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or
``gmt.dll`` can be found for Linux, macOS and Windows respectively.
e.g. on a command line, run::

# Linux/macOS
export GMT_LIBRARY_PATH=$HOME/anaconda3/envs/pygmt/lib
Expand Down