search

GenericMappingTools / gmt

The Generic Mapping Tools
https://www.generic-mapping-tools.org
Other
843 stars 352 forks source link

Unify and update install instructions #472

Closed leouieda closed 5 years ago

leouieda commented 5 years ago

Currently, the install instructions for GMT (compiled and from source) and spread over several different pages:

Some of the instructions are repeated, some are incomplete, some are outdated or out of sync. It would be best to unify these into one or two pages with links to them distributed widely within the project for easy access. While we're at it, we should make sure that the instructions actually work on all platforms. A good way to keep them updated is to fix the instructions when a user is having trouble instead of replying in the issue/forum only to have it come up again the next month.

A few options for doing this:

  1. A "Installing" page in the docs (as .rst) for the compiled packages and a BUILDING.md/COMPILING.md file in the top-level of the repository. Keeping the compiling instructions separate might be good because people will be building from the master branch and released instructions would quickly get out-of-date.
  2. Pages in Wiki of the repository. I don't like this too much because we would have to keep different pages for every release (or risk people following the 5.4 instructions to install 6.0).
  3. A combination of the above.

The compiling instructions are specially difficult to follow, even for people with moderate computer skills. I expect that many people give up after failing to get GMT building properly (or even worse, get stuck compiling some dependency on Windows).

leouieda commented 5 years ago

@joa-quim do you use any package manager on Windows to install our dependencies? I remember you mentioning something like that in Faro but I forget. If so, then we should probably recommend it as a way to get dependencies installed for building GMT on Windows.

joa-quim commented 5 years ago

No, I still build all the dependencies myself. What mentioned in Faro was the use of Vcpkg as a future way of building GMT (the dependencies are already build-able) . Actually after that I was able to make a portfile (a recipe) that built GMT but I broken it after while trying to make it work for both released versions as well as master. Easy to make it work again but I would like to have both build possibilities. But anyway, I didn't make a PR of that portfile yet to the VCpkg repo.

leouieda commented 5 years ago

Thanks for link. I don't think we need it as a way of getting a GMT master package but at least as a way of easily installing our dependencies when people want to build from source (like we have for Ubuntu and Mac).

seisman commented 5 years ago

Can we add both ("Installing" for binary packages and "Building" for compiling from source) in the top-level of the repo and then include them into the documentations?

Since the compiled packages of most Linux distros are way behind the latest GMT release and out of our control, Linux users usually cannot install the latest release by following the "Installing" instructions and have to compile from source.

seisman commented 5 years ago

@leouieda I've created a PR #484 to address this issue. Feel free to make any changes you want to that PR.

PaulWessel commented 5 years ago

I had a look at the PR and it looks good to me. Let's see what @leouieda says and if OK we can merge.

seisman commented 5 years ago

No. Don't merge that PR now. We still need to improve the install instructions.

PaulWessel commented 5 years ago

No worries, will no do it!

leouieda commented 5 years ago

@seisman we could try to include them in the docs but it would be easier then to write them in rst instead of md. But I don't know if it's worth having it in two places (docs and repo top level), even if we reuse the same file. What do others think?

leouieda commented 5 years ago

The PR only renamed the file for now, right? Did I miss something?

joa-quim commented 5 years ago

I think we should have the installing instructions only at the repo. And even there I would prefer to have them as links to other dedicated pages instead of having the details directly on sight. That's certainly boring to most visitors.

seisman commented 5 years ago

@leouieda Yes, I made no changes in that PR. I opened that PR so that we can make changes while discussing.

@joa-quim I'm OK with "having the installing instruction only at the repo". I also agree that we shouldn't put detailed installing instructions in README.md.

daxsoule commented 5 years ago

I am currently trying to install GMT on a PANGEO server with the hope of developing my maps using pygmt and jupyter notebooks. I have cloned the repos and created the environments contained in the .yml files and yet I am still struggling to understand how to get up and running.

@leouieda @PaulWessel, If either of you were willing to help me walk through the process we could develop a "Zero to GMT" notebook that addresses many of the things discussed in this thread and perhaps provide a smoother onramp for future users. Mapping out all of my wrong turns and places where the instructions did not get me from point A to point B would likely help a lot of folks.

PaulWessel commented 5 years ago

This is great @daxsoule. I'm just a dumb C programmer but @leouieda will help you out.

leouieda commented 5 years ago

:wave: @daxsoule Thanks for reaching out! This is an interesting use case and most of us don't have much experience with this. I like your idea of "Mapping out all of my wrong turns". We definitely need non-core devs trying out these instructions to make sure they're actually useful.

I have cloned the repos and created the environments contained in the .yml files

Could you be a bit more specific? Which files? Which repos? Right now, PyGMT requires building GMT from source. So creating a conda environment is not enough.

daxsoule commented 5 years ago

The repos I cloned are gmt and pygmt. I have an environment created from the environment.yml that is part of the pygmt repo. I now understand that cloning and creating an environment is not sufficient, unfortunately I am quite stuck. I have a working instance of GMT (5.4.4) on my local machine that I launch from the an app, but I have been completely unsuccessful in moving this functionality to the cloud and rendering it from a Jupiter notebook.

leouieda commented 5 years ago

I think the comments in #588 should solve your problem with gettting GMT 5.4.5 installed with conda. You can use command line GMT in Jupyter with %%bash cells and IPython.display.Image. Getting the conda packages working is a bit of a challenge but it's getting better.