Using the `lumi` Command¶

The lumi command is a tool that helps compile, test, and run Lumi code. For example, lumi command can be used to build an executable directly from Lumi code by simply running lumi hello.5.lm.

The lumi command:

assumes the used Lumi compilers are already built and are in the system path
uses the CC environment variable to determine the C compiler command, using gcc if not exists
supports all Lumi version from TL0 to TL5

Command Help¶

Running lumi -h or lumi --help will print help:

>>> lumi -h
Usage: lumi [options] file...
Options:
  -h/--help        print this help
  --version        print lumi command version
  -o <file>        output file name
  -t <module>      compile test program for <module>
  -l <module>      compile shared library exporting <module>
  -c               only create C file(s)
  -TL<version>     only run C compiler for TL<version>
  -e <argument>    extra argument for C compilation
  -p <lumipath>    path of lumi-lang repository
  -r               run the compiled program
  -ra <arguments>  run the compiled program with given arguments
  -v/--verbose     print executed commands
  -d/--debug       only print commands without execution

Usage¶

The basic usage of lumi command is to take one or more Lumi files and create a single executable from them. For example:

lumi hello.5.lm

will create a hello named executable compiled from hello.5.lm, generating a hello.c C file in the process. This is done by running Lumi compiler and C compiler one after another.

If multiple Lumi files are given, the generated name will be based on the first input file.

lumi command detects the TL version based on the input file extension .[TL version].lm and runs the respective Lumi compiler.

Specifying an Explicit Output File Name¶

The output file name can be explicitly defined with -o <output file name>. For example:

lumi hello.5.lm -o output

will generate output named executable, and output.c named C file in the process.

Compiling Tests¶

Lumi compiler allows generating testing code for a specific Lumi module. This feature can be used in lumi command with -t <tested module name>. For example:

lumi -t hello hello-tests.5.lm hello.5.lm

will generate hello-tests executable that tests the hello module.

Running a Lumi test executable with -xml argument will also generate a cobertura.xml named file with code coverage XML report in cobertura scheme.

Compiling a Shared Library¶

Lumi compiler allows generating code for a shared library exporting C styled functions from a specific Lumi module. This feature can be used in lumi command with -l <exported module name>, and only functions from the given module will be exported to the shared library. For example:

lumi -l hello hello.5.lm

will generate libhello.so shared library that exports functions from the hello module.

Only Running Lumi Compiler¶

To only run the Lumi compiler -c flag can be used. For example:

lumi -c hello.5.lm

will only generate hello.c C file.

Only Running C Compiler¶

To only run the C compiler -TL<TL version> flag can be used. The TL version number must be given as it cannot be detected from the input C file name. For example:

lumi -TL5 hello.c

will only generate hello executable, assuming hello.c was generated by TL5.

Extra C arguments¶

To add extra arguments to the C compilation -e can be used. For example:

lumi hello.5.lm -e external.c

will add external.c as an input to the C compiler, while ignoring it in the Lumi compilation. This is mainly needed when external C code is called from Lumi.

Running the Generated Executable¶

The generated executable can also be run using -r. For example:

lumi -r hello.5.lm

will generate hello executable and then run it.

It is possible to also send arguments to the executable using -ra <arguments>. For example:

lumi -r hello.5.lm -ra 'first-arg "second arg"'

Will run hello first-arg "second arg".

Verbose and Debug¶

Adding -v or --verbose option will also print the executed commands.

Adding -d or --debug option will only print the commands without execution.

Old Version Limitations¶

TL4 and below assumes LUMIPATH is correctly configured
multiple input Lumi files are not supported in TL0 and TL1
implicit output name is determined by the last file in TL2, and not the first
TL2 and TL3 generate multiple C files - one C file for each input Lumi file, this also meas that an explicit output name for C files is not supported
testing is only supported in TL4 and above

LUMIPATH¶

For C linking purposes in TL4 and below lumi command needs to know the local Lumi repository root directory path. This can be configured by one of:

running lumi command inside the Lumi repository root directory
setting the value of LUMIPATH environment variable to the path
running lumi with flag -p <path> (this will override LUMIPATH environment variable)

Path Separator¶

The default path separator in lumi command is /. In systems where the path separator is \ instead (such as Windows), the LUMIPATH must end with a \ character. Doing this will set the path separator in lumi command to \.

Using the lumi Command¶