Skip to main content
Version: 0.6.0

This article has examples in the following target languages:

Every Lingua Franca program begins with a statement of this form:

target <name> <parameters>

The <name> gives the name of some Lingua Franca target language, which is the language in which reactions are written. This is also the language of the program(s) generated by the Lingua Franca compiler. The target languages currently supported are C, C++, Python, TypeScript, and Rust. There is also a target CCpp that is just like the C target except that it uses a C++ compiler to compile the code, thereby allowing inclusion of C++ code.

Summary of Parameters

A target specification may have optional parameters, the names and values of which depend on which specific target you are using. Each parameter is a key-value pair, where the supported keys are a subset of the following:

  • auth: A boolean specifying to apply authorization between RTI and federates when federated execution.
  • build: A command to execute after code generation instead of the default compile command.
  • build-type: One of Debug (the default), Release, RelWithDebInfo and MinSizeRel.
  • cargo-dependencies: (Rust only) list of dependencies to include in the generated Cargo.toml file.
  • cargo-features: (Rust only) List of string names of features to include.
  • cmake-include: List of paths to cmake files to guide compilation.
  • compiler: A string giving the name of the target language compiler to use.
  • compiler-flags: An arrays of strings giving options to be passed to the target compiler.
  • docker: A boolean to generate a Dockerfile.
  • external-runtime-path: Specify a pre-compiled external runtime library located to link to instead of the default.
  • export-dependency-graph: To export the reaction dependency graph as a dot graph (for debugging).
  • fast: A boolean specifying to execute as fast as possible without waiting for physical time to match logical time.
  • files: An array of paths to files or directories to be copied to the directory that contains the generated sources.
  • logging: An indicator of how much information to print when executing the program.
  • no-compile: If true, then do not invoke a target language compiler. Just generate code.
  • no-runtime-validation: If true, disable runtime validation.
  • protobufs: An array of .proto files that are to be compiled and included in the generated code.
  • runtime-version: Specify which version of the runtime system to use.
  • rust-include: (Rust only) A set of Rust modules in the generated project.
  • scheduler: (C only) Specification of the scheduler to us.
  • single-file-project: (Rust only) If true, enables single-file project layout.
  • single-threaded: Specify to not use multithreading.
  • timeout: A time value (with units) specifying the logical stop time of execution. See Termination.
  • workers: If using multiple threads, how many worker threads to create.

Not all targets support all target parameters. The full set of target parameters supported by the target is:

target C { auth: <true or false> build: <string>, build-type: <Debug, Release, RelWithDebInfo, or MinSizeRel>, cmake-include: <string or list of strings>, compiler: <string>, compiler-flags: <string or list of strings>, docker: <true or false>, fast: <true or false>, files: <string or list of strings>, logging: <error, warning, info, log, debug>, no-compile: <true or false>, protobufs: <string or list of strings>, single-threaded: <true or false>, timeout: <time>, workers: <non-negative integer>, };

For example:

target C { cmake: false, compiler: "cc", flags: "-O3", fast: true, logging: log, timeout: 1 secs, };

This specifies to use compiler cc instead of the default gcc, to use optimization level 3, to execute as fast as possible, and to exit execution when logical time has advanced to 10 seconds. Note that all events at logical time 10 seconds greater than the starting logical time will be executed.

The comma on the last parameter is optional, as is the semicolon on the last line. A target may support overriding the target parameters on the command line when invoking the compiled program.

auth​

The detailed documentation is here.

build​

A command to execute after code generation instead of the default compile command. This is either a single string or an array of strings. The specified command(s) will be executed an environment that has the following environment variables defined:

  • LF_CURRENT_WORKING_DIRECTORY: The directory in which the command is invoked.
  • LF_SOURCE_DIRECTORY: The directory containing the .lf file being compiled.
  • LF_PACKAGE_DIRECTORY: The directory for the root of the project or package (normally the directory above the src directory).
  • LF_SOURCE_GEN_DIRECTORY: The directory in which generated files are placed.
  • LF_BIN_DIRECTORY: The directory into which to put binaries.

The command will be executed in the same directory as the .lf file being compiled. For example, if you specify

target C { build: "./compile.sh Foo" }

then instead of invoking the C compiler after generating code, the code generator will invoke your compile.sh script, which could look something like this:

#!/bin/bash
# Build the generated code.
cd ${LF_SOURCE_GEN_DIRECTORY}
cmake .
make

# Move the executable to the bin directory.
mv $1 ${LF_BIN_DIRECTORY}

