Installation instructions are not user friendly

[Metaxal]

Problem
The docs don't make it easy enough for non-Racket users to run a package's main they've just heard of. This situation occurs often and yet currently it's not dealt with properly in the docs/website. If it was streamlined, it would make a good first impression on potential new users.

More details
Currently, package designers are forced to explain the whole Install Racket process themselves, often not optimally, and leads to a lot of unnecessary duplication. What is needed is a single link to be provided in the package's README saying "Follow these instructions to install racket and this package".

Some missing information in the docs and webpages:

• download.racket-lang.org gives too little information, despite often being the entry page, such as a link on the package's README saying "Download and install Racket from here".
• Ubuntu/debian: It should say that [sudo] apt install racket should work.
• Linux (other): It should say that one should download the .sh and then run/install it with [sudo] sh racket-<something>.sh
• All platforms: There's no information about how to setup the PATH environment variable for different systems. Something like Pollen's instructions---up to "Then install Pollen."---is a good start.

There should be a webpage detailing how to install a package, given its name, and run it, in the absence of specific information from the package's docs or readme. Something like the following.

Ideally, this webpage would have a get parameter package-name so as to tweak the instructions to the particular package name.

Example webpage:

Install the package:

From DrRacket: Click on "File | Install Package…" then type ${the-package} and click "Install".

Or from the command line:

raco pkg install ${the-package}

Running the program

If no specific instruction is given from the package's documentation or README, try the following.

From DrRacket: In an interaction window, type (require ${the-package}) and press enter

Or from the command line:

racket -l ${the-package}

Thoughts?

[sorawee]

Ubuntu/debian: It should say that [sudo] apt install racket should work.

IMO, most users wouldn't want this. Racket in Ubuntu's official repository is lagged behind for several versions. For example, in the upcoming release (Ubuntu 21.04), it will only provide Racket 7.8.

I feel the current assumption is, if you use Linux, you are a power user. Linking to the PPA is a standard practice to let users know that we provide our own version. That being said, perhaps spelling out the commands needed to be entered might be more friendlier to a fresh Ubuntu user. Then again, if you are a fresh user, you probably can't use shell anyway.

All platforms: There's no information about how to setup the PATH environment variable for different systems. Something like Pollen's instructions---up to "Then install Pollen."---is a good start.

I think this would be nice, though it should be clear that it's optional. A lot of people (particularly students) don't need to set it up.

[Metaxal]

Ubuntu/debian: It should say that [sudo] apt install racket should work.

IMO, most users wouldn't want this. Racket in Ubuntu's official repository is lagged behind for several versions. For example, in the upcoming release (Ubuntu 21.04), it will only provide Racket 7.8.

How come---I thought @takikawa was pretty much on top of it?

But if that's the case, then either apt+lag should be mentioned, or not mentioned at all (as currently). In both cases the instructions to install from the .sh should be given anyway.

I feel the current assumption is, if you use Linux, you are a power user. Linking to the PPA is a standard practice to let users know that we provide our own version. That being said, perhaps spelling out the commands needed to be entered might be more friendlier to a fresh Ubuntu user.

Then again, if you are a fresh user, you probably can't use shell anyway.

What about the nearly-fresh user who's learning to use the command line? Every command-line power user has been through this, right?

Still, there's a difference between "here's the sequence of commands you need to do" and "figure it out yourself", in particular when spelling out the commands is trivial for us and annoying at best for the user.

All platforms: There's no information about how to setup the PATH environment variable for different systems. Something like Pollen's instructions---up to "Then install Pollen."---is a good start.

I think this would be nice, though it should be clear that it's optional. A lot of people (particularly students) don't need to set it up.

I'm okay with a particular webpage set of instructions for students. Their main use case is not the one I described above, and they also can easily reach out to their teacher.

[sorawee]

How come---I thought @takikawa was pretty much on top of it?

Yes, but @takikawa maintains the PPA. There's really nothing we can do re: the official repository. Ubuntu is based on Debian and Debian updates slowly (they want to make sure softwares are "stable"), so Ubuntu updates slowly too.

[Metaxal]

I started something on the wiki: https://github.com/racket/racket/wiki/Installing-Racket-and-trying-out-a-package-or-a-file
Feel free to edit or let me know what you'd change.

