Improve how PyGMT finds the GMT library

[seisman]

In the old codes, PyGMT first checks if the environmental variable GMT_LIBRARY_PATH
is defined. If yes, it tries to find the GMT library in the specified path.
Otherwise, it will search for the GMT library in standard library paths
(LD_LIBRARY_PATH on Linux; DYLD_LIBRARY_PATH on macOS; PATH on Windows).

This PR improves how PyGMT finds the library, by searching for all possible
paths. The paths from the highest priority to the lowest priority are:

1. the path defined by GMT_LIBRARY_PATH
2. the path returned by the command gmt --show-library
3. On Windows, also check the path returned by find_library function
4. the standard system paths

Thus, the function clib_full_names now yields a generator (not a list)
of possible paths, for example:

["/path/defined/by/gmtlibrarypath/libgmt.so",
 "/usr/local/lib/libgmt.so",
 "libgmt.so"]

Pros:

1. More ways to find the library, so less "GMTCLibNotFoundError" errors
2. Only calls the gmt command if GMT_LIBRARY_PATH is not defined

Cons:

1. A much longer list returned by clib_full_names. Maybe slower loading?
2. Difficult to test.

TODO

• Need to rewrite some tests in the test_clib_loading.py file.

Closes #628.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Notes

• You can write /format in the first line of a comment to lint the code automatically

[leouieda]

Thanks, @seisman! This is a good thing to have and I agree that it's worth the downsides. A few thoughts on the design of loading the library as a whole (might be out of scope for this PR but worth mentioning):

• I initially made the Session class load the library when it's used to avoid doing this work at import time. Mostly so we wouldn't have GMTLibNotFoundError at import.
• That clearly didn't work because we need to call begin at import for this whole thing to work.
• So it might be time to rethink loading libgmt in the class instead of as a global instead to avoid searching for it every time.
• Or we figure out a way to not call begin at import time.

[leouieda]

And yes, these are the trickiest things to test. Using pytest's monkeypatch is usually a good way to do it so you can trigger errors yourself.

[weiji14]

Cons:

1. It calls the "gmt" command in a new process

2. A much longer list returned by `clib_full_names`. Maybe slower loading?

These cons have been mitigated somewhat in commit 5f17f1e, so the gmt subprocess is only called if necessary (i.e. when looking in GMT_LIBRARY_PATH or the default PATH doesn't work).

3. Difficult to test.

Monkeypatch tests have been added in test_clib_loading.py at commit 243ad13 so there should be full test coverage now. @GenericMappingTools/python-maintainers, give this a review once you have time (particularly on Windows if possible).

[seisman]

@weiji14 Great work!

I just made a few commits to this branch (dbfd7e2, 6769dc3 and c3887ce).

I tested the branch on macOS for many different cases:

• GMT_LIBRAYR_PATH defined
• PATH defined, GMT_LIBRARY_PATH undefined
• both PATH and GMT_LIBRARY_PATH defined
• both PATH and GMT_LIBRARY_PATH undefined, but DYLD_LIBRARY_PATH defined

They all work as I expect (e.g., no extra system calling if the library is already found via GMT_LIBRARY_PATH.

I think this PR is ready to merge. Do we want to merge it into v0.3.0?

[weiji14]

/test-gmt-master

I think this PR is ready to merge. Do we want to merge it into v0.3.0?

Yes please! Once the tests pass. I think there's still some missing code coverage? But we can improve on things later in another iteration.