Get started
Installing Narra
Installing Narra
Install
On macOS and Linux, run this in a terminal:
curl -fsSL https://github.com/lxsmnsyc/narra/releases/latest/download/install.sh | sh
On Windows, run this in PowerShell:
irm https://github.com/lxsmnsyc/narra/releases/latest/download/install.ps1 | iex
The command downloads the archive for your system, checks its SHA-256 sum against the sum published with the release, and installs narrac. It then tells you the next step. The sum catches a damaged or incomplete download. It does not catch a compromised release: the sum is published next to the archive, so whoever can replace one can replace the other. narrac calls a C compiler each time it builds a program, so keep one installed (cc, clang or gcc).
Where it installs
| System | Folder |
|---|---|
| macOS and Linux | ~/.local/bin |
| Windows | %LOCALAPPDATA%\narra\bin, added to your user PATH |
Open a new terminal, then check that your shell finds narrac:
narrac --version
This prints the version, such as 0.1.0. If your shell says narrac is not found on macOS or Linux, ~/.local/bin is not on your PATH yet. Add this line to your shell's startup file, ~/.zshrc for zsh (the macOS default) or ~/.bashrc for bash, then open a new terminal:
export PATH="$HOME/.local/bin:$PATH"
Prebuilt systems
| System | Processor |
|---|---|
| macOS 13 or newer | arm64, x64 |
| Linux (glibc 2.28 or newer) | arm64, x64 |
| Linux (musl, such as Alpine) | arm64, x64 |
| Windows | x64 |
The shell script picks the musl archive on a musl system. The glibc archives need glibc 2.28 or newer, which means Debian 10, Ubuntu 18.04 or RHEL 8 and later. The musl archives are static and run on any Linux. On another system, build from source (below).
On an Apple Silicon Mac, the shell script installs the arm64 build even when the terminal runs under Rosetta.
Options
| Variable | Meaning | Default |
|---|---|---|
NARRA_VERSION |
The version to install, such as 0.1.0. |
The latest release. |
NARRA_INSTALL |
The folder that receives narrac. |
See the table above. |
NARRA_NO_PATH |
Set to 1 to leave your PATH alone. Windows only. |
Not set. |
Set them before sh in the shell command, or in the environment before the PowerShell command. For example, this installs version 0.1.0 into /usr/local/bin:
curl -fsSL https://github.com/lxsmnsyc/narra/releases/latest/download/install.sh | NARRA_VERSION=0.1.0 NARRA_INSTALL=/usr/local/bin sh
GitHub's latest link skips prereleases. While a project has only prereleases, the one-line commands above fail with a 404, because they download the script from releases/latest. In that case, download the script from the release itself, for example https://github.com/lxsmnsyc/narra/releases/download/v0.1.0-rc1/install.sh, or set NARRA_VERSION. A script that runs without NARRA_VERSION installs the latest release, or the newest release of any kind when there is only a prerelease.
NARRA_BASE_URL is a testing override. It names a folder that holds the archive and its .sha256 file instead of the GitHub release, and it must start with https://. Only http://localhost and http://127.0.0.1 are allowed without TLS, and the shell script also takes a file:// folder. The script needs HOME or NARRA_INSTALL to know where to install.
Update and uninstall
Run the same command again to update. To uninstall, delete the narrac file (narrac.exe on Windows). On Windows, also remove the folder from your user PATH in the system settings.
Check that it works
Create a file named hello.nra:
export function run(args: Array<string>): int {
print("hello, narra")
return 0
}
Run it:
narrac run hello.nra
hello, narra
Chapter 1 of the guide explains this program and goes on from there.
Build from source
You can build the compiler yourself instead. The build takes a few minutes.
What you need
- A C compiler that supports C11:
cc,clangorgcc. sh, the standard shell.git, to download the source.
Nothing else is needed. The standard library is built into narrac, so the single narrac file is the whole install. narrac also calls the C compiler each time it builds a program, so keep the C compiler installed.
On macOS, xcode-select --install installs cc and git. On Debian or Ubuntu, sudo apt-get install gcc libc6-dev git installs them.
Build
git clone https://github.com/lxsmnsyc/narra
cd narra
sh selfhost/bootstrap.sh out
The last command prints its progress and ends like this:
stage 0: cc builds the seed
stage 1: the seed compiler emits selfhost, cc builds it
stage 2: the stage 1 compiler emits selfhost
stage 1 binary: 5080728 bytes
ok: stage 1 and stage 2 emit identical C (246458 lines)
seed is current
The sizes in your output can differ. The new compiler is now in out/narrac. If the build fails, the line above the error names the step.
The line that starts with ok: shows that the build is correct. seed is current means the checked-in seed matches the source. The seed and the stages are explained in seed/README.md.
Choose a C compiler
The script uses cc unless you set CC. CC must name one program, with no flags:
CC=clang sh selfhost/bootstrap.sh out
narrac reads CC in the same way when it builds your programs.
Install the build
Copy out/narrac to a folder on your PATH. ~/.local/bin is a common choice:
mkdir -p ~/.local/bin
cp out/narrac ~/.local/bin/
Update a source build
From inside the narra folder, download the new source, build it, and copy the result over the old file:
git pull
sh selfhost/bootstrap.sh out
cp out/narrac ~/.local/bin/