[xxyzz]

Mac users can install the latest version of Racket with Homebrew and don't need to edit PATH manually:

$ brew install --cask racket

or

$ brew install minimal-racket

[Metaxal]

Does it have the same problem as apt, that is, it may be a few versions behind?

[mflatt]

I agree about adding instructions to use sh racket-8.0-x86_64-linux-cs.sh on the download page, and I've added that.

I also like the idea idea about having a page that package authors/documentation can point to for installing a package, and the new wiki page looks like a good start.

I'm ambivalent about trying to explain how to set PATH. Partly because there's no simple answer, and partly it it's the same argument here but one level away: that kind of thing should have OS documentation instead of Racket documentation.

Maybe on Windows the installer should offer the option of setting PATH. I think that's common for Windows installers there, and maybe NSIS provides good support for it.

On Mac OS DrRacket should maybe offer a menu item to set /etc/paths.d/racket, something like the way Xcode can install command-line tools. (Or used to? It keeps changing.) In case anyone wonders, though, creating a .pkg for Mac OS isn't a great option; it seems to create more problems than solutions.

On Linux and other Unix variants... I have no good idea how to help with PATH.

In any case, see also here: https://github.com/racket/racket/wiki/Set-your-PATH-environment-variable

[mflatt]

Apparently, adding a menu item to set the command line on Mac OS is a good idea, because it's already there! It's "Configure Command Line for Racket..." in the "Help" menu.

[LiberalArtist]

I may not immediately have a lot of time to work on this, but I can report that non-technical users have found installing a package challenging, even with the GUI and some instructions I've written here. (Feel free to use any of the text or screenshots there if it's useful!)

It looks like someone has started maintaining the non-cask minimal-racket Homebrew formula again, so I should update my notes on that. This may be too much into the weeds for introductory notes, but personally I've come to prefer not to use Homebrew or the PPA for Racket: I tend to regularly do sudo apt update && sudo apt upgrade or the Homebrew equivalent fairly regularly, without a lot of thought, but doing that doesn't migrate my installed packages.

[spdegabrielle]

Notes

@mflatt https://github.com/racket/racket/wiki/Set-your-PATH-environment-variable has been corrected to direct the user to the help menu item

Installing and running Racket for the first time on

• Windows: https://youtu.be/PT9hbSFyP1k
• MacOS: https://youtu.be/o4-baTdEJWQ

[spdegabrielle]

Also relevant https://github.com/racket/racket/wiki/How-to-get-started

[xxyzz]

Does it have the same problem as apt, that is, it may be a few versions behind?

Homebrew updates their packages quite quickly. If it's only version bump and doesn't require any further change, the package will be updated automatically.

Hombrew code: racket cask, minimal-racket formula

[spdegabrielle]

What interests me in this issue is not the struggles people go through to install Racket, though I do applaud the efforts to improve this situation, but the original problem statement; I don’t think you are expected to install the a compiler+ide to play minecraft or DSP.

If an app is intended to run standalone it should be packaged à la https://github.com/racket/racket/wiki/Compiling-standalone-executables (yes I created an inferior one page guide to compiling a standalone app because some people assume Racket is interpreted)

What apps should be packaged this way?

• Graphical Package Manager (this should also stay a part of DrRacket)
• MrEd Designer (can’t be added to DrRacket due to licence - more people would try it but sadly no one knows it exists)
• Others?

Not sure how to improve this situation - maybe update the Scribble in racket-templates for applications to include the basic text on how to Create Executable type:Distribution, or maybe a include shell scripts(for Linux, win &mac) that compile (re)distributable version and sets the icons if it is a gui app, with similar for a command line app, a web-app, a compiler, etc.

[samth]

@LiberalArtist Have you watched people try this? What steps do they get stuck on? One thing I notice is that there are a lot of buttons in that dialog.

[Metaxal]

@spdegabrielle On the PATH wiki, you say:

• If you prefer the command line, you can do sudo sh -c 'echo "/Applications/Racket v8.0/bin" >> /etc/paths.d/racket'
  (If you have installed a previous version you may want to edit /etc/paths.d/racket to remove the old paths. I used vi but you may prefer to delete the file with sudo rm /etc/paths.d/racket, and recreate it with the above command)

