Design and Implementation of an OCaml-Based Standalone SystemVerilog Preprocessor Compliant with IEEE 1800-2023

Abstract

SystemVerilog preprocessing determines the effective source code consumed by subsequent front-end compilation stages, yet in many toolchains it is implemented as an internal component tightly coupled with lexical, syntactic, or downstream analysis. Such integration is effective for end-to-end compilation flows, but it can obscure preprocessing behavior and make independent validation difficult, especially for macro expansion, conditional compilation, file inclusion, and source-location tracking. This paper presents Stagira svpp, a standalone SystemVerilog preprocessor implemented in OCaml and designed to follow the preprocessing semantics of IEEE Std 1800–2023. Preprocessing is modeled as an independent, directive-driven frontend stage, in which macro definitions, conditional-compilation contexts, file-inclusion hierarchies, source-location mappings, diagnostics, and auxiliary directive states are maintained through explicit state updates. The implementation supports object-like and function-like macros, token-level macro operators, nested conditional compilation, macro-driven file inclusion with cycle detection, predefined macros, source-location remapping, command-line macro/include configuration, and selected stateful directives. The evaluation uses a focused semantic test suite to exercise implemented preprocessing mechanisms and representative boundary cases. Within the evaluated scope, Stagira svpp passes all 48 test cases and exhibits consistent behavior for tested scenarios including nested conditionals, token-level macro operations, macro-expanded include arguments, cyclic inclusion detection, and source location-related diagnostics. A representative comparison with Icarus Verilog and Quartus II further illustrates observable behavioral differences in selected include-related scenarios. The current evaluation focuses on semantic correctness and boundary behavior rather than large-scale performance benchmarking, which has been identified as a direction for future work. By decoupling preprocessing from later frontend phases and making preprocessing state explicit, Stagira svpp provides a reusable reference implementation for studying and validating SystemVerilog preprocessing behavior.