Refresh and de-duplicate install instructions for users and developers

[edwardchalstrey1]

• mac
• Windows
• Linux

Closes #577

[edwardchalstrey1]

@rahulsavani @tturocy Is the GUI installable on Windows/Linux or only Mac?

[tturocy]

There are .msi installers for Windows built with every release.

[edwardchalstrey1]

There are .msi installers for Windows built with every release.

Thanks Ted, I have changed it to link to the releases page where the installers can be found. I left the mac manual build instructions in since unfortunately my Turing Mac couldn't trust the dmg downloaded from the release page wasn't malware - so I guess others might find this too

[tturocy]

Apple makes it deliberately misleading as to how to install/run unsigned apps. Meanwhile they charge an extortionate amount to sign them (at least from the perspective of an open-source developer). Does Turing have some dev account that can be used to sign these?

Building on Windows is at best going to be complicated, because at present it is going to require having e.g. MinGW installed so as to use the autotools setup, followed by having to have wxWidgets installed correctly as well. While it would be good to document this, equally in truth the documentation for "building Gambit on Windows" would consist of "(1) Throw out your computer and get one that runs MacOS or Linux; (2) See those build directions" It would be easier! :)

[tturocy]

I'm unsure about a few things here in this approach - we definitely need to improve our documentation on this but I'm not sure this is the best way to do it.

First - we already have build directions in src/developer.build.rst. The description here is definitely better than what's there because what's there does assume a bit more background knowledge than what is in this PR so far, whereas this is more explicit. (The developer build docs are also slightly out of date in that they quote wxWidgets 3.1 as the minimum required, and that's now 3.2.)

Putting instructions to build the GUI in what's effectively the GUI user's guide isn't the best place. GUI users in the first instance should be pointed rather firmly to using pre-built versions. The audience for the GUI is primarily those who don't have a lot of coding experience - so putting build instructions in for them isn't going to help! Aside from our provided .dmg (which yes needs better instructions for working around the misleading OSX errors), it's also available via homebrew, and that seems like where we should be pointing them.

We should though move this text into the "developer" build section and update accordingly. Even there, it would also seem like a good idea in the first instance to be pointing users to build Gambit against the homebrew wxWidgets, rather than downloading and building wxWidgets directly. The only reason we download wxWidgets directly in our GitHub action is that the homebrew wxWidgets builds shared libraries - our GitHub action is designed for static linkage so our resulting binary doesn't have any dependencies (including wxWidgets).

[tturocy]

Please see comments in main conversation thread on placement of this and build strategy.

[edwardchalstrey1]

I'm unsure about a few things here in this approach - we definitely need to improve our documentation on this but I'm not sure this is the best way to do it.

First - we already have build directions in src/developer.build.rst. The description here is definitely better than what's there because what's there does assume a bit more background knowledge than what is in this PR so far, whereas this is more explicit. (The developer build docs are also slightly out of date in that they quote wxWidgets 3.1 as the minimum required, and that's now 3.2.)

Putting instructions to build the GUI in what's effectively the GUI user's guide isn't the best place. GUI users in the first instance should be pointed rather firmly to using pre-built versions. The audience for the GUI is primarily those who don't have a lot of coding experience - so putting build instructions in for them isn't going to help! Aside from our provided .dmg (which yes needs better instructions for working around the misleading OSX errors), it's also available via homebrew, and that seems like where we should be pointing them.

We should though move this text into the "developer" build section and update accordingly. Even there, it would also seem like a good idea in the first instance to be pointing users to build Gambit against the homebrew wxWidgets, rather than downloading and building wxWidgets directly. The only reason we download wxWidgets directly in our GitHub action is that the homebrew wxWidgets builds shared libraries - our GitHub action is designed for static linkage so our resulting binary doesn't have any dependencies (including wxWidgets).

Thanks @tturocy I made the following changes:

1. Moved the build instructions to the developer doc
2. Updated the instructions to install wxWidgets via homebrew
3. Bumped the required version stated in the doc to 3.2

[tturocy]

This might be scope creep - but looking at the build instructions file, it seems like it might be better for us to look at that whole section holistically?

The thought is that the section is really imbalanced, with very detailed instructions badged as "building the GUI on MacOS". But actually most of those instructions apply to building the command-line tools as well; they're really not GUI specific. Further, they aren't really Mac-specific either - at least all of the bits about autotools and the like apply across all platforms.

The detail in the new build instructions is a big improvement - I'm thinking that while we are looking at the section we should simply go through and as best we can try to improve/refresh the whole section along those lines, for all platforms.

[tturocy]

And to pile on, I also realised we have an INSTALL.md file which is separate and also now very out-of-date, that should probably be merged into the main documents and INSTALL.md just point to the documentation...

[edwardchalstrey1]

And to pile on, I also realised we have an INSTALL.md file which is separate and also now very out-of-date, that should probably be merged into the main documents and INSTALL.md just point to the documentation...

Thanks @tturocy I think let's discuss and plan today or in another one of our weekly sessions exactly how this should look

[edwardchalstrey1]

Update from meeting 28th October

• Install.md shows the most accurate way to install CLI/GUI (but ignore the gambit-enumpoly section and it doesn't have PyGambit)
• Need to ensure clarity and separation of install instructions for CLI/GUI vs PyGambit and users vs developers and put them in correct places without duplication
• Remove install.md
• Make a website PR in tandem for Revise website install page to link to docs install pages gambitproject.github.io#22

[edwardchalstrey1]

@tturocy @rahulsavani I've had a good go at updating the installation pages today. Let me know your thoughts, here are the key pages with changes:

• Docs homepage now has a clear link to an install page and a quickstart instruction to install pygambit
• New Install page expains PyGambit install and a few different ways to install the CLI/GUI (this page is linked to at the top of the PyGambit, GUI and CLI pages as well)
• Building Gambit from source in the developer docs has also been revised with sequential steps and platform specific parts

The main thing that's lacking are the Windows sections as we discussed, but I think if anything the way I've presented it especially in the dev docs gets across that we haven't tested these recently. We can update these parts in a subsequent pull request.