Macros, Defines & Compilation

Overview

The SystemVerilog preprocessor runs before the compiler ever sees your code. `define, `ifdef, and `include perform pure text manipulation — no type checking, no scoping, no awareness of modules or classes. That makes macros powerful for code generation and configuration, and dangerous when misused. Understanding what the preprocessor does — and what the compiler, elaborator, and simulator each do afterward — is what separates engineers who fix build errors in minutes from those who stare at cryptic expansion messages for hours.

Every major verification codebase is macro-heavy: UVM itself is built on `uvm_component_utils and `uvm_info. You will read, debug, and write macros constantly — this topic gives you the mental model for all of it.

Sub-topics

1. `define & Text Macros — object-like and function-like macros, multi-line macros, stringification.

2. `ifdef & Conditional Compilation — compile-time configuration, +define+, guard discipline.

3. `include & Guard Discipline — textual paste semantics, double-include failures, ifndef guards.

4. Debugging Macro Problems — expansion errors, silent ifdef skips, safe log-macro construction.

5. Compilation, Elaboration & Optimization Flow — what each tool stage does and which errors appear where.

TOPIC MAP — PREPROCESSOR TO SIMULATOR

  source.sv ──► PREPROCESSOR ──► expanded text ──► COMPILER ──► ...
                    │
       ┌────────────┼──────────────┐
       │            │              │
       ▼            ▼              ▼
   `define       `ifdef        `include
   text macros  conditional    file paste
   (lesson 1)   compilation    + guards
                (lesson 2)     (lesson 3)
       │            │              │
       └────────────┴──────────────┘
                    │
                    ▼
        Debugging macro problems (lesson 4)
                    │
                    ▼
   compile → elaborate → optimize → simulate (lesson 5)

Key takeaways

• Macros are textual substitution — they run before compilation and know nothing about types or scope.

• Conditional compilation configures code at compile time; plusargs configure at run time — different tools for different jobs.

• Most macro bugs are invisible until expansion — learn to read errors at the expansion site, not the use site.