Getting started with Plasma

Copyright (C) 2019-2022 Plasma Team
Distributed under CC BY-SA 4.0
Updated: September 2022
Source: on github
Table of Contents

Since we don’t have static builds yet, you’ll need to build Plasma from source. This file contains some instructions on setting up the prerequisites and building Plasma.

Plasma has been tested on Linux, Windows subsystem for Linux 1 and 2 on x86_64.

Docker

If you want to run Plasma in a Docker container (rather than the instructions below for Ubuntu Linux) the Dockerfile provided in scripts/docker is available, It is also build and available on docker hub. You can resume this "getting started" guide at the Hello World section below, you will still need to adapt some of the instructions for use with the container.

Dependencies

You will need

  • GCC or Clang

  • GNU Make

  • git

  • Mercury (tested with 22.01)

  • ninja 1.10 or later

Optionally for building documentation:

  • asciidoc

  • source-highlight

Optionally to run the test suite:

  • lua

  • lua-file-system

  • lua-posix

  • tappy (optional, used for nicer output)

  • diffutils

C++ compiler, make and git

Plasma has been tested with clang and gcc. On debian-based systems you can install a suitable compiler and GNU Make with the build-essential package. Install git at the same time.

sudo apt install build-essential git

Mercury

You’ll need another language, Mercury, since our compiler is written in it. A recent stable version is required (22.01.x), ROTD versions may also work. Plasma’s CI currently tests with 22.01. Compiling Mercury from source can take a long time, but if you’re on Debian, Ubuntu or other derivative running on x86_64 then there are some packages! Read on or follow the instructions at https://dl.mercurylang.org/deb/

For Ubuntu 20.04, this is what you need to do:

To install Mercury you’ll need to add a new package repository & GPG key. Download and trust Paul’s GPG key:

cd /tmp
wget https://paul.bone.id.au/paul.asc
sudo cp paul.asc /etc/apt/trusted.gpg.d/paulbone.asc

Create a new file in /etc/apt/sources.list.d, name it mercury.list and paste in it:

deb http://dl.mercurylang.org/deb/ focal main
deb-src http://dl.mercurylang.org/deb/ focal main

You may need to substitue focal for another name, see the Mercury debian packages page.

Now we can install:
sudo apt update
sudo apt install mercury-rotd-recommended

Asciidoc

To optionally build the documentation, you need to install AsciiDoc and source-highlight:

sudo apt install asciidoc source-highlight

Beware, this is a very large installation, on a default Ubuntu installation this amounts to over 1 GB of space and a download of over 300MB. If AsciiDoc is not installed, documentation will not be built.

ninja

Plasma’s build tool plzbuild needs least version 1.10 of the ninja build tool.

Ubuntu 20.04 has a suitable package.

sudo apt install ninja-build

Or install it yourself from a binary download: https://github.com/ninja-build/ninja/releases

Or from source: https://github.com/ninja-build/ninja/

Or run these commands to install ninja 1.10.2 on your x86_64 Linux system:

cd /tmp
wget https://github.com/ninja-build/ninja/releases/download/v1.10.2/ninja-linux.zip
unzip ninja-linux.zip
sudo cp ninja /usr/local/bin/

Lua, tappy and diffutils

To run the test suite you will need

  • lua

  • lua-file-system

  • lua-posix

  • tappy

  • diffutils

Ubuntu 20.04 has a suitable package.

apt install lua5.3 lua-filesystem lua-posix tappy diffutils

Compiling Plasma

Now it’s time to clone the plasma repo:

git clone https://github.com/PlasmaLang/plasma.git

If you want or need to, you can configure Plasma’s build settings by copying template.mk to build.mk and editing it. It contains some documentation for the build options. These include which C compiler to use, and compilation flags. The default build is reasonable if you have gcc. You may need to set the PREFIX variable to your desired installation directory, The Plasma compiler and other tools will be installed to $PREFIX/bin/, you will need to arrange for that to be in your shell interpreter’s path (bug #325 will remove this requirement).

Then run make and it will build you the plasma compiler (src/plzc) and the runtime (runtime/plzrun). Set MAKEFLAGS to build the C++ code in parallel, or set it in your ~/.bashrc.

NPROC=$(nproc)
export MAKEFLAGS="-j$NPROC -l$NPROC"
make

The make test command will execute the test suite. Be sure to take a look at the example programs in examples/.

Installing Plasma

The make install command will now install the Plasma tools into the $PREFIX path you set in build.mk in the previous step. The compiler and other tools are now available under $PREFIX/bin/.

Enjoy!

Hello world

So you’ve got Plasma installed, it’s time to take it for a test-drive.

In a new directory create a BUILD.plz project file, it should contain:

[hello]
type = program
modules = [ Hello ]

Create a hello.p file to contain the Hello module, it should contain:

module Hello

entrypoint
func hello() uses IO -> Int {
    print!("Hello world\n")

    return 0
}

Then use the plzbuild program to build the program:

$ plzbuild

This will create a hello.pz file in the current directory containing the program’s bytecode. Run it with:

$ plzrun hello.pz
Hello world

vim customisation

If you want to write some Plasma programs and you use vim. You may wish to use the vim editor support.

Getting help

If you’re stuck and the Documentation doesn’t contain the answer or clue you need or you’re struggling to find it. Please ask for help. The Contact page of the website lists all the ways you can get in touch. In particular the Plasma Help mailing list and Discord server are the best resources for help.

For bugs or missing information please file a bug.