factor
Install script for Factor's dependencies on Linux should be added and/or mentioned on the main site, etc.
The Problem:
When I first tried to use Factor on Linux I couldn't seem to get it working. It kept giving missing library related error messages.
However, after some internet searching I found that the Concatenative.org site's page on installing Factor linked to a requirements page that finally described how to actually install the required dependencies to run Factor.
(Side-Note: The requirement page's mention of not including the libgl1-mesa-dev if you use proprietary drivers is out of date. The provided command already doesn't include that library. Thus, it should actually say that users should install libgl1-mesa-dev if they don't have proprietary drivers installed. I do have proprietary Nvidia drivers installed though, so I didn't test this though.)
None of this is mentioned on the main Factor site though, nor is any automated script provided in the package, which likely misleads many (most?) new users into thinking the Linux package might be broken in general and/or on their specific system and likely greatly reducing how many Linux users end up ever trying Factor or contributing to it.
Even slight friction in install processes are known to cause huge decreases in user adoption rates and this friction mentioned here is far worse than slight considering that the main site doesn't even mention the basic requirements.
The Solution:
Thus, I suggest doing both of the following:
- Mention the prerequisites and how to get them on the main site.
- Add a simple installer script for Linux users and put it in the root of the main package.
It could literally just be a copy of the one line command to install the prerequisites mentioned on the requirements page linked above:
apt --yes install libc6-dev libpango1.0-dev libx11-dev xorg-dev libgtk2.0-dev gtk2-engines-pixbuf libgtkglext1-dev wget git git-doc rlwrap gcc g++ make
apt doesn't redundantly install already installed packages, so this can just be run as is.
Some associated commentary in the script could inform users why it is there (i.e. for Linux users to make Factor usable).
The file could be named install_Linux_prerequisites.sh or whatever else. It would be obvious what the purpose is.
Additional Remarks:
Concatenative languages are very interesting and should be more widely experimented with, but friction in the process reduces user adoption rates which therefore also (like a domino effect) also ends up reducing the available contributors as well. Never underestimate the harm that having a poor install process or uncommunicative documentation or websites can cause. Even the best software in the world would still fail or lose to the competition if poorly communicated to users or needlessly tedious. This is also ironic given that the whole point of programming is arguably eliminating tedium and yet we have so many software systems that require tedious hunting down of information even for the most basic use cases. The more that is handled properly the better user adoption rates will be, as with all software.
As an extra: Perhaps informing the user that a launcher for the "start menu" can also be created and a general sense of how to do that on a few common desktop environments could also perhaps be provided in a provided readme document. It was easy to set up on Linux Mint Xfce for me. It could potentially even be automated by detecting the distro and/or desktop environment. This is not as important as adding the trivially simple installer script though.
The fact that (1) the Factor folder can be moved around wherever the user wishes and (2) that its root (where the factor executable/binary is) can be added to the path so that it can opened from the command line whenever desired could also be mentioned in the install script or elsewhere. That would even further improve the new user experience.
Debian is the most popular distro family, but similar install scripts could also be added for other distro if applicable or possible. I haven't tested others with that. Regardless, even just providing a script for Debian family distros (like Ubuntu and Mint, etc) is a big improvement in reducing user friction despite how "trivial" it may seem.
I agree that we could do a better job here. Some comments...
We have some of this in the build script:
$ ./build.sh help
usage: ./build.sh command [optional-target]
...
deps-apt - install required packages for Factor on Linux using apt
deps-pacman - install required packages for Factor on Linux using pacman
deps-dnf - install required packages for Factor on Linux using dnf
deps-pkg - install required packages for Factor on FreeBSD using pkg
deps-apk - install required packages for Factor on Alpine Linux using apk
deps-macos - install git on macOS using port
...
But that doesn't help if the binary distribution doesn't include build.sh!
The other thing making distribution hard is the name conflict with https://man7.org/linux/man-pages/man1/factor.1.html
I'm glad you agree and I hope that Factor sees some improvement in this regard in the future. It'd help retain more users and/or at least expand people's perspectives on what's possible in programming languages more, etc.
I wasn't aware of the name conflict with with a pre-existing factor. Perhaps an installed name like factor-lang would be a reasonable compromise for increasing the odds of distros accepting it. There are many system binaries that already use hyphens or even (more rarely) underscores on Linux.
Anyway, good to hear from you and have a great day/night! 🦖🌠😎
Definitely agree. I'd had trouble with dependencies, too. The apt-get should be on the factor main web page and should accompany other distros' dependency install commands (like https://github.com/zsa/wally/wiki/Linux-install). By the way, for Arch Linux, it's either yay -S factor-git or yay -S factor (require yay(1) or other AUR package manager); or to install only factor dependencies if one wants to maintain & build their own factor fork: sudo pacman -S pango cairo glib2 freetype2 mesa libgl gtkglext.
Historically it was always on the wiki: https://concatenative.org/wiki/view/Factor/Requirements
But this means maintaining it well, i'm not sure it's up to date right now. IMHO having it in code is better, it's actually tested and updated ?
Note: the new wiki looks great ! didn't know it was restyled ! The old one was like this http://web.archive.org/web/20180702041247/https://concatenative.org/wiki/view/Factor/Requirements
EDIT: Sorry, the wiki was already mentionned in the original report... So my only point is about having it in code that's actually used and maintained versus some documentation that could be out of date
@jonenst to have the dependencies (and their install commands) automatically computed would be ideal but unachievable. Each package manager has unique quirks, the least of which is how they name equivalent packages. To have any one system test multiple install commands would mean using many package managers simultaneously, which is impractical. Also, we'd need to consider how to handle a package failing to compile; if it's because a package is no longer maintained, is that because it needs a new maintainer, or was the package deprecated, etc. There are surprisingly many possible cases.
Still, the onus of maintaining correct commands is better put upon users rather than whoever maintains factor's website; so we need something user-editable. Each user of a given package manager can test & correct their install command(s). People can easily contribute to factor's github. If the factor website were to dynamically load code from the repo, then it'd be up-to-date. Or, the factor website could link to its github for latest install instructions. Idk anything about github wiki's, but maybe they're an option.
This all said, I think that this concern reflects a greater one which behooves us to take a step back and reconsider some more fundamental things.
About concatenative.org vs [docs.]factorcode.org: I can see how newcomers would be confused about there being two domains; of course, one seems more official (reliable, certain—important attributes for newcomers) than the other, especially since the other refers to many abandoned, theoretical, toy, or out-of-date projects. It's not clear that both sites are maintained by the same people, and so that factor is better-updated on the wiki, whereas other catlangs are more likely to update on each their respective sites (usually their github repo's readme.)
Also, Factor is the only concatenative language that has enough functionality to actually be useful for real-world projects. I can't blame anyone for simply denouncing all catlangs at once, since nearly all of them are either undeveloped, or are literally forth, which is found online only in historical or theoretical language discussion, or as a smattering of obviously pre-90's webpages of code snippets/libs lingering around like ghosts. Factor has a bias to overcome!
Thus it seems perhaps lofty, yet due, that the factor-specific information of concatenative.org be merged into factorcode.org, and the non-factor parts remain in concatinative.org; and, by the way, that that new factor site be revamped to be more modern, and streamlined so that people can overview the important vocabs, learn the language feature-by-feature (such as java's Really Big Index, or zig's langref. There's a lot to say about that, but it's a separate topic.
Good to hear that it sounds like some form of this change will be implemented at some point! 😎🍀
Any solution that covers the majority of uses cases and the most common distros would be much better than keeping things disorganized and leaving users in the dark. Even for unsupported (more obscure) distros, having reference scripts for installing prerequisites on the most common distros would greatly illuminate the most likely avenues for making the software work, since that at least gives users an idea of what the prerequisites are like on common systems.
A 90%+ solution that exists in a reasonable from of time and with reasonable resources is far better than a 100% solution that doesn't exist and is too impractical to create. Fence post issues at the margins of software shouldn't be allowed to prevent reasonable common cases from being convenient for most uses and for most people. Including some installer scripts in a the root or in a sub folder of the root won't hurt anybody but will add good value and convenience.