# Invoke the executable.
${LF_BIN_DIRECTORY}/$1

# Plot the results, which have appeared in the src-gen directory.
gnuplot ${LF_SOURCE_DIRECTORY}/$1.gnuplot
open $1.pdf

The first few lines of this script do the same thing that is normally done when there is no build option in the target. Specifically, they use cmake to create a makefile, invoke make, and then move the executable to the bin directory. The next line, however, gives new functionality. It executes the compiled code! The final two lines assume that the program has produced a file with data to be plotted and use gnuplot to plot the data. This requires, of course, that you have gnuplot installed, and that there is a file called Foo.gnuplot in the same directory as Foo.lf. The file Foo.gnuplot contains the commands to plot the data, and might look something like the following:

set title 'My Title'
set xrange [0:3]
set yrange [-2:2]
set xlabel "Time (seconds)"
set terminal pdf size 5, 3.5
set output 'Foo.pdf'
plot 'mydata1.data' using 1:2 with lines, \
     'mydata2.data' using 1:2 with lines

This assumes that your program has written two files, mydata1.data and mydata2.data containing two columns, time and value.

build-type​

This target does not currently support the build-type target option.

cargo-dependencies​

This target does not support the cargo-dependencies target option.

cargo-features​

This target does not support the cargo-features target option.

cmake-include​

target C { cmake-include: ["relative/path/to/foo.txt", "relative/path/to/bar.txt", ...] };
target Cpp { cmake-include: ["relative/path/to/foo.txt", "relative/path/to/bar.txt", ...] };

This will optionally append additional custom CMake instructions to the generated CMakeLists.txt, drawing these instructions from the specified text files (e.g, foo.txt). The specified files are resolved using the same file search algorithm as used for the files target parameter. Those files will be copied into the src-gen directory that contains the generated sources. This is done to make the generated code more portable (a feature that is useful in federated execution).

The cmake-include target property can be used, for example, to add dependencies on various packages (e.g., by using the find_package and target_link_libraries commands).

A CMake variable called ${LF_MAIN_TARGET} can be used in the included text file(s) for convenience. This variable will contain the name of the CMake target (i.e., the name of the main reactor). For example, a foo.txt file can contain:

find_package(m REQUIRED) # Finds the m library

target_link_libraries( ${LF_MAIN_TARGET} m ) # Links the m library

foo.txt can then be included by specifying it as an argument to cmake-include.

Note: For a general tutorial on finding packages in CMake, see this external documentation entry. For a list of CMake find modules, see this.

The cmake-include parameter works in conjunction with the import statement. If any imported .lf file has cmake-include among its target properties, the specified text files will be appended to the current list of cmake-includes. These files will be resolved relative to the imported .lf file using the same search procedure as for the files parameter. This helps resolve dependencies in imported reactors automatically and makes the code more modular.

CMakeInclude.lf is an example that uses this feature. A more sophisticated example of the usage of this target parameter can be found in Rhythm.lf. A distributed version can be found in DistributedCMakeInclude.lf is a test that uses this feature.

Note: For federated execution, both cmake-include and files are kept separate for each federate as much as possible. This means that if one federate is imported, or uses an imported reactor that other federates don't use, it will only have access to cmake-includes and files defined in the main .lf file, plus the selectively imported .lf files. DistributedCMakeIncludeSeparateCompile.lf is a test that demonstrates this feature.

See AsyncCallback.lf for an example.

compiler​

This target does not support the compiler target option.

compiler-flags​

This target does not support the compiler-flags parameter.

docker​

This option takes a boolean argument (default is false).

If true, a docker file will be generated in the unfederated case.

In the federated case, a docker file for each federate will be generated. A docker-compose file will also be generated for the top-level federated reactor.

external-runtime-path​

This target does not support the external-runtime-path target option.

export-dependency-graph​

This target does not support the export-dependency-graph target option.

fast​

By default, the execution of a Lingua Franca program is slowed down, if necessary, so that logical time does not elapse faster than physical time. If you wish to execute the program as fast as possible without this constraint, then specify the fast target parameter with value true.

files​

This target does not support the files option.

logging​

This target does not support the logging parameter.

no-compile​

This target does not support the no-compile target option.

no-runtime-validation​

This target does not support the no-runtime-validation target option.

protobufs​

This target does not support the protobufs target option.

runtime-version​

This target does not support the runtime-version target option.

rust-include​

This target does not support the rust-include target option.

