Conditional Compilation

Conditional compilation removes flag-only branches before BrightScript is emitted. Use it when code must not exist in a particular Roku build—not as a replacement for ordinary runtime conditions.

Define flags

Add Boolean values to hsconfig.json:

{
  "buildFlags": {
    "DEV": true,
    "TELEMETRY": false,
    "EXPERIMENTAL_PLAYER": true
  }
}

The source identifier wraps the key in double underscores:

declare const __DEV__: boolean;
declare const __TELEMETRY__: boolean;
declare const __EXPERIMENTAL_PLAYER__: boolean;

Hosanna UI's global declarations already include its standard flags. Declare an application-specific flag in the application's global type declarations.

Defaulted flags

• An explicit buildFlags.ROKU value becomes __ROKU__.
• Without that explicit value, __ROKU__ reflects whether the compiler source platform is roku.
• An explicit buildFlags.PROD becomes __PROD__.
• Without it, __PROD__ is the opposite of DEV when DEV is defined.
• Other __NAME__ identifiers must have a Boolean value in buildFlags; an unresolved flag cannot safely reach BrightScript.

Keep environment profiles explicit. Do not assume WEB, APPLE, ANDROID, or an application flag is inferred merely because a global declaration exists.

Supported expressions

Flag-only expressions can contain:

• flag identifiers;
• Boolean literals;
• !;
• &&;
• ||; and
• parentheses.

if (__DEV__ && (__ROKU__ || __EXPERIMENTAL_PLAYER__)) {
  installPlaybackDiagnostics();
}

When the expression is true, the compiler emits the block body without the if. When false, it emits nothing for the statement.

No runtime values

Do not mix flags with runtime data:

// Invalid conditional compilation
if (__ROKU__ && session.isSignedIn) {
  startPlayback();
}

Split build-time and runtime decisions:

if (__ROKU__) {
  if (session.isSignedIn) {
    startPlayback();
  }
}

Equality checks, calls, property reads, typeof, ternaries, arithmetic, and other runtime expressions are not part of the flag evaluator.

No else or else if

A flag-only if cannot have an alternate branch:

// Invalid
if (__WEB__) {
  installWebPlayer();
} else {
  installDevicePlayer();
}

Write independent complementary checks:

if (__WEB__) {
  installWebPlayer();
}

if (!__WEB__) {
  installDevicePlayer();
}

This restriction keeps eliminated code and diagnostics deterministic. It also avoids turning one statically evaluated arm into an unexpected runtime chain.

Flag design

• Prefer a small vocabulary based on capabilities or release policy.
• Keep mutually exclusive flags complementary and test every supported combination.
• Do not use DEV as a proxy for a platform.
• Ensure CI compiles both sides of important flags; code removed in every routine build can silently decay.
• Use hs:exclude-from-platform roku for an entire Roku-incompatible file instead of wrapping every declaration in if (!__ROKU__).