Skip to content
Emerald

Install Emerald

Emerald installs with one command. You paste it into a terminal, and it downloads Emerald, checks that the download is complete, and sets your computer up to find it. It does not need administrator rights, so it works on most school computers too.

  1. Open PowerShell: press the Windows key, type PowerShell, and press Enter.

  2. Paste this command and press Enter:

    Terminal window
    irm https://raw.githubusercontent.com/amortimer20/emerald-lang/main/install.ps1 | iex

  3. When it says Emerald is ready, check that it works:

    Terminal window
    emerald --version

    It prints the version you installed, such as Emerald 0.6.0.

Emerald works straight away in the window you installed it from. Other windows that were already open, and editors such as VS Code, find it once you close and reopen them.

Your first program

Section titled “Your first program”

Make a file named hello.em containing one line:

print("Hello, world!")

Then run it from the terminal, in the folder where you saved it:

Terminal window
emerald run hello.em

It prints Hello, world!. The First Program carries on from here.

Updating

Section titled “Updating”

Run the install command again. It replaces Emerald with the latest release and changes nothing else.

Installing a particular version

Section titled “Installing a particular version”

A class may ask everyone to use the same version. Name it after -Version or --version:

Terminal window
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/amortimer20/emerald-lang/main/install.ps1))) -Version v0.6.0

Every version is listed on the releases page.

Uninstalling

Section titled “Uninstalling”
Terminal window
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/amortimer20/emerald-lang/main/install.ps1))) -Uninstall

This removes Emerald and the setting that let your terminal find it. Your programs are not touched.

What the installer does

Section titled “What the installer does”

It is good practice to know what a command from the internet will do before you run it. You can read both scripts in Emerald’s repository: install.ps1 for Windows and install.sh for macOS and Linux. Each one:

  • downloads Emerald from its releases page on GitHub;
  • checks the download against the release’s list of checksums, so a damaged or altered download is refused;
  • puts Emerald in a folder of your own: %LOCALAPPDATA%\Programs\Emerald on Windows, and ~/.emerald/bin on macOS and Linux;
  • adds that folder to your PATH, the list of folders your terminal looks in for commands. On Windows that is your user PATH; on macOS and Linux it is one line added to your shell’s startup file, such as ~/.zshrc.

If something goes wrong

Section titled “If something goes wrong”

The terminal says emerald is not recognized, or command not found. A terminal reads PATH when it opens, so one that was open before the install has not seen the change. Close it and open a new one. In VS Code, close and reopen the whole editor, not just its terminal.

PowerShell says running scripts is disabled. Some school computers block PowerShell scripts. Ask whoever looks after the computers, or install Emerald on a computer of your own.

The Mac installer says this Mac has an Intel processor. Emerald’s Mac release is for Apple silicon only, for now.

The download fails. Check your internet connection and run the command again. If you named a version, check that it is spelled as it is on the releases page, with its v.

Other ways to install

Section titled “Other ways to install”

If you already use Mise to manage your tools, it can install Emerald:

Terminal window
mise use -g "github:amortimer20/emerald-lang@latest"

You can also build Emerald from source, which needs the Zig compiler.