The Urn Logo

The Urn command line interface

The Urn command line interface, or CLI is used to compile and run Urn programs, as well as providing useful utilities such as native library generation and the REPL.

The CLI can be started by executing bin/urn.lua on the command line, (or lua bin/urn.lua if you do not wish to use Lua 5.3). By default this will start the REPL. In order to get more options about the CLI, you can run it using the --help flag. This will detail the various options that the CLI provides.

General purpose arguments

Urn has a series of general arguments which can be useful in debugging situations.

Specifying files

Obviously one of the things you’ll want to be doing with Urn is loading files, in order to compile and run them. To do this, just specify the files on the command line. However, you may also want to adjust some other settings:

Processing files

Urn will run several processing steps on your files before running/compiling them. Firstly the compiler runs “warning tests:” a couple of functions which check your code for possible bugs. Then it will optimise your code: stripping unused symbols, folding constants, and more. However, these features do take substantial amounts of time on large files - optimising the Urn compiler takes 3 seconds on my machine. Therefore, you may wish to disable certain features.

Both optimisations and warnings are configured with the same system, the former with --optimise (and -O), the latter being configured with --warning and -W. In the following section, replace “optimise” with “warning” where applicable.

I generally use the shorter argument form instead, for instance: -O+inline to enable function inlining.

Optimisation specific arguments

There are also several optimisation specific flags, which control how long the optimiser will run for:

Compiling files

By default, Urn will emit a file named out.lua and exit. However, various command arguments provide a little more flexibility in the output.

Urn also allows emitting files in other formats, such as a fully expanded Lisp, and generating documentation.

Running files

Whilst you can run the generated file using the Lua interpreter, it is often nicer to run it directly from the Urn CLI. Along with being slightly easier, you get additional features such as a built in profiler and error message line-mapping.

There are two profiling modes you can use with the --profile flag:

The stack profiler

Whilst the call profiler is very simple to use, the stack profiler provides several other configuration options.

The coverage profiler

The coverage profiler does not profile how long your code takes to execute, but instead determines how much of your code is executed. It is designed to be run for multiple files and then merged together to generate a report, hence requiring several a separate report generation process.

This is done using the --gen-coverage option. This will read the luacov.stats.out file and merge it with all command line inputs, producing a file. In order for a file to be included in the report, you must specify it on the command line. This allows you to track coverage for files which are not executed, and exclude files which are, say, part of the standard library.