Installing Zeno: a setup program, and one line
A release of Zeno is an archive for each kind of machine
(release.md). To use one, somebody has to know which
of ten files is theirs, unpack it, find a folder for zeno, put that
folder on the PATH, and then find out, from an error, that zeno
build wanted a C compiler. Each step is small, and each is a place to
give up.
So there are two installers that do all of it.
On Windows, a setup program, as Python has:
zeno-0.2.0-windows-setup.exe
Run it and press Next. It is the same file for every Windows machine.
On macOS and Linux, one line in a terminal, as Rust has:
curl -fsSL https://github.com/partham20/zeno-lang/releases/latest/download/install.sh | sh
Both do the same five things:
- Work out which
zenothis machine needs. - Put it,
zeno.wasm, the docs, the examples and the editor setup in a folder that belongs to the user. Nothing asks for an administrator's password. - Add that folder to the PATH, so that
zenoworks in any terminal opened afterwards. - Look for the programs that parts of Zeno hand work to, and offer to install the ones that are missing.
- Leave a way to take all of it off again.
The archives are still there, for anyone who would rather do it by
hand. The decisions are chapter 15 of decisions.md.
What Zeno needs, and what it does not
zeno is one file that needs nothing else to check, run, test and
format a program. Three commands hand part of their work to another
program:
| Command | Hands work to |
|---|---|
zeno build |
a C compiler: cc, gcc or clang |
zeno build --llvm |
clang |
zeno fetch |
git |
zeno build --web |
nothing, but zeno.wasm must be beside zeno |
That is the whole of "whatever is needed", and the installers offer
it: a C compiler and git. They ask first. A compiler is a few hundred
megabytes that somebody who only wants zeno run does not need, and
it is installed by the system's own package manager, which on Linux
wants a password.
zeno build used to want set CC=gcc on Windows, which has no cc.
It now tries cc, then gcc, then clang, and uses the first that
is installed. CC still names another.
The setup program for Windows
It installs into %LOCALAPPDATA%\Programs\Zeno, which is where
Windows puts programs that are installed for one user. Its pages:
- Where to install. The folder above, unless another is chosen.
- What to do besides. - Add Zeno to the PATH. Ticked. Python's installer leaves its own box unticked, and "python is not recognized" is the first thing many people see of Python. - Install a C compiler. Shown only if this machine has none. - Install Git. Shown only if this machine has none.
- Install.
The two tools are installed by winget, the package manager that
comes with Windows 10 and 11: the compiler is WinLibs (gcc, and clang
too, so zeno build --llvm works as well), and Git is Git for
Windows. On a machine without winget the two boxes are not shown.
In the Start menu it leaves a folder, Zeno, with four things: Zeno
Prompt (a terminal in which zeno works even if the PATH was left
alone), the examples, the docs, and Uninstall Zeno. Zeno is also
in the list of installed apps in Windows' settings, where it can be
removed like any other. Uninstalling removes the folder and takes it
out of the PATH. The compiler and Git are programs of their own and
stay.
A newer version is installed over an older one: the setup program finds the folder by itself.
One file for three processors
The setup program holds three zeno.exe: for x86-64, for 32-bit x86
and for ARM64. It asks Windows which processor it is on and installs
that one. Zeno is small enough (a few megabytes each) that three
in one file is easier than three files and a question.
Windows will warn about it
The first time it is run, Windows says "Windows protected your PC", with a "More info" link that leads to "Run anyway". Windows shows this for every program whose maker has not bought a certificate to sign it with, until enough people have run it. Nothing is wrong with the file. A certificate costs money every year, and is not worth buying for a language that is being learnt on (15.6).
How it is made
tools/installer/zeno.iss is a script
for Inno Setup, a free program that turns such a script into a
setup .exe. Most of it is lists: which files go where, which boxes
to show, which shortcuts to make. The part that is code is at the end,
in Pascal, and does three things the lists cannot: choose the
zeno.exe for this processor, look for gcc and git on the PATH,
and add a folder to the PATH and take it out again.
The PATH of a user is one piece of text in the registry, under
HKEY_CURRENT_USER\Environment, with ; between the folders.
AddToPath reads it, adds the folder at the end unless it is there,
and writes it back. RemoveFromPath puts a ; at each end of the
text, so that every folder in it reads ;folder;, and cuts out the
one that matches. Setup then tells the programs that are running that
the environment has changed, which is why a terminal opened after it
finds zeno and one that was already open does not.
tools\installer\build.cmd 0.2.0 files makes zeno-0.2.0-windows-setup.exe
pwsh tools\installer\try.ps1 zeno-0.2.0-windows-setup.exe
try.ps1 installs without showing a window, checks that zeno is
there, runs and is on the PATH, that it builds a page, that installing
twice leaves the PATH with one entry, and that uninstalling leaves
nothing. The release workflow runs it on the setup program before
releasing it.
The line for macOS and Linux
curl -fsSL https://github.com/partham20/zeno-lang/releases/latest/download/install.sh | sh
curl downloads tools/install.sh, which is a
file of every release, and sh runs it. It is a shell script of about
three hundred lines, half of them comments, written for the plainest
shell there is, and it is meant to be read before it is trusted.
Zeno 0.2.0 for macos on arm64
from https://github.com/partham20/zeno-lang/releases/download/v0.2.0
the download is whole
installed zeno 0.2.0 in /Users/partha/.zeno
added it to the PATH, in /Users/partha/.zshrc
Zeno is installed. Open a new terminal, so that it is on the PATH, and try it:
zeno run /Users/partha/.zeno/examples/hello.zeno
zeno new first
What it does, in order:
- Which machine.
uname -ssays Linux or Darwin (macOS), anduname -mthe processor. A Raspberry Pi with the 32-bit system on a 64-bit processor saysaarch64and gets the 32-bit Zeno, because that is what its system runs. - The download, with
curlorwget, of the archive and ofSHA256SUMS.txt. - The check. The archive's checksum must be the one the release lists. If it is not, nothing is unpacked.
- The install, into
~/.zeno:bin/zeno,bin/zeno.wasm, and the docs, examples and editors besidebin. An older Zeno there is replaced. A folder that holds something else is refused, so that a wrongZENO_HOMEcannot empty it. - The PATH. One line at the end of the startup file of the shell
in use:
.zshrc,.bashrc(.bash_profileon macOS),config.fish, or.profile. The line ends with a comment,# added by the Zeno installer, which is how the script knows not to add it twice and how--uninstallfinds it. - The tools. On Linux, if there is no
cc,gccorclang, it says so and asks whether to install one with the system's package manager (apt-get,dnf,yum,pacman,zypperorapk), and the same forgit. On macOS both come with Apple's command line tools, and it offersxcode-select --install. The question is asked of the terminal, not of the script's input, because withcurl ... | shthe input is the script.
On macOS this also avoids a step the archives need: a file that a
browser downloads is held back by macOS until xattr -d
com.apple.quarantine is run on it, and a file that curl downloads
is not.
sh install.sh --yes # install the missing tools without asking
sh install.sh --no-tools # do not look for them
sh install.sh --uninstall # remove ~/.zeno and the PATH line
curl -fsSL .../install.sh | sh -s -- --yes # options, when piped
ZENO_VERSION installs another version, ZENO_HOME into another
folder, and ZENO_FROM from another place, which can be a folder.
That last one is how it is tried:
tools/try-install.sh packs the zeno
that was just built as a release would, installs it from that folder
into a home folder of its own, and checks the same things try.ps1
does, and that a download with one byte added is refused.
In the release
release.yml has a job after the
ten builds, windows-setup, that takes the three Windows builds,
makes the setup program, and tries it. The Linux and macOS builds that
run on their own processor run try-install.sh. If either fails,
there is no release.
A release then has twelve files and their checksums: the ten archives,
zeno-0.2.0-windows-setup.exe and install.sh.
.github/workflows/installer.yml tries the installers on one machine
without a release, and keeps the setup program it made for a week, to
download and run by hand.
For a version that was released before
Zeno 0.1.0 was released the day before there were installers. It has
them too, added afterwards by
add-installers.yml, which
is started by hand with a version:
- It downloads the three Windows archives of that release, checks
them against the release's
SHA256SUMS.txt, and makes the setup program from the threezeno.exein them. Nothing is built again: what the setup program installs is what was released. - It takes today's
install.sh, writes that version into itsversion=line, and has it install the released Linux archive into a home folder of its own. - Only if both passed, and "add" was ticked, it adds the two files to
the release, and two lines to its
SHA256SUMS.txt. The lines of the archives stay as they were.
Two things differ for 0.1.0, and the installers allow for both.
It has no zeno.wasm, so the setup program leaves that out and
try.ps1 does not build a page. And its zeno build runs cc and
nothing else, so on Windows it still wants set CC=gcc first: the
box that offers the compiler says so.
So each release has its own install.sh, at
releases/download/v0.1.0/install.sh, which installs that version.
releases/latest/download/install.sh is the one of the newest.
What it does not do yet
- The setup program is not signed, and neither is
zenoon macOS. Windows warns once (above). - The winget step has not been run by a test. GitHub's Windows machines have no winget, and already have a compiler and Git, so there the two boxes are not shown. Everything else in the setup program is run before each release.
- Packages for package managers (apt, pacman, snap, flatpak,
Homebrew, winget) came next, and are in
packages.md. - No
.pkgfor macOS. An unsigned one is refused by macOS more firmly than the script is. - The repository is private while this is written, and a private release cannot be downloaded by a script. The line above works from the day the repository is public.
zenodoes not update itself. Running the installer again installs the newest version over the old one.
Things to try
- Read
tools/install.shfrom top to bottom before running it. Which lines change something outside~/.zeno? Is that all of them? - Run
tools/try-install.sh target/release/zeno. Then break something ininstall.sh(take out the checksum comparison) and run it again. Which check catches it? ZENO_HOME=$HOME sh install.shis refused. Find the line. What would have happened without it? What does the same line allow that it perhaps should not?- The PATH line is added to one startup file. Somebody uses zsh on Monday and bash on Tuesday. What happens? What would rustup do (it writes a file of its own and has each startup file read it)? Is that better?
- In
zeno.iss,RemoveFromPathputs a;at each end of the text first. Work through it for a PATH that is exactly the Zeno folder, for one where the folder is first, and for one where it is last. Then find the case it gets wrong: a PATH in which somebody wrote the folder with a\at its end. - Add a box to the setup program that opens
docs\web.mdwhen it finishes. It is one line in[Run]. - A big one: write a Homebrew formula for Zeno. It is a Ruby file
that names the two macOS archives and their checksums. Where does
it have to live for
brew install zenoto find it, and what would the release workflow have to do at each release?
This page is docs/install.md in the language repository.