What about:

• If you have a single installation of Racket (the default), just type:

sudo sh -c 'echo "/Applications/Racket v8.0/bin" > /etc/paths.d/racket'

• If you have multiple installations of Racket (unusual), type instead:

sudo sh -c 'echo "/Applications/Racket v8.0/bin" >> /etc/paths.d/racket'

but you may wish to edit the file /etc/paths.d/racket to remove obsolete paths.

[Metaxal]

@xxyzz Thanks. I think I prefer to not mention homebrew for this wiki page which targets 'really-new users', since it requires installing additional software.

[Metaxal]

@spdegabrielle Re. standalones. Having binaries would be nice, but you'd need a server that compiles for all platforms. I can't cross-compile my programs to macOS or Windows myself for example.

[Metaxal]

@mflatt

I agree about adding instructions to use sh racket-8.0-x86_64-linux-cs.sh on the download page, and I've added that.

Wonderful, thanks!
Would it be worth mentioning that sudo may be needed for a Unix-style installation?

I'm ambivalent about trying to explain how to set PATH. Partly because there's no simple answer, and partly it it's the same argument here but one level away: that kind of thing should have OS documentation instead of Racket documentation.

Maybe on Windows the installer should offer the option of setting PATH. I think that's common for Windows installers there, and maybe NSIS provides good support for it.

That would be great!

In any case, see also here: https://github.com/racket/racket/wiki/Set-your-PATH-environment-variable

I've updated this wiki page to add instructions for Linux, and to mention homebrew and apt.

[Metaxal]

The new instructions are starting to be pretty decent I think, and they are complete:
https://github.com/racket/racket/wiki/Installing-Racket-and-trying-out-a-package-or-a-file

Any comment to improve this is welcome! It would also be great to actually test it with real new users and get feedback.

[Metaxal]

One thing I can't make up my mind on is whether we should split the page in 2: One page for GUI, on page for CLI.
The reason is that there should be just the minimum amount of information so that the user (in particular a really-new user) doesn't feel overwhelmed.
But adding a level of indirection is also not ideal.

Thoughts?

[mflatt]

@Metaxal Good point about sudo. I'll add that.

Robby is making the "Configure Command Line for Racket..." menu item work in DrRacket on Windows. Adding an option to the installer appears to be complicated, but it might be relatively easy to add a note to the installer saying that DrRacket provides the option.

[Metaxal]

I added this line, hopefully it's accurate:

On Windows 10:

• Racket 8.1 or later: In DrRacket, click on Help then Configure Command Line for Racket…: This will configure your PATH environment variable properly.

[rfindler]

I put something to the drracket Help|Configure Command Line for Racket... menu item under unix that tells people where the path is, but doens't try to do anything about it. Comments welcome

[jackfirth]

@mflatt @rfindler I just tried the "Configure Command Line for Racket" option in DrRacket 8.0 on macOS, and it did set the PATH for racket and raco... but not for user-scope racket-launcher-names binaries. Those live in a different location that seems like it should also be added to the PATH.

[mflatt]

@jackfirth I thought about that too.

On Windows, that seems like a fine idea, except that the path is going to have a version number in it, so DrRacket may need to be smart about removing old paths as a adds new ones. Or there could be a configuration change so that the path doesn't have a version, but that's a whole new set of trade-offs.

On Mac OS, I worry about adding a user-specific path to /etc/path.d/. There doesn't appear to be a user-specific variant of that, and if not, you're back to Unix-style PATH management for an individual user.

[Metaxal]

@rfindler

I put something to the drracket Help|Configure Command Line for Racket... menu item under unix that tells people where the path is, but doens't try to do anything about it. Comments welcome

That's a start :)

Normally, the following line should go into ~/.profile:

export PATH=$PATH:<path to racket>

with a couple of caveats that can be checked.

If you're worried about cluttering the .profile with many racket paths, how about this:
In the .profile, add the following lines if they don't exist already:

racket_paths_file=~/path/to/fixed/file
if [ -f "$racket_paths_file" ]; then
  export PATH=$PATH:$(cat "$racket_paths_file")
fi

