Compiling SNL Programs¶

The SNL to C Compiler¶

The SNL to C compiler snc compiles the state notation language into C code. The resulting file can then be compiled with a C compiler.

Compiler Options¶

SNC options start by a plus or minus sign, followed by a single character. A plus sign turns the option on, and a minus turns the option off, unless the option takes an argument (currently only -o).

Option	Description
+a¶	Asynchronous `pvGet`: the program continues without waiting for completion of the `pvGet` operation.
-a¶	Synchronous `pvGet`: the program waits for completion. This is the default if an option is not specified.
+c¶	Wait for process variables to connect before allowing the program to begin execution. This is the default.
-c¶	Allow the program to begin execution before connections are established to all channel.
+d¶	Turn on run-time debug messages.
-d¶	Turn off run-time debug messages. This is the default.
+e¶	Use the new event flag mode. This is the default.
-e¶	Use the old event flag mode (clear flags after executing a when statement).
+i¶	Generate registrar procedure that registers shell commands and programs with an IOC shell. This is the default.
-i¶	Do not generate registrar procedure.
+l¶	Add line markers to the generated code, so that C compiler messages refer to the SNL source file. This is the default.
-l¶	Do not produce line markers.
+m¶	Include main procedure (seqMain.c) for a stand-alone program.
-m¶	Do not include seqMain.c. This is the default.
+r¶	Make the generated code reentrant, thus allowing more than one instance of the program to run on an IOC.
-r¶	Generated code is not reentrant. This is the default.
+s¶	Safe Mode: variables are local to state set and must be communicated explicitly. Implies +r.
-s¶	Traditional (non-safe) mode. This is the default for compatibility.
+w¶	Display warning messages. This is the default.
-w¶	Suppress warnings.
-o¶	To change the name of the generated C file. Requires an argument.

New in version 2.2.

Option	Description
+W¶	Display extra warnings for undefined objects.
-W¶	Suppress extra warnings. This is the default.

Note that +a and -a are ignored for calls to pvGet that explicitly specify SYNC or ASYNC in the 2nd argument.

Options may also be set from within the program (somewhere between the program name/parameter and the state set definitions), see Option in the SNL Reference for Version 2.2.

Prior to Version 1.8 of the sequencer, event flags were cleared after a when statement executed. Currently, event flags must be cleared explicitly with either efTestAndClear or efClear. The -e compiler option can be used to restore the old behaviour.

Output File¶

The output file name is that of the input file with the extension replaced with .c. The -o option can be used to override the output file name.

Actually the rules are a little more complex than stated above: .st and single-character extensions are replaced with .c; otherwise .c is appended to the full file name. In all cases, the -o compiler option overrides.

Errors¶

If snc detects an error, it displays a message describing the error and the location in the source file and aborts further compilation. Note, however, that snc does not contain a type checker: all it knows (and cares) about C is the syntax. This means that many errors will only be found only during the C compilation phase. The C compiler will attributed these to the corresponding location in the SNL source file, since by default snc generates line markers in the output that point back to the original source. This can be turned off with the -l (“ell”) compiler switch.

Warnings¶

In certain cases snc cannot ultimately decide whether the code is erroneous. In such cases it will issue a warning message and continue.

The most prominent example is the use of a variable or CPP macro that has not been declared in the SNL code, but could well be defined when compiling the generated C code (for example if the declaration has been in embedded C code, which snc does not interpret at all). Warnings can be suppressed with the -w compiler option.

Note that since version 2.1 you can avoid these warnings by declaring such variables in SNL, see the Foreign Declarations declaration.

C Pre-processor¶

Depending on the application, it might be useful to pre-process the SNL source with a C pre-processor (cpp). Using the C pre-processor allows you to include other SNL files, define macros, and perform conditional compilation. snc supports this by interpreting cpp-generated line markers, so that error and warning messages refer to the line numbers in the un-pre-processed SNL source.

The build rules that the sequencer adds to the EPICS build system are such that files with the extension .st are preprocessed, while those with the extension .stt are not.

Complete Build¶

By default, the C code generated by snc from an SNL program is not a complete program, but merely a collection of procedures, data types, and variables. The generated procedures are supposed to be called by the sequencer library, which must be linked to the program. Furthermore, the generated code includes a number of header files, both from the sequencer and from EPICS base. Thus the compiler needs to have the EPICS base and sequencer include directories in its include path, and when linking it needs to link with sequencer and some EPICS base libraries.

The simplest and most reliable way to build programs is by using the EPICS build system. All you need to do is:

Declare your .st or .stt files as sources for your program or IOC, by adding them to the <prod or lib>_SRCS variable, where <prod or lib> is either PROD or LIB or the concrete name of your product or library.

Declare that you need to link against the seq and pv libraries by adding both to the <prod or lib>_LIBS variable.

If none of this makes any sense to you then you probably need to study Chapter 4 “Build Facility” of the EPICS Application Developer’s Guide.

Building a Stand-alone Program¶

The +m compiler option can be used to create a stand-alone program, otherwise an IOC is needed to start sequencer programs. Since version 2.1 the main procedure is no longer hard-coded. Instead, the code generator adds a define and an include statement

#define PROG_NAME name_of_your_snl_program
#include "seqMain.c"

at the end of the generated C file, where name_of_your_snl_program is the name (identifier) whose address is to be passed to the seq function. This means you can provide your own version of main simply by placing a file named seqMain.c in your source directory (the EPICS build system usually takes care that the source directory is at the front of the C compiler’s include path).

A simple default seqMain.c is provided and installed into the sequencer’s include directory. Note that since version 2.1 the default main starts an IOC shell (iocsh); this can be disabled by providing a -S (capital ‘s’) argument. The old -s switch is accepted for backward compatibility but does nothing.

Using makeBaseApp¶

An easy to set up an EPICS application that uses the sequencer is to use makeBaseApp.pl, a perl script that comes with your EPICS base. Assuming you have it in your PATH, create an empty directory, go there, and issue the command:

ben@sarun[1]: .../tmp/test > makeBaseApp.pl -t example
Name the application(s) to be created.
Names given will have "App" appended to them.
Application names? test
ben@sarun[1]: .../tmp/test > ls -l
total 12
-rw-rw-r-- 1 ben ben  467 May 14 22:25 Makefile
drwxrwxr-x 2 ben ben 4096 May 14 22:25 configure
drwxrwxr-x 4 ben ben 4096 May 14 22:25 testApp

In testApp/src/ you will find example .st and .stt files and a Makefile that shows how to define the make variables so that everything is compiled and linked correctly.

All that’s left to do is add:

SNCSEQ=/path/to/your/seq/installation

to configure/RELEASE (that is, the one in the configure directory that makeBaseApp.pl just created).