Narra

Chapter 1

Getting started

1. Getting started

In this chapter you install the compiler, run a first program and fix your first compile error. Then you turn the program into a project with two files.

Install the compiler

Narra programs compile to C, and a C compiler turns that C into an executable. Keep a C compiler (cc, clang or gcc) installed. On macOS and Linux, run this in a terminal:

sh
curl -fsSL https://github.com/lxsmnsyc/narra/releases/latest/download/install.sh | sh

On Windows, and for other systems and building from source, see the installation guide. Open a new terminal, then check that your shell finds the compiler, narrac:

sh
narrac --version

Say hello

Create a file named hello.nra and run it with narrac run hello.nra. Each program in this guide is followed by what it prints:

narra
export function run(args: Array<string>): int {
  print("hello, narra")
  return 0
}
hello, narra

narrac run compiled the file, built an executable, and started it. The executable called the function named run, so every program has one. Here is what each part of it does:

  • export makes run visible outside the file, which is how the compiler finds it.
  • args: Array<string> is the command-line arguments, as a list of strings. The first one is the path of the program.
  • : int after the parentheses is the type of value the function returns. run returns the exit code, and 0 means success.
  • print writes a line of text to standard output.

A statement ends at the end of its line, so you write no ; after it.

Next, make the program print the result of a sum. The obvious version does not compile:

narra
export function run(args: Array<string>): int {
  print(1 + 2)
Error: expected string, found int  return 0
}

The first line is a comment. // starts a note for the reader that runs to the end of the line, and the compiler skips it. In this guide, such a comment on the first line of a sample shows the message the compiler prints for that file. 3:11 is the line and column of the problem, with the comment counted as line 1: print wants a string, and 1 + 2 is an int. Narra never turns a number into text for you, so you convert it yourself with Int.toString:

narra
import * as Int from "std/int"

export function run(args: Array<string>): int {
  // Int.toString turns a number into text.
  print(Int.toString(1 + 2))
  return 0
}
3

Int.toString lives in the standard module std/int. The import line makes the functions of that module available under the name Int. Only print, assert, panic and copy are there without an import. Everything else, including the functions for strings, arrays and maps, comes from a module you import.

When you are only looking for mistakes, narrac check hello.nra reports the errors without building anything.

Build an executable

narrac run builds into a temporary place. To keep the executable, use narrac build:

sh
narrac build -o hello hello.nra
./hello

This is a debug build. Running it with NARRA_CHECK_LEAKS=1 set reports memory that was never freed. Add -release for an optimized build. In both builds, reading past the end of an array stops the program with a message.

Split the program into files

Once a program grows, you want it in several files. A project of several files is a package: a folder with a narra.toml file and a src folder for the code.

shop/
  narra.toml
  src/
    main.nra
    prices.nra

narra.toml names the package and says which function starts the program:

toml
[package]
name = "shop"

[[binary]]
name = "shop"
entry = "main.run"

entry = "main.run" means the function run in src/main.nra. Each file in src is a module, named after the package and the file: src/prices.nra is the module "shop/prices". Put a function in it and export it:

narra
export function withTax(cents: int): int {
  return cents + cents / 10
}

Then src/main.nra imports that function by name:

narra
import * as Int from "std/int"
import { withTax } from "shop/prices"

export function run(args: Array<string>): int {
  print(Int.toString(withTax(200)))
  return 0
}
220

From inside the shop folder, narrac run . builds and runs the package and prints 220. narrac build . writes the executable shop, named after the [[binary]]. Chapter 8 covers modules and imports in full.

The commands

Command What it does
narrac run file.nra build and run a program
narrac build -o app file.nra build a debug executable
narrac build -release -o app file.nra build an optimized executable
narrac check file.nra report errors without building
narrac test file.nra run the tests in the file (chapter 10)

For a package, run each command from inside the package folder and write . in place of the file: narrac run ., narrac build -o app ., narrac check ., narrac test .. Without -o, narrac build . names the executable after the [[binary]]. Chapter 18 covers the other commands: formatting, explaining and fixing errors, questions about a package, and editor support.

Next: 2. Values and types.