(I haven't checked if it really works as is though)
Then it's easy to handle the $racket_paths_file to remove/update paths.

Ideally this would all be done by the .sh installer (if local installation) and possibly by the Help menu in DrRacket.

[rfindler]

I'm a bit skeptical that we can really accommodate anything close to the number of different ways one can install unix. Is it really reasonable to assume that they're using a bash shell? Or ubuntu? Even under macOS, zsh has become the default shell so using bash-based instructions wouldn't work there. (I realize we're not talking about macOS but that's just the OS I'm most familiar with.)

[Metaxal]

.profile is sh based and used quite widely by many shells (not just bash/ubuntu). But it appears that zsh sometimes(?) has a .zprofile. If that's the case, either we add these lines to both files if they exist I guess?

[rfindler]

I really don't think it is a good idea for us to get into the business of dealing with the huge number of possibilities here. It might make sense for us to try to detect, say, one or two popular unix installation (perhaps ubuntu) and then use some ubuntu-provided tool that does path manipulation (so we know it will work on multiple different versions of ubuntu and probably continue to work going forward), which is the case for macOS and Windows but I'm skeptical of more than that.

[mflatt]

I learn toward Robby's view. We try to make tools that fit into the usual ways of doing things on a given OS. Unlike Windows or (to a much lesser degree) Mac OS, it’s not typical or expected for a program to try to modify the PATH setting permanently. I vaguely recall installers in a Unix-style environment years ago that would try to modify files like ~/.profile, and I was left with the impression that it didn't work out and that installers stopped doing that.

[Metaxal]

How about asking whether to add symlinks into ~/bin or ~/usr/bin if they exists? (for non-unix style installation)

If they don't exist, we could at least give the correct path and tell the user to do that themselves maybe?

[rfindler]

Are these things set up in various distributions typically? I tried to google around to find docs about it but came up empty.

[Metaxal]

It appears that a default .profile on Ubuntu includes ~/bin and ~/.local/bin in the path (not sure where I got ~/usr/bin from)

[samth]

I think the situation is somewhat different than what @mflatt remembers. Mostly, other languages that I've found are not distributed as executable installers on Linux (as Racket is), and so this mostly doesn't come up. However, the last few years has seen a big trend in "toolchain managers" which install systems for you to make this easier, and these are almost always (a) executable installers and (b) installed via curl SOMEURL | sh. Almost all of these modify the user's shell initialization by default.

Here are all the ones I could find:

• Deno (a nodejs-like system which is only installed this way) prints a message at the end of the installation process about how to edit my $PATH settings.
• rustup, the installer for Rust, modifies ~/.profile by default. Note that unlike all the others, this is the recommended way to install Rust.
• ghcup (for GHC) prompts for whether it should modify .bashrc
• Volta, which is a toolchain manager for Node, modifies .profile without giving an option.
• nvm (another Node toolchain manager) modified my .bashrc but not .profile.
• RVM (a ruby toolchain manager) modifies .profile, .bashrc, .zshrc, .bash_profile, .mkshrc, and .zlogin.
• rbenv (another ruby toolchain manager) prints a message about how to modify files to set the PATH.
• hygiea (a Python toolchain manager) modifies .$SHELLrc.
• pyenv-installer (an installer for pyenv, a python toolchain manager) says that it will modify .bashrc in the docs, but didn't on my system and printed a message about what to put there.
• stack (the Haskell package manager, which is also installed with curl | sh) by default installs in /usr/local/bin but if you pick a different directory it checks if that's in your PATH and prints a warning if not (but no instructions).

I also looked at the installation pages for several other languages themselves.

The Go installation page explains what to change in .profile. The Swift installation page contains somewhat less helpful instructions about $PATH. Node distributes binaries and provides no instructions. Rust (if you ignore their rustup recommendations and click through a lot of things) provides an installer shell script that doesn't set the PATH. Python just distributes sources and suggests sudo make install. Scala recommends that I install .deb packages (that they provide, not the default Ubuntu ones) as root.

[Metaxal]

@samth Based on all this, would you recommend something?

[LiberalArtist]

@jackfirth

