Siemens STL Precompiler Directives: #define, USES, USELIB

Overview

Siemens STL (Statement List) precompiler directives are the mechanism by which a single S7-300/400 or S7-1500 source tree can produce different firmware builds without duplicating the project. Unlike runtime logic, which decides what the CPU executes after the program is loaded, precompiler logic decides what the compiler accepts into the binary image at all. A code path wrapped in #ifdef is either physically present in the compiled FB or it is not — there is no runtime cost and there is no way for an HMI to toggle it.

The original forum question described a block that appeared to be testing for a label called teststand, conditionally defining a constant bTESTSTAND and a secondary label defTESTAND. That single pattern is the canonical use of the STL preprocessor for separating test-stand vs. production firmware, hardware revisions, and optional feature builds. This reference covers the full directive set shipped with Step 7 V5.x and TIA Portal V16 / V17 / V18, the difference between USES and USELIB, the correct way to trace a defined symbol back to its origin (and why the Cross Reference view is the wrong tool), and the diagnostic checks that confirm a directive is doing what you expect.

For the official STL language reference and the S7-1500 programming manual, see the SIMATIC S7-1500 Programming Guideline and the STEP 7 V5.x STL Reference.

Prerequisites

• Siemens SIMATIC Step 7 V5.5 / V5.6 (for S7-300/400) or TIA Portal V16 / V17 / V18 (for S7-1200/1500), with the corresponding option package installed.
• Programming language support: STL on S7-300/400; STL or SCL on S7-1500 — both support the same preprocessor directive set.
• A project that contains at least one STL source file so that the import chain (USES) can be demonstrated.
• For USELIB examples: a master copy or type library in the Library View (TIA Portal) or a *.s7l library (Step 7 V5.x).
• Read/write access to the source files in the project's source folder so that temporary #define injections can be tested.

Precompiler Directive Reference

The STL preprocessor supports a deliberately small set of directives. Anything outside this list is not part of the language and will produce a compile error.

Tracing the teststand Example Step-by-Step

The example block from the original post looked like the following when extracted into a typical project source.

FUNCTION_BLOCK FB_TestStand
VAR
   bTestActive : BOOL;
END_VAR

#ifdef teststand
   CONST bTESTSTAND : BOOL := TRUE;
   #define defTESTAND
#else
   CONST bTESTSTAND : BOOL := FALSE;
#endif

BEGIN
   bTestActive := bTESTSTAND;
END_FUNCTION_BLOCK

The resolution path is the same on Step 7 V5.x and TIA Portal, and follows five steps.

1. Locate any #define teststand in the project. Open the source editor and press Ctrl+F to launch the standard Find dialog. The Search function in the Edit menu is the correct tool, because the Cross Reference view only tracks compiled symbol usage, not preprocessor symbols.
2. If the search returns zero hits in the current source, expand scope. In Step 7 V5.x, right-click the S7 program node and choose Source Files > Show All Sources. In TIA Portal, expand PLC > External source files and the Program blocks > System blocks > Libraries tree. Re-run the search against all of them.
3. If a hit is found in a source that is USES-imported, the define still propagates. The preprocessor builds a global symbol table for the entire compilation pass, not the file. Confirm the import path by searching for USES or USELIB at the top of the dependent source.
4. If the search still returns no hit, the #ifdef teststand branch is dead. The compiler silently excludes the block, bTESTSTAND is set to FALSE, and the label defTESTAND is never defined. Any subsequent #ifdef defTESTAND in the same compilation pass will also evaluate false.
5. To force the test-stand branch on for a single verification build, add a local #define teststand at the very top of the source, before the FUNCTION_BLOCK declaration. Recompile, confirm that bTESTSTAND is TRUE, and then remove the temporary define before downloading to production hardware.

USES vs. USELIB — When to Use Each

Both directives insert content from another file at the point of use, but they differ in build-time behavior, version-control implications, and — critically for the test-stand pattern — define propagation.

The crucial difference for the bTESTSTAND pattern is the Defines visible to importer row. A #define placed inside a file brought in by USES will be visible to the importing source. A #define placed inside a file brought in by USELIB will not. If your project-wide search for #define teststand lands only inside a library, that is a strong hint that the bTESTSTAND branch is actually being toggled by a flag passed in a different way — most often a project-wide compile-time switch set in the library's own configuration block, or a project-level preprocessor variable set in the CPU properties.

How to Search for a Preprocessor Define

There are three places to look, in order of likelihood, and a fourth place engineers often look by mistake.

1. The same source file. The standard Find dialog (Ctrl+F in Step 7 and TIA Portal) scans the open source by default. This is the right tool for preprocessor symbols.
2. A source that the current source imports with USES. Use Find in Project. In Step 7 V5.x: Edit > Find in Project. In TIA Portal: right-click the project tree node and select Find and Replace, or use the global search bar in the project view.
3. A library that the project references. Open the library master in the Library View (TIA Portal: Libraries > Master copies) or the Library folder (Step 7 V5.x: S7 Program > Sources > ... > Library), then run Find inside it. A find inside a compiled *.s7l will not show #define symbols; the source of the library must be opened in a writable form.

