Discussion: py-rse setup instructions

[DamienIrving]

Now that the content of the RSE book is more or less settled, we need to sort out our setup instructions.

Where does the information go?

The current py-rse/install.md file says the following:

FIXME: link to installation instructions on our website
FIXME: link to instructions for downloading sample files.

So the idea is to provide the setup information on our website (rather than in the printed book) to allow for the fact that instructions for installing software are constantly evolving. Questions relevant to that plan:

1. What is our website? I'm guessing we won't stick with https://merely-useful.github.io/ if the book isn't called Merely Useful.
2. Where on the website does the setup information go?

I guess for now we can just keep the information in a setup.md file.

What information do we provide?

Readers of the book need to install the following:

1. Bash shell
2. Git
3. Text editor
4. Python (Anaconda)
5. Make

For 1-4, instructions for Windows, Mac and Linux (with video tutorials) are maintained by The Carpentries, so we can direct people to https://carpentries.github.io/workshop-template/#setup.

For 5, there are some notes on installing Make that accompany the Software Carpentry automation lessons, but I suspect they aren't updated as regularly as the general Carpentries installation instructions and hence we might want to write/maintain our own.

We'll also need a zip file with the initial data files and folder structure, which is discussed in #426.

The only hitch here is that the conda command is not automatically available using Git Bash. This means that Windows users (at least those on older windows machines that don't have a native bash shell) cannot use conda from the bash shell, which we do in the "software environment" section of the Provenance chapter and the "virtual environments" and "exercises" sections of the Packaging chapter. The solution is to update your Anaconda path by doing the following:

• Open the Anaconda Prompt program (via the Windows start menu) and enter where python to find the path of the Anaconda3 directory (the output should show a path similar to C:\Users\Username\Anaconda3\python.exe)
  • Convert that path for use in the next step by doing the following:
  • Replace all instances of \ with /
  • Replace C: with /c
  • Replace python.exe with Scripts/activate
  • e.g. if you got C:\Users\Username\Anaconda3\python.exe from the previous step, you will use /c/Users/Username/Anaconda3/Scripts/activate for the next step
• Go back to Git Bash and run echo "source [Anaconda path]" >> ~/.profile && source ~/.profile, replacing [Anaconda path] with the path you generated in the previous step

Should I go ahead and create a setup.md file with this information in it, or do people have other thoughts on how the setup should be handled?

[joelostblom]

I agree with linking 1-4.

Regarding accessing conda from Git bash, you can make it available with conda init. Open the Anaconda Prompt and run conda init bash, which will add the necessary line to ~/.bash_profile.

Regarding 5, I wrote about makefor windows previously, which I have modified below, what do you think (this is using the same make binaries as the scoop package installer for windows, which I imagine is a recent and trustworthy source, make is also available via the chochoately package installer if we want to go that route)?

## Make

[Download `make` from this URL](https://downloads.sourceforge.net/project/ezwinports/make-4.3-without-guile-w32-bin.zip). Click on the downloaded zip-file to open it in the File Explorer, click the "Extract" tab and the button in the header that says "Extract all" and accept the default extraction location.

Next we need to add the `bin` folder in this extraction location to our PATH so that we can use `make` from the terminal. Open the bash configuration file with VS Code by pasting this into a terminal:

code ~/.bash_profile

And prepend the `make` folder to the path by adding this line:

Add Make to path

export PATH="/c/Users/${USERNAME}/Documents/make-4.3-without-guile-w32-bin/bin":$PATH

Launch a new terminal and run

make --version

which should return something like

GNU Make 4.3 Built for Windows32 Copyright (C) 1988-2020 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

[DamienIrving]

Oh, wow, conda init bash from the Anaconda Prompt is much easier!

In terms of Make, is choco install make all you'd have to do if we went the Chocolatey route? (i.e. would that mean it was available from Git Bash without editing bash_profile?) And are there other pros or cons associated with introducing Chocolatey?

[joelostblom]

For chocolatey, I am not sure actually. I have seen that this is a popular alternative but when I was going to try it, I noticed that it requires a few step in powershell to install the package manager, and I thought it was not worth it for teaching nonice students and when only doing it for a single package (since we're intermediate itmight be ok) https://chocolatey.org/install.

[gvwilson]

https://ubc-mds.github.io/resources_pages/installation_instructions/ may be useful