scheduler​

This target does not support the scheduler target option.

single-file-project​

This target does not support the single-file-project target option.

single-threaded​

This target does not support the single-threaded target option.

timeout​

A time value (with units) specifying the logical stop time of execution. See Termination.

workers​

This target does not support the workers target option.

Command-Line Arguments​

In the TypeScript target, the generated JavaScript program understands the following command-line arguments, most of which have a short form (one character) and a long form:

  • -f, --fast [true | false]: Specify whether to allow logical time to progress faster than physical time. The default is false. If this is true, then the program will execute as fast as possible, letting logical time advance faster than physical time.
  • -h, --help: Print this usage guide. The program will not execute if this flag is present.
  • -k, --keepalive [true | false]: Specifies whether to stop execution if there are no events to process. This defaults to false, meaning that the program will stop executing when there are no more events on the event queue. If you set this to true, then the program will keep executing until either the timeout logical time is reached or the program is externally killed. If you have physical actions, it usually makes sense to set this to true.
  • -l, --logging [ERROR | WARN | INFO | LOG | DEBUG]: The level of logging messages from the reactor-ts runtime to to print to the console. Messages tagged with a given type (error, warn, etc.) will print if this argument is greater than or equal to the level of the message (ERROR < WARN < INFO < LOG < DEBUG).
  • -o, --timeout <duration> <units>: Stop execution when logical time has advanced by the specified duration. The units can be any of nsec, usec, msec, sec, minute, hour, day, week, or the plurals of those. For the duration and units of a timeout argument to be parsed correctly as a single value, these should be specified in quotes with no leading or trailing space (e.g. '5 sec').
  • --single-threaded: Specify to execute in a single thread.
  • -w, --workers <n>: Execute using <n> worker threads if possible. This option is incompatible with the single-threaded option. If provided, a command line argument will override whatever value the corresponding target property had specified in the source .lf file.

Command line options are parsed by the command-line-arguments module with these rules. For example

node <LF_file_name>/dist/<LF_file_name>.js -f false --keepalive=true -o '4 sec' -l INFO

is a valid setting.

Any errors in command-line arguments result in printing the above information. The program will not execute if there is a parsing error for command-line arguments.

Custom Command-Line Arguments​

User-defined command-line arguments may be created by giving the main reactor parameters. Assigning the main reactor a parameter of type string, number, boolean, or time will add an argument with corresponding name and type to the generated program's command-line-interface. Custom arguments will also appear in the generated program's usage guide (from the --help option). If the generated program is executed with a value specified for a custom command-line argument, that value will override the default value for the corresponding parameter. Arguments typed string, number, and boolean are parsed in the expected way, but time arguments must be specified on the command line like the --timeout property as '<duration> <units>' (in quotes).

Note: Custom arguments may not have the same names as standard arguments like timeout or keepalive.

For example this reactor has a custom command line argument named customArg of type number and default value 2:

target TypeScript; main reactor clArg(customArg:number(2)) { reaction (startup) {= console.log(customArg); =} }

If this reactor is compiled from the file simpleCLArgs.lf, executing

node simpleCLArgs/dist/simpleCLArgs.js

outputs the default value 2. But running

node simpleCLArgs/dist/simpleCLArgs.js --customArg=42

outputs 42. Additionally, we can view documentation for the custom command line argument with the --help command.

node simpleCLArgs/dist/simpleCLArgs.js -h

The program will generate the standard usage guide, but also

--customArg '<duration> <units>'                    Custom argument. Refer to
                                                      <path>/simpleCLArgs.lf
                                                      for documentation.

Additional types for Custom Command-Line Arguments​

Main reactor parameters that are not typed string, number, boolean, or time will not create custom command-line arguments. However, that doesn't mean it is impossible to obtain other types from the command line, just use a string and specify how the parsing is done yourself. See below for an example of a reactor that parses a custom command-line argument of type string into a state variable of type Array<number> using JSON.parse and a user-defined type guard.

target TypeScript; main reactor customType(arrayArg:string("")) { preamble {= function isArrayOfNumbers(x: any): x is Array<number> { for (let item of x) { if (typeof item !== "number") { return false; } } return true; } =} state foo:{=Array<number>=}({=[]=}); reaction (startup) {= let parsedArgument = JSON.parse(customType); if (isArrayOfNumbers(parsedArgument)) { foo = parsedArgument; } else { throw new Error("Custom command line argument is not an array of numbers."); } console.log(foo); =} }