Installation

The first step is to install the Zirco compiler (zrc) and its associated tools and libraries. We call this the “Zirco toolchain”.

The toolchain has host support for the following targets:

Tier 1 targets (tested):

• x86_64-unknown-linux-gnu (Linux on x86_64, prebuilt binaries available)

Tier 2 targets (built, but not tested in CI):

• aarch64-unknown-linux-gnu (Linux on ARM64, prebuilt binaries available)
• x86_64-apple-darwin (macOS on x86_64, prebuilt binaries available, deprecated)
• aarch64-apple-darwin (macOS on Apple Silicon, prebuilt binaries available)

Note

Nix support for all targets (including Tier 1 targets) is considered Tier 2.

Other platforms may be supported via cross-compilation or by building Zirco with a custom LLVM build, but this is not currently documented.

Zirco does not support Windows, but the compiler runs normally on Windows via WSL. This guide also assumes your system has a C toolchain installed (for linking).

Note

Command Line Notation

Throughout the book, we’ll show some commands used in the terminal. Lines that you should enter in a terminal all start with $. You don’t need to type the $ character; it’s the command line prompt shown to indicate the start of each command. Lines that don’t start with $ typically show the output of the previous command.

Selecting an Installation Method

The recommended way to install the Zirco toolchain is via the zircon toolchain installer, which allows you to easily install and manage multiple versions of the Zirco toolchain.

Other installation methods are included below, alongside instructions for their use. If you don’t know what installation method to use, we recommend using zircon.

Install via zircon

Zircon requires libarchive, curl, and openssl to be installed on your system. On Debian-based Linux distros, you can install these dependencies with the following command:

$ sudo apt install libarchive-dev curl openssl

Now, you can run the Zirco bootstrap script to set up zircon in to ~/.zircon.

$ curl -sL https://zirco.dev/zstrap.sh | bash
✓ Zircon installed successfully

Next steps:
1. Add the following line to your shell profile (e.g., ~/.bashrc, ~/.zshrc):
   source <($HOME/.zircon/self/bin/zircon env)
2. Restart your terminal or run 'source ~/.bashrc' (or the appropriate command for your shell) to apply the changes.
3. Run 'zircon install' to install the latest Zirco toolchain.

Add the required environment variables to your shell profile, as zircon will not do it for you.

After that, you can install the latest Zirco toolchain with the following command:

$ zircon install nightly
✓ Successfully imported toolchain: nightly
✓ Set as current toolchain

To use this toolchain, run:
  source <(zircon env)
*** You may need to restart your shell or source your profile for changes to take effect. ***

Now, re-configure your shell environment to use the new toolchain:

$ source <(zircon env)

You’re all done! You can verify that the Zirco compiler is installed and working by running:

$ zrc --version
zrc_cli 0.2.0 (commit ..., release build, ...)

Install via Debian Package

Even on Debian-based systems, we recommend using zircon to install the Zirco toolchain, as it allows you to easily upgrade, switch, and manage multiple versions of the Zirco toolchain. However, if you prefer to install the Zirco toolchain via dpkg, you can download the latest Debian package from the releases page.

$ dpkg -i zrc-0.2.0+1234567_amd64.deb

Install via Nix

Zirco provides a Nix flake that provides the latest Zirco toolchain.

You can add our package to your flake inputs as follows:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    zirco-pkgs.url = "github:zirco-lang/zrc/main";
  };

  outputs = { self, nixpkgs, zirco-pkgs }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in
    {
      devShells.${system}.default = pkgs.mkShell {
        buildInputs = [
          zirco-pkgs.packages.${system}.zrc
          zirco-pkgs.packages.${system}.libzr
        ];
      };
    };
}

Note

System-wide Nix installations often lack required environment variables for the Zirco toolchain. If you encounter issues with missing libraries or include paths, you may need to manually set the -I/-L paths for headers and libzr.

Download Prebuilt Binaries

Release tarballs are available on the releases page.

Ensure that LD_LIBRARY_PATH and ZIRCO_INCLUDE_PATH are set to the appropriate directories for the downloaded toolchain, and add the bin directory to your PATH.

Build from Source

Instructions for building from source are available in the compiler’s README file.

Troubleshooting

If you encounter issues with the installation, we recommend checking the following before reaching out for support.

To check that the Zirco compiler is installed and working, run:

$ zrc --version
zrc_cli 0.2.0 (commit ..., release build, ...)

If you don’t see this information, check that the zrc binary is in your PATH. If you installed with Zircon, you will see an entry for .zircon/toolchains/current/bin. Ensure this symlink points to the correct toolchain directory.

If you encounter issues with missing libraries or include paths, ensure that LD_LIBRARY_PATH and ZIRCO_INCLUDE_PATH are set to the appropriate directories for your toolchain installation.