Conditional Compilation Patterns

Three patterns show up repeatedly in production S7 code. Each is paired with the exact preprocessor syntax required to make it work.

Pattern 1: Test-Stand / Production Split

// Comment out the next line for production builds
#define teststand

FUNCTION_BLOCK FB_TestStand
VAR
   bTestActive : BOOL;
END_VAR

BEGIN
#ifdef teststand
   // Force test-stand inputs for dry-run validation
   "TS.Mode" := 1;
   "TS.DryRun" := TRUE;
#endif
   bTestActive := bTESTSTAND;
END_FUNCTION_BLOCK

The define is left commented out in the production source. The build engineer uncomments it for the test-stand build only. Combined with the original forum example, the constant bTESTSTAND is then TRUE and downstream blocks (e.g. an HMI startup screen) can branch on it.

Pattern 2: Hardware Variant

// Set per project, not per build
#define HW_REV_B

#ifdef HW_REV_A
   CALL FB_RevA_Init
#else
   CALL FB_RevB_Init
#endif

The define is set per project, lives in a small configuration source imported with USES, and is rarely changed after commissioning.

Pattern 3: Optional Features Behind a Compile Flag

#ifndef DISABLE_SAFETY
   CALL FB_SafetyMonitor
#endif

The absence of the symbol is the switch. This is the most defensible default for safety-related code, because the compiled binary always contains the safety call unless an explicit #define DISABLE_SAFETY is added — the opposite of a typical "opt-in" pattern.

Pattern 4: Multi-Line Macro Substitution

#define LOG_WARN(tag, msg) \
   "Logger".Write(WARN_LEVEL := 1, TAG := tag, MSG := msg)

LOG_WARN("E-Stop", "Button pressed");

Multi-line macros use the C-style backslash continuation. TIA Portal V17+ accepts them in both STL and SCL; Step 7 V5.x accepts them in STL. Use sparingly — the resulting compile errors are difficult to localize.

Preprocessor Error Codes and Diagnostics

Step 7 and TIA Portal surface preprocessor errors as part of the regular compile log, but with specific error classes that engineers can recognize.

Troubleshooting Matrix

Verification Checklist

1. Open the source containing the #ifdef teststand block and confirm the constant bTESTSTAND is declared exactly once.
2. Run Edit > Find in Project for the literal string teststand and note every hit.
3. For each hit, verify whether the defining file is brought in via USES (defines propagate) or USELIB (defines do not propagate).
4. Add a temporary #define teststand at the top of the consumer source, recompile, and confirm bTESTSTAND changes to TRUE in the watch table.
5. Remove the temporary define, recompile, and confirm bTESTSTAND returns to FALSE.
6. Run the generated block through the offline / online compare (Step 7: PLC > Compare Blocks; TIA Portal: Online > Compare) and confirm the compiled STL matches the expected branch.
7. Document the define location in the project README so the next engineer does not have to repeat the search.
8. For production builds, confirm no #define for teststand is present in any source or library imported with USES into the production firmware.

Notes on S7-1500 / TIA Portal Differences

On S7-1500 CPUs the STL language is supported, but TIA Portal's preprocessor is stricter in three ways that engineers moving code from Step 7 V5.x will encounter.

• All #define lines must precede the first executable statement. TIA Portal does not allow a #define to appear after any code line, including declarations, in the same compilation unit.
• Warning on unused defines. TIA Portal warns — but does not error — when a defined symbol is never used. The warning appears in the compile log with a "Preprocessor symbol defined but not used" message and an entry in the information pane.
• Stricter USES resolution. TIA Portal resolves USES paths relative to the project's External source files folder. A source that lives in the same folder but is not added to the project will not be found, even though Step 7 V5.x would have picked it up from the local source directory.

The semantics of USES and USELIB are unchanged, and SCL on S7-1500 supports the same preprocessor directive set, so the bTESTSTAND pattern is portable across STL and SCL with no source changes.

Field-Proven Caveats

Three issues that surface regularly on real commissioning sites.

1. Hidden defines inside generated code. Some Siemens tool add-ons (HMI tag generators, library manager scripts) insert #define lines into source files that the application engineer never sees in the editor. If teststand appears in a project that nobody typed it into, search the generated sources folder before concluding the symbol is unused.
2. Case sensitivity in Step 7 V5.x vs. TIA Portal. Step 7 V5.x is case-insensitive for preprocessor symbols; TIA Portal is case-sensitive. A define of TestStand will not match an #ifdef teststand in TIA Portal even though it did in Step 7 V5.x. Normalize the case at the start of a TIA Portal migration.
3. Watch table names with the same string. Engineers sometimes add a watch table named "teststand" while debugging, then confuse its presence with a defined preprocessor symbol. The Cross Reference view will show the watch table reference, but it is unrelated to the preprocessor state.

FAQ