@mflatt @rfindler I just tried the "Configure Command Line for Racket" option in DrRacket 8.0 on macOS, and it did set the PATH for racket and raco... but not for user-scope racket-launcher-names binaries. Those live in a different location that seems like it should also be added to the PATH.
@mflatt
On Mac OS, I worry about adding a user-specific path to /etc/path.d/. There doesn't appear to be a user-specific variant of that, and if not, you're back to Unix-style PATH management for an individual user.

On Mac OS, the first thing I do when I download a new Racket release is raco pkg config my default package scope to installation, precisely for the sake of racket-/gracket-launcher-names. I think that would be a much more tractable recommendation than explaining how to set your user-specific PATH, which is a much harder task than it should be.

In general, I would think command-line-oriented Unix users would be familiar with setting up there PATH as something they do occasionally. (Or have a tool do for them, for better or for worse: I'd add conda to @samth's list, which has you source a shell script that defines a bunch of functions, but doesn't actually change your PATH until/unless you use some of those functions.) Further, the distinction between the rc and profile depends on subtle things like what terminal emulator you use (does it start login shells?) and what your desktop/window-manager sets up as it's initial environment. My preference on non-Mac Unix would be instructions on what directories to put on my path, perhaps with a pointer to docs from a popular distro or two. I don't like it when tools change these files automatically; they don't always do it well, and they don't always make it clear what they've changed. (In contrast, I quite like the Mac /etc/path.d mechanism.)

But the non-technical users I support—and even some of the technical ones—much prefer working with a GUI than a command line, and, as I said, even that can be challenging.

[LiberalArtist]

re @samth:

@LiberalArtist Have you watched people try this? What steps do they get stuck on? One thing I notice is that there are a lot of buttons in that dialog.

Unfortunately it's almost entirely remote: IIRC, one of the few exceptions prompted me to write that guide afterwords.

I agree that there are a lot of buttons. The initial tab is labeled Do What I Mean with a field Package Source and, until you type one, there's a greyed-out Install button: I'm not sure this makes it obvious that you've come to the right place.

I see now (I don't know if it existed when I last updated those notes) that, in addition to File|Package Manager…, DrRacket also has File|Install Package…: I think that simpler interface is an improvement, though the dialog was a bit of an awkward size for me just now:

One thing that I know has posed a challenge is that this GUI is sort of like a command line: the user has to copy-and-paste or type in the name of the package exactly, e.g. case-sensitively and in kebab case. Then the feedback you get is the stream of textual output that raco pkg would produce.

For comparison, in Emacs, when I go to Options|Manage Emacs Packages, I get a listing not altogether unlike the Available from Catalog tab in DrRacket's package manager, but with clickable links that open a synopsis with an Install button:

[samth]

As for what we should do, I think the shell-script installer should offer to set the path. The best way to do this is probably to add a line like source <something>/init.sh at the end of ~/.profile and create an init.sh shell script that gets installed with the rest of the distribution.

[Metaxal]

I like this. This looks like a simple enough solution. Here's a more general but more convoluted one (so possibly more likely to fail and harder to maintain?).

• Offer(*) to update ~/.profile as per @samth 's proposal.
• Note that ~/.profile is sourced only if ~/.bash_profile and ~/.bash_login don't exist. Hence if at least one of these exists, also offer(*) to update/create ~/.bash_profile.
• If ~/.zprofile exists (for zsh), also offer(*) to update it.

(*) Skip the offer if the corresponding file already calls source <something>/init.sh.

If any change has been made:

• Mention that the effects will take effect after the next reboot (because .profile is sourced globally only upon startup, not when running a new terminal).
• Print what to do on the command line to set the path in the current terminal.

Note that users that have already been through the process above in a previous installation will likely not see any of the above.

Maybe setting the command line should also be part of a raco subcommand or some standalone program, so as to trigger it any time.

(edit: add (*) Skip.)

[gus-massa]

For unrelated reasons I just checked the Haskell instructions. They have an (arbitrary?) list of Linux distributions https://www.haskell.org/ghc/distribution_packages.html

[samdphillips]

re: user-scope racket-launcher-names binaries

Would it make sense to try and install these in $HOME/.local/bin or $HOME/bin?

TIL: on an OS with systemd the systemd-path command gives you some useful info:

$ systemd-path user-binaries
/home/sam/.local/bin