Preprocessor Symbols

Preprocessor Symbols

Because Sucrose reuses code through Shared Item Projects — where the same source file is physically compiled into many different executables — it relies on preprocessor symbols to make one shared file behave differently per app, per engine, and per platform. Every executable defines a unique symbol in its .csproj, and shared source wraps host-specific code in #if SYMBOL blocks. This page catalogs all three symbol families and explains how they vary shared code.

Contents

• How symbols are defined
• Application symbols
• Engine symbols
• Platform symbols
• How shared code uses them
• See also

How symbols are defined

Each executable defines its symbol via <DefineConstants> in its .csproj:

<!-- Sucrose.Launcher.csproj -->
<DefineConstants>$(DefineConstants);LAUNCHER</DefineConstants>

<!-- Sucrose.Live.MpvPlayer.csproj -->
<DefineConstants>$(DefineConstants);ENGINE;LIVE_MPVPLAYER</DefineConstants>

Platform symbols are not set per project — they are set centrally in Directory.Build.targets based on the active PlatformTarget. The combination of an app/engine symbol and a platform symbol uniquely identifies the compilation host of any shared file.

Application symbols

Each non-engine executable defines exactly one application symbol:

Symbol	Process
LAUNCHER	Sucrose.Launcher
PORTAL	Sucrose.Portal
BACKGROUNDOG	Sucrose.Backgroundog
COMMANDOG	Sucrose.Commandog
WATCHDOG	Sucrose.Watchdog
REPORTDOG	Sucrose.Reportdog
PROPERTY	Sucrose.Property
UNDO	Sucrose.Undo
UPDATE	Sucrose.Update

(The roles of each of these processes are covered in Architecture Overview.)

Engine symbols

Every live engine defines the shared ENGINE symbol plus exactly one LIVE_* symbol identifying which engine it is:

Symbol(s)	Engine
ENGINE	Defined by all engines
ENGINE + LIVE_WEBVIEW	Sucrose.Live.WebView
ENGINE + LIVE_CEFSHARP	Sucrose.Live.CefSharp
ENGINE + LIVE_MPVPLAYER	Sucrose.Live.MpvPlayer
ENGINE + LIVE_AURORA	Sucrose.Live.Aurora
ENGINE + LIVE_NEBULA	Sucrose.Live.Nebula
ENGINE + LIVE_VEXANA	Sucrose.Live.Vexana
ENGINE + LIVE_XAVIER	Sucrose.Live.Xavier

The ENGINE symbol lets shared code distinguish "any engine" from the non-engine apps, while the LIVE_* symbol selects engine-specific behavior. (Each engine's technology and supported types are documented under Engines Overview.)

Platform symbols

Set in Directory.Build.targets according to the build's PlatformTarget:

Symbol	Platform	RuntimeIdentifier
X86	x86	win-x86
X64	x64	win-x64
ARM64	ARM64	win-arm64

These are used wherever code must branch on architecture — for example, selecting the correct native binary (libmpv-{arch}.dll) or resolving an installer's {Architecture} placeholder.

How shared code uses them

Because a shared .cs file is inlined into many hosts, the same file may need different usings, different startup wiring, or different feature toggles depending on who is compiling it. The pattern is a plain C# conditional-compilation block:

#if PORTAL
    // Code only compiled into Sucrose.Portal
#endif

#if ENGINE && LIVE_MPVPLAYER
    // Code only compiled into the MpvPlayer engine
#endif

#if X64
    // x64-only path (e.g. native binary selection)
#endif

This is why the Shared Item Project model is used instead of a single shared DLL: a DLL would compile once with one set of symbols, whereas inlining lets each consumer compile the shared source with its own symbols. When you edit shared code, always consider which hosts will compile each branch.

See also

• Shared Item Projects
• Repository Layout
• Code Conventions
• Building From Source
• Architecture Overview
• Engines Overview
• Extending Sucrose