Workaround for PyGMT on Windows

[seisman]

Description of the problem

We have several reported issues saying that pygmt can't load the GMT library on Windows, e.g. #46, #285, #353.

Actually, the description of the issues is inaccurate. PyGMT works well with the GMT official installers (i.e., gmt-6.0.0-win64.exe), but doesn't work with the gmt conda package on Windows. We're working on a fix in PR #313, but currently, it's still not clear why the conda windows package is special, and it may take a long time to make it work (it's almost solved, see #434 and GenericMappingTools/gmt#3353).

---

Update on May 22, 2020

PyGMT v0.1.1 works perfectly on Windows. No workaround is needed.

Please follow the latest install instructions.

---

Update on May 20, 2020:

We finally find out why PyGMT crashes with the GMT conda package on Windows. The issue was fixed in #434.

Currently, Windows users can install the PyGMT master branch:

pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip

so that import pygmt will work. We will release PyGMT v0.1.1 in the coming days on PyPI and conda-forge to include the new fixes.

and add one environmental variable:

• GMT_LIBRARY_PATH: path to the gmt.dll path, e.g., C:\Miniconda\envs\pygmt\Library\bin
• GMT_SHAREDIR: path to the GMT's share directory, e.g., C:\Miniconda\envs\pygmt\Library\share\gmt

More testing from Windows users are welcomed.

---

Posted on May 17, 2020.

The workaround below is still valid, but please follow the comment above.

For PyGMT users on Windows, the simplest workaround would be:

# configure conda to get packages from the conda-forge channel:
conda config --prepend channels conda-forge
# create a new conda environment
conda create --name pygmt python=3.6 pip numpy pandas xarray netcdf4 packaging 
# Activate the environment by running:
conda activate pygmt
# install pygmt
pip install pygmt
# download GMT installers and install it
...

note: currently, we can't use conda install pygmt on Windows, but it should be fixed later.

Perhaps also need to set the environmental variable GMT_LIBRARY_PATH to the gmt.dll library path, e.g., C:\Miniconda\envs\testing\Library\bin.

I just installed GMT and pygmt following the install instruction above and successfully made a simple plot.

I think this is easier than "building from source" or using "WSL" as suggested in our documentation (https://www.pygmt.org/latest/install.html), and we should recommend this way instead.

[weiji14]

Ok, we should add this workaround to the documentation. Probably need to make a 0.1.1 release too otherwise it won't show up on pygmt.org/latest. And we'll need to have the windows conda package ready. Bit of a chicken and egg situation...

[seisman]

Here are what we should do:

• Review, improve and merge PR Let PyGMT work with the conda GMT package on Windows #434
• Find out why GMT can't guess the share directory and report it to the core GMT (A potential bug in guessing GMT's share directory gmt#3353). (The issue was fixed in GMT master branch).
• Apply the patch to GMT 6.0.0 and rebuild the conda package (GMT_SHAREDIR is no longer needed).
• Find out why ctypes.CDLL can't find conda's library (see Improve how PyGMT finds the GMT library #440, GMT_LIBRARY_PATH is no longer needed on Windows)
• Document the workaround for Windows (workaround is not needed after Improve how PyGMT finds the GMT library #440 is merged)
• Fixes the failing tests on Windows (Finalize fixes on WIndows test suite for v0.1.1 #441)
• Update the conda install instructions (Update install instructions #430)
• Release v0.1.1 or 0.2.0
• Update the pygmt feedstock to provide the conda pygmt package

[seisman]

The conda GMT package was rebuilt in conda-forge/gmt-feedstock#94. Windows users no longer need to set the variable GMT_SHAREDIR.

[seisman]

As per the conda documentation:

For now, most DLLs are installed into (install prefix)\Library\bin. This path is added to os.environ["PATH"] for all Python processes, so that DLLs can be located, regardless of the value of the system's PATH environment variable.

PyGMT should be able to locate gmt.dll.

---

PREFIX\Library\bin is in the PATH, but ctypes.CDLL("gmt.dll") cannot find the library. However, ctypes.CDLL("gmt.dll", winmode=0) can, but winmode is new in Python 3.8.

[seisman]

PyGMT v0.1.1 is released. It's expected to work smoothly on Windows. No workaround is needed anymore.