Skip to content

Environment schema#

Environment#

BaseCompilationConfig #

Bases: BaseModel

Parameters:

Name Type Description Default
commands List[str] | None

Commands to compile the program.

[]
sandbox EnvironmentSandbox | None

Sandbox configuration to use when compiling for this language.

None
passthrough bool | None

Whether to pass through the compilable as an executable file.

None
Source code in rbx/box/environment.py
class BaseCompilationConfig(BaseModel):
    model_config = ConfigDict(extra='forbid')

    commands: Optional[List[str]] = Field(
        default=[],
        description="""Commands to compile the program.""",
    )

    sandbox: Optional[EnvironmentSandbox] = Field(
        default=None,
        description="""Sandbox configuration to use when compiling for this language.""",
    )

    passthrough: Optional[bool] = Field(
        default=None,
        description="""Whether to pass through the compilable as an executable file.""",
    )

BaseExecutionConfig #

Bases: BaseModel

Parameters:

Name Type Description Default
command str | None

Command to run the program.

None
sandbox EnvironmentSandbox | None

Sandbox configuration to use when executing for this language.

None
problemLimits Limits

Original limits of the problem.

<dynamic>
Source code in rbx/box/environment.py
class BaseExecutionConfig(BaseModel):
    model_config = ConfigDict(extra='forbid')

    command: Optional[str] = Field(
        default=None,
        description="""Command to run the program.""",
    )

    sandbox: Optional[EnvironmentSandbox] = Field(
        default=None,
        description="""Sandbox configuration to use when executing for this language.""",
    )

    problemLimits: Limits = Field(
        default_factory=Limits,
        description="""Original limits of the problem.""",
    )

CompilationConfig #

Bases: BaseCompilationConfig

Parameters:

Name Type Description Default
solutionOverrides SolutionCompilationOverrides

Overrides to apply when compiling solutions for this language.

<dynamic>
Source code in rbx/box/environment.py
class CompilationConfig(BaseCompilationConfig):
    solutionOverrides: SolutionCompilationOverrides = Field(
        default_factory=SolutionCompilationOverrides,
        description="""Overrides to apply when compiling solutions for this language.""",
    )

Environment #

Bases: BaseModel

Parameters:

Name Type Description Default
defaultFileMapping FileMapping | None

Default mapping for files within the sandbox. Fields in the mapping can be individually overridden in the language configuration.

None
defaultCompilation CompilationConfig | None

Default compilation configuration to use when compiling programs. Fields in the compilation config can be individually overridden in the language configuration.

None
defaultExecution ExecutionConfig | None

Default execution configuration to use when running programs. Fields in the execution config can be individually overridden in the language configuration.

None
languages List[EnvironmentLanguage]

Configuration for each language supported in this environment.

[]
sandbox str

Identifier of the sandbox used by this environment (e.g. "stupid")

'stupid'
timing TimingConfig

Timing configuration for the environment.

<dynamic>
extensions Extensions | None

Extensions to be added to the environment.

None
buildDir Path

Directory to store the build files.

PosixPath('build')
issues EnvironmentIssuesConfig

How large or slow things may get before rbx issues reports them.

<dynamic>
Source code in rbx/box/environment.py
class Environment(BaseModel):
    model_config = ConfigDict(extra='forbid')

    # `!include` fragments are resolved when loading this model (see
    # rbx.box.yaml_include). Only the four user-authored config kinds people
    # actually share between packages are include-capable; everything else --
    # limits profiles, locks, registries, generated artifacts -- loads plainly
    # and is written back from the model, which would inline any fragment.
    rbx_include_capable: ClassVar[bool] = True

    defaultFileMapping: Optional[FileMapping] = Field(
        default=None,
        description="""Default mapping for files within the sandbox. Fields in the mapping can be
individually overridden in the language configuration.""",
    )

    defaultCompilation: Optional[CompilationConfig] = Field(
        default=None,
        description="""Default compilation configuration to use when compiling programs. Fields in
the compilation config can be individually overridden in the language configuration.""",
    )

    defaultExecution: Optional[ExecutionConfig] = Field(
        default=None,
        description="""Default execution configuration to use when running programs. Fields in the
execution config can be individually overridden in the language configuration.""",
    )

    languages: List[EnvironmentLanguage] = Field(
        default=[],
        description="""Configuration for each language supported in this environment.""",
    )

    sandbox: str = Field(
        default='stupid',
        description="""Identifier of the sandbox used by this environment (e.g. "stupid")""",
    )

    timing: TimingConfig = Field(
        default_factory=TimingConfig,
        description="""Timing configuration for the environment.""",
    )

    extensions: Optional[Extensions] = Field(
        default=None,
        description="""Extensions to be added to the environment.""",
    )

    buildDir: pathlib.Path = Field(
        default=pathlib.Path('build'),
        description="""Directory to store the build files.""",
    )

    issues: EnvironmentIssuesConfig = Field(
        default_factory=EnvironmentIssuesConfig,
        description="""How large or slow things may get before `rbx issues` reports them.""",
    )

EnvironmentLanguage #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

Identifier of this language within this environment.

required
readableName str | None

Readable name for this language.

None
extension str

File extension supported by this language. If there's only one language that supports a certain file extension in the environment, the tool will automatically identify the language based on such extension.

required
extraExtensions List[str]

Extra file extensions supported by this language. If not specified, the tool will automatically identify the language based on such extensions.

<dynamic>
compilation CompilationConfig | None

Compilation config to use when compiling programs for this language.

None
execution ExecutionConfig

Execution config to use when running programs for this language.

required
fileMapping FileMapping | None

Mapping for files within the sandbox. If not specified, the default mapping for the environment will be used.

None
extensions LanguageExtensions | None

Extensions to apply for this language.

None
linters List[LinterConfig]

Linters to run for this language during compilation.

<dynamic>
scanners List[str]

Dependency scanners (by registry name) to apply for this language, in addition to the ones automatically selected by language kind.

<dynamic>
timing LanguageTimingConfig | None

Per-language overrides for timing configuration (e.g. wall time).

None
Source code in rbx/box/environment.py
class EnvironmentLanguage(BaseModel):
    model_config = ConfigDict(extra='forbid')

    name: str = Field(
        description="""Identifier of this language within this environment."""
    )

    readableName: Optional[str] = Field(
        default=None,
        description="""Readable name for this language.""",
    )

    extension: str = Field(
        description="""File extension supported by this language. If there's only one language
that supports a certain file extension in the environment, the tool
will automatically identify the language based on such extension."""
    )

    extraExtensions: List[str] = Field(
        default_factory=list,
        description="""Extra file extensions supported by this language. If not specified, the tool
will automatically identify the language based on such extensions.""",
    )

    compilation: Optional[CompilationConfig] = Field(
        default=None,
        description="""Compilation config to use when compiling programs for this language.""",
    )

    execution: ExecutionConfig = Field(
        description="""Execution config to use when running programs for this language."""
    )

    fileMapping: Optional[FileMapping] = Field(
        default=None,
        description="""Mapping for files within the sandbox. If not specified, the default mapping
for the environment will be used.""",
    )

    extensions: Optional[LanguageExtensions] = Field(
        default=None,
        description="""Extensions to apply for this language.""",
    )

    linters: List[LinterConfig] = Field(
        default_factory=list,
        description="""Linters to run for this language during compilation.""",
    )

    scanners: List[str] = Field(
        default_factory=list,
        description="""Dependency scanners (by registry name) to apply for this
language, in addition to the ones automatically selected by language kind.""",
    )

    timing: Optional[LanguageTimingConfig] = Field(
        default=None,
        description="""Per-language overrides for timing configuration (e.g. wall time).""",
    )

    @field_validator('linters', mode='before')
    @classmethod
    def _coerce_linter_shorthand(cls, v):
        if v is None:
            return []
        return [{'name': item} if isinstance(item, str) else item for item in v]

    def get_extension(self, name: str, _: Type[T]) -> Optional[T]:
        if self.extensions is None:
            return None
        if not hasattr(self.extensions, name):
            return None
        return getattr(self.extensions, name)

    def get_extension_or_default(self, name: str, cls: Type[T]) -> T:
        return self.get_extension(name, cls) or cls()

EnvironmentSandbox #

Bases: BaseModel

Parameters:

Name Type Description Default
maxProcesses int | None

Max. number of process to allow to run concurrently for the program.

1
timeLimit int | None

Time limit in milliseconds to allow the program to run.

None
wallTimeLimit int | None

Wall time limit in milliseconds to allow the program to run.

None
memoryLimit int | None

Memory limit in MiB.

None
fileSizeLimit int | None

File size limit in KiB

None
stackLimit int | None

Stack limit in MiB. Only enforced on Linux; ignored on macOS, where the stack is whatever the host shell provides. When unset, the stack is made as large as the system allows.

None
preserveEnv bool | None

Whether to preserve env. variables coming from the host.

False
mirrorDirs List[str] | None

Directories in the host that should be read-only exposed to the sandbox.

[]
Source code in rbx/box/environment.py
class EnvironmentSandbox(BaseModel):
    model_config = ConfigDict(extra='forbid')

    maxProcesses: Optional[int] = Field(
        default=1,
        description="""Max. number of process to allow to run concurrently for the program.""",
    )

    timeLimit: Optional[int] = Field(
        default=None,
        description="""Time limit in milliseconds to allow the program to run.""",
    )

    wallTimeLimit: Optional[int] = Field(
        default=None,
        description="""Wall time limit in milliseconds to allow the program to run.""",
    )

    memoryLimit: Optional[int] = Field(
        default=None,
        description="""Memory limit in MiB.""",
    )

    fileSizeLimit: Optional[int] = Field(
        default=None,
        description="""File size limit in KiB""",
    )

    stackLimit: Optional[int] = Field(
        default=None,
        description="""Stack limit in MiB. Only enforced on Linux; ignored on macOS,
where the stack is whatever the host shell provides. When unset, the stack is
made as large as the system allows.""",
    )

    preserveEnv: Optional[bool] = Field(
        default=False,
        description="""Whether to preserve env. variables coming from the host.""",
    )

    mirrorDirs: Optional[List[str]] = Field(
        default=[],
        description="""Directories in the host that should be read-only exposed to the sandbox.""",
    )

ExecutionConfig #

Bases: BaseExecutionConfig

Parameters:

Name Type Description Default
solutionOverrides SolutionExecutionOverrides

Overrides to apply when executing solutions for this language.

<dynamic>
Source code in rbx/box/environment.py
class ExecutionConfig(BaseExecutionConfig):
    solutionOverrides: SolutionExecutionOverrides = Field(
        default_factory=SolutionExecutionOverrides,
        description="""Overrides to apply when executing solutions for this language.""",
    )

FileMapping #

Bases: BaseModel

Parameters:

Name Type Description Default
input str

Path where to copy the stdin file to before running the program, relative to the sandbox root.

'stdin'
output str

Path where to output the stdout file after running the program, relative to the sandbox root.

'stdout'
error str

Path where to output the stderr file after running the program, relative to the sandbox root.

'stderr'
capture str

Path where to output the capture file after running the program, relative to the sandbox root.

'capture'
compilable str

Path where to copy the compilable file to before compiling the program, relative to the sandbox root.

'{source}'
executable str

Path to where to output the executable file after compiling the program, relative to the sandbox root.

'executable'
Source code in rbx/box/environment.py
class FileMapping(BaseModel):
    model_config = ConfigDict(extra='forbid')

    input: str = Field(
        default='stdin',
        description="""Path where to copy the stdin file to before running the program,
relative to the sandbox root.""",
    )

    output: str = Field(
        default='stdout',
        description="""Path where to output the stdout file after running the program,
relative to the sandbox root.""",
    )

    error: str = Field(
        default='stderr',
        description="""Path where to output the stderr file after running the program,
relative to the sandbox root.""",
    )

    capture: str = Field(
        default='capture',
        description="""Path where to output the capture file after running the program,
relative to the sandbox root.""",
    )

    compilable: str = Field(
        default='{source}',
        description="""Path where to copy the compilable file to before compiling the program,
relative to the sandbox root.""",
    )

    executable: str = Field(
        default='executable',
        description="""Path to where to output the executable file after compiling the program,
relative to the sandbox root.""",
    )

LanguageGroup #

Bases: BaseModel

Parameters:

Name Type Description Default
languages List[str]

rbx language names that share a single estimated time limit.

required
whenEmpty LanguageGroupFallback | None

How to derive a TL for this group when it has no solutions.

None
Source code in rbx/box/environment.py
class LanguageGroup(BaseModel):
    model_config = ConfigDict(extra='forbid')

    languages: List[str] = Field(
        description="""rbx language names that share a single estimated time limit.""",
    )
    whenEmpty: Optional[LanguageGroupFallback] = Field(
        default=None,
        description="""How to derive a TL for this group when it has no solutions.""",
    )

LanguageGroupFallback #

Bases: BaseModel

Parameters:

Name Type Description Default
relativeTo str | None

A language name whose group's estimated TL this empty group is relative to. If omitted, the multiplier is applied to the base estimate.

None
multiplier float

Slope applied to the reference TL when this group has no solutions. The resolved TL is multiplier * reference + increment.

required
increment int | None

Constant offset (in milliseconds) added on top of the multiplied reference TL when this group has no solutions. The resolved TL is multiplier * reference + increment.

None
Source code in rbx/box/environment.py
class LanguageGroupFallback(BaseModel):
    model_config = ConfigDict(extra='forbid', frozen=True)

    relativeTo: Optional[str] = Field(
        default=None,
        description="""A language name whose group's estimated TL this empty group is
relative to. If omitted, the multiplier is applied to the base estimate.""",
    )
    multiplier: float = Field(
        gt=0,
        description="""Slope applied to the reference TL when this group has no
solutions. The resolved TL is ``multiplier * reference + increment``.""",
    )
    increment: Optional[int] = Field(
        default=None,
        description="""Constant offset (in milliseconds) added on top of the
multiplied reference TL when this group has no solutions. The resolved TL is
``multiplier * reference + increment``.""",
    )

LanguageTimingConfig #

Bases: BaseModel

Parameters:

Name Type Description Default
wallTimeMultiplier float | None

Overrides the environment wall-time multiplier a for this language.

None
wallTimeIncrement int | None

Overrides the environment wall-time increment b (in milliseconds) for this language.

None
Source code in rbx/box/environment.py
class LanguageTimingConfig(BaseModel):
    model_config = ConfigDict(extra='forbid')

    wallTimeMultiplier: Optional[float] = Field(
        default=None,
        ge=1.0,
        description="""Overrides the environment wall-time multiplier `a` for this language.""",
    )

    wallTimeIncrement: Optional[int] = Field(
        default=None,
        ge=0,
        description="""Overrides the environment wall-time increment `b` (in milliseconds) for this language.""",
    )

LinterConfig #

Bases: BaseModel

Parameters:

Name Type Description Default
name str

Name of the linter to run (see registry).

required
applies_to List[AssetKind] | None

Asset kinds this linter applies to. None means all kinds.

None
Source code in rbx/box/environment.py
class LinterConfig(BaseModel):
    model_config = ConfigDict(extra='forbid')

    name: str = Field(description='Name of the linter to run (see registry).')
    applies_to: Optional[List[AssetKind]] = Field(
        default=None,
        description='Asset kinds this linter applies to. None means all kinds.',
    )

    @field_validator('applies_to', mode='before')
    @classmethod
    def _normalize_applies_to(cls, v):
        if v is None:
            return None
        out = []
        for item in v:
            if isinstance(item, AssetKind):
                out.append(item)
                continue
            token = str(item).rstrip('s')  # 'generators' -> 'generator'
            out.append(AssetKind(token))
        return out

SolutionCompilationOverrides #

Bases: BaseCompilationConfig

Source code in rbx/box/environment.py
class SolutionCompilationOverrides(BaseCompilationConfig):
    pass

SolutionExecutionOverrides #

Bases: BaseExecutionConfig

Source code in rbx/box/environment.py
class SolutionExecutionOverrides(BaseExecutionConfig):
    pass

TimingConfig #

Bases: BaseModel

Parameters:

Name Type Description Default
formula str | None

Formula to use to calculate the time limit for the environment. Mutually exclusive with multipliers. When neither is set, a default formula is used.

None
multipliers TimingMultipliers | None

Ratios used to infer the time limit from the measured solutions. Mutually exclusive with formula.

None
inferenceTimeout int | None

Time limit (in milliseconds) enforced on every solution run while the time limit is estimated, whatever the estimation strategy is. A solution expected to be too slow that hits it is dropped from the upper bound; an accepted one that hits it is an error. Defaults to 10s.

None
groups List[LanguageGroup]

Groups of related languages that share an estimated time limit.

<dynamic>
wallTimeMultiplier float

Default multiplier a in the wall-time formula a*x + b, where x is the expanded CPU time limit.

2.0
wallTimeIncrement int

Default increment b (in milliseconds) in the wall-time formula a*x + b.

0
Source code in rbx/box/environment.py
class TimingConfig(BaseModel):
    model_config = ConfigDict(extra='forbid')

    formula: Optional[str] = Field(
        default=None,
        min_length=1,
        description="""Formula to use to calculate the time limit for the environment.
Mutually exclusive with `multipliers`. When neither is set, a default formula is
used.""",
    )

    # TimingMultipliers is defined in `schema.py` so problem-level models can embed
    # it too: `schema.py` cannot import this module back without a cycle.
    multipliers: Optional[TimingMultipliers] = Field(
        default=None,
        description="""Ratios used to infer the time limit from the measured
solutions. Mutually exclusive with `formula`.""",
    )

    inferenceTimeout: Optional[int] = Field(
        default=None,
        gt=0,
        description="""Time limit (in milliseconds) enforced on every solution run
while the time limit is estimated, whatever the estimation strategy is. A solution
expected to be too slow that hits it is dropped from the upper bound; an accepted one
that hits it is an error. Defaults to 10s.""",
    )

    groups: List[LanguageGroup] = Field(
        default_factory=list,
        description="""Groups of related languages that share an estimated time limit.""",
    )

    wallTimeMultiplier: float = Field(
        default=2.0,
        ge=1.0,
        description="""Default multiplier `a` in the wall-time formula `a*x + b`, where `x` is the expanded CPU time limit.""",
    )

    wallTimeIncrement: int = Field(
        default=0,
        ge=0,
        description="""Default increment `b` (in milliseconds) in the wall-time formula `a*x + b`.""",
    )

    @model_validator(mode='after')
    def _validate_disjoint_groups(self):
        seen: set[str] = set()
        for group in self.groups:
            for lang in group.languages:
                if lang in seen:
                    raise ValueError(
                        f'Language {lang!r} appears in more than one timing group; '
                        'groups must be disjoint.'
                    )
                seen.add(lang)
        return self

    @model_validator(mode='after')
    def _validate_single_inference_timeout(self):
        if (
            self.inferenceTimeout is not None
            and self.multipliers is not None
            and self.multipliers.inferenceTimeout is not None
        ):
            raise ValueError(
                'timing.inferenceTimeout and timing.multipliers.inferenceTimeout '
                'are the same setting; keep only timing.inferenceTimeout.'
            )
        return self

    @model_validator(mode='after')
    def _validate_exclusive_strategies(self):
        if self.formula is not None and self.multipliers is not None:
            raise ValueError(
                'timing.formula and timing.multipliers are mutually exclusive; '
                'set exactly one of them.'
            )
        return self

    def resolved_inference_timeout(self) -> int:
        """The cap in effect for this environment, old spelling included."""
        if self.inferenceTimeout is not None:
            return self.inferenceTimeout
        if (
            self.multipliers is not None
            and self.multipliers.inferenceTimeout is not None
        ):
            return self.multipliers.inferenceTimeout
        return DEFAULT_INFERENCE_TIMEOUT

    def resolved_formula(self) -> Optional[str]:
        """The formula to estimate with, or None when multipliers are in use."""
        if self.multipliers is not None:
            return None
        if self.formula is not None:
            return self.formula
        return DEFAULT_TIMING_FORMULA

resolved_formula() #

The formula to estimate with, or None when multipliers are in use.

Source code in rbx/box/environment.py
def resolved_formula(self) -> Optional[str]:
    """The formula to estimate with, or None when multipliers are in use."""
    if self.multipliers is not None:
        return None
    if self.formula is not None:
        return self.formula
    return DEFAULT_TIMING_FORMULA

resolved_inference_timeout() #

The cap in effect for this environment, old spelling included.

Source code in rbx/box/environment.py
def resolved_inference_timeout(self) -> int:
    """The cap in effect for this environment, old spelling included."""
    if self.inferenceTimeout is not None:
        return self.inferenceTimeout
    if (
        self.multipliers is not None
        and self.multipliers.inferenceTimeout is not None
    ):
        return self.multipliers.inferenceTimeout
    return DEFAULT_INFERENCE_TIMEOUT

apply_walltime_formula(cpu_tl_ms, coeffs) #

Applies wall = a*x + b, where x is the expanded CPU time limit (ms).

Source code in rbx/box/environment.py
def apply_walltime_formula(cpu_tl_ms: int, coeffs: Tuple[float, int]) -> int:
    """Applies wall = a*x + b, where x is the expanded CPU time limit (ms)."""
    multiplier, increment = coeffs
    return int(cpu_tl_ms * multiplier + increment)

compute_walltime(cpu_tl_ms, language) #

Computes the wall-time limit (ms) for a CPU time limit (ms) under the active environment's coefficients for the given language.

Source code in rbx/box/environment.py
def compute_walltime(cpu_tl_ms: int, language: Optional[str]) -> int:
    """Computes the wall-time limit (ms) for a CPU time limit (ms) under the active environment's coefficients for the given language."""
    return apply_walltime_formula(cpu_tl_ms, get_walltime_coeffs_for_language(language))

get_walltime_coeffs_for_language(language) #

Reads the active environment and resolves wall-time coefficients for the given language name (None -> environment defaults).

Source code in rbx/box/environment.py
def get_walltime_coeffs_for_language(
    language: Optional[str],
) -> Tuple[float, int]:
    """Reads the active environment and resolves wall-time coefficients for the
    given language name (None -> environment defaults)."""
    env = get_environment()
    lang = get_language_or_nil(language) if language is not None else None
    return resolve_walltime_coeffs(env.timing, lang)

is_interpreted(language, solution=False) #

Whether the language runs its source directly (the compilable is the executable) rather than producing a separate binary. This is exactly the signal compile_item uses to take the passthrough path.

Source code in rbx/box/environment.py
def is_interpreted(language: str, solution: bool = False) -> bool:
    """Whether the language runs its source directly (the compilable is the
    executable) rather than producing a separate binary. This is exactly the
    signal ``compile_item`` uses to take the passthrough path."""
    config = get_compilation_config(language, solution)
    return bool(config.passthrough) or not config.commands

language_kinds(language) #

The set of :class:LanguageKind a language belongs to, derived from its toolchain: the compilation commands if it compiles, else its execution command. Deriving from the actual compiler/interpreter (not the language name) keeps dispatch robust to custom language names.

Source code in rbx/box/environment.py
def language_kinds(language: EnvironmentLanguage) -> Set[LanguageKind]:
    """The set of :class:`LanguageKind` a language belongs to, derived from its
    toolchain: the compilation commands if it compiles, else its execution command.
    Deriving from the actual compiler/interpreter (not the language *name*) keeps
    dispatch robust to custom language names."""
    if language.compilation and language.compilation.commands:
        commands = list(language.compilation.commands)
    elif language.execution and language.execution.command:
        commands = [language.execution.command]
    else:
        commands = []

    kinds: Set[LanguageKind] = set()
    for command in commands:
        parts = shlex.split(command)
        kinds |= command_kinds(parts[0] if parts else command)
    return kinds

resolve_walltime_coeffs(timing, language) #

Resolves the effective (wall_time_multiplier, wall_time_increment_ms), where a per-language override takes precedence field-by-field over the environment-level timing defaults.

Source code in rbx/box/environment.py
def resolve_walltime_coeffs(
    timing: TimingConfig,
    language: Optional[EnvironmentLanguage],
) -> Tuple[float, int]:
    """Resolves the effective (wall_time_multiplier, wall_time_increment_ms),
    where a per-language override takes precedence field-by-field over the
    environment-level timing defaults."""
    multiplier = timing.wallTimeMultiplier
    increment = timing.wallTimeIncrement
    if language is not None and language.timing is not None:
        if language.timing.wallTimeMultiplier is not None:
            multiplier = language.timing.wallTimeMultiplier
        if language.timing.wallTimeIncrement is not None:
            increment = language.timing.wallTimeIncrement
    return multiplier, increment

Extensions#

Extensions #

Bases: BaseModel

Parameters:

Name Type Description Default
boca BocaExtension | None

Environment-level extensions for BOCA packaging.

None
moj MojExtension | None

Environment-level extensions for MOJ packaging.

None
domjudge DomjudgeExtension | None

Environment-level extensions for DOMjudge tooling.

None
cms CmsEnvironmentExtension | None

Default CMS contest and task settings, which a contest overrides field by field.

None
Source code in rbx/box/extensions.py
class Extensions(BaseModel):
    boca: Optional[BocaExtension] = Field(
        default=None, description='Environment-level extensions for BOCA packaging.'
    )

    moj: Optional[MojExtension] = Field(
        default=None, description='Environment-level extensions for MOJ packaging.'
    )

    domjudge: Optional[DomjudgeExtension] = Field(
        default=None,
        description='Environment-level extensions for DOMjudge tooling.',
    )

    cms: Optional[CmsEnvironmentExtension] = Field(
        default=None,
        description='Default CMS contest and task settings, which a contest '
        'overrides field by field.',
    )

LanguageExtensions #

Bases: BaseModel

Parameters:

Name Type Description Default
boca BocaLanguageExtension | None

Language-level extensions for BOCA packaging.

None
moj MojLanguageExtension | None

Language-level extensions for MOJ packaging.

None
polygon PolygonLanguageExtension | None

Language-level extensions for Polygon packaging.

None
domjudge DomjudgeLanguageExtension | None

Language-level extensions for DOMjudge tooling.

None
cms CmsLanguageExtension | None

Language-level extensions for CMS: the CMS languages it maps to.

None
Source code in rbx/box/extensions.py
class LanguageExtensions(BaseModel):
    boca: Optional[BocaLanguageExtension] = Field(
        default=None, description='Language-level extensions for BOCA packaging.'
    )

    moj: Optional[MojLanguageExtension] = Field(
        default=None, description='Language-level extensions for MOJ packaging.'
    )

    polygon: Optional[PolygonLanguageExtension] = Field(
        default=None, description='Language-level extensions for Polygon packaging.'
    )

    domjudge: Optional[DomjudgeLanguageExtension] = Field(
        default=None, description='Language-level extensions for DOMjudge tooling.'
    )

    cms: Optional[CmsLanguageExtension] = Field(
        default=None,
        description='Language-level extensions for CMS: the CMS languages it maps to.',
    )

BOCA#

BocaExtension #

Bases: RejectsRemovedFields

Parameters:

Name Type Description Default
flags Dict[Literal[c, cpp, cc, kt, java, py2, py3], str]
{}
minRunningTime int | None
None
preferContestLetter bool
False
usePypy bool
False
languages List[str] | None
None
maximumTimeError float | None
None
Source code in rbx/box/packaging/boca/extension.py
class BocaExtension(RejectsRemovedFields):
    model_config = ConfigDict(extra='forbid')

    # Legacy: compilation flags keyed by BOCA language id. Superseded by the
    # per-language `flags` on `BocaLanguageExtension`; still read as a fallback when a
    # language leaves its own `flags` unset.
    flags: typing.Dict[BocaLanguage, str] = {}
    # Optional floor (in milliseconds) on the TOTAL BOCA time budget. When set, the
    # solution is run ceil(minRunningTime / timeLimit) times so the accumulated budget
    # reaches this floor, while the effective per-run TL stays exactly equal to the real TL.
    minRunningTime: typing.Optional[int] = Field(default=None, gt=0)
    preferContestLetter: bool = False
    usePypy: bool = False

    # Removed in rbx v1 (see the "Migrating to rbx v1" troubleshooting guide).
    languages: typing.Annotated[typing.Optional[typing.List[str]], Removed()] = Field(
        default=None,
        deprecated=(
            'Env-level `extensions.boca.languages` was removed in rbx v1. Declare '
            '`languages` per rbx language under its `extensions.boca` instead; the '
            "emitted set is the union of every language's `languages`."
        ),
    )
    maximumTimeError: typing.Annotated[typing.Optional[float], Removed()] = Field(
        default=None,
        deprecated=(
            '`maximumTimeError` was removed in rbx v1. It has been ignored since #494 '
            '(rbx emits exact fractional time limits). Use `minRunningTime` instead.'
        ),
    )

BocaLanguageExtension #

Bases: RejectsRemovedFields

Parameters:

Name Type Description Default
languages List[str] | None
None
template str | None
None
flags str | None

Compilation flags substituted into the template. Leave unset to use the template's own default.

None
bocaLanguage str | None
None
Source code in rbx/box/packaging/boca/extension.py
class BocaLanguageExtension(RejectsRemovedFields):
    model_config = ConfigDict(extra='forbid')

    # BOCA languages this rbx language maps to. The first entry is the canonical/primary
    # one, used as the forward (rbx -> BOCA) mapping. Every entry is emitted as a separate
    # per-language script dir in the BOCA package (e.g. ['cc', 'cpp'] emits both).
    languages: typing.Optional[typing.List[str]] = None
    # On-disk BOCA template dir (under rbx/resources/packagers/boca/{compile,run,
    # interactive}/) to source per-language scripts from. Required whenever `languages`
    # is set.
    template: typing.Optional[str] = None
    flags: typing.Optional[str] = Field(
        default=None,
        description='Compilation flags substituted into the template. Leave unset to '
        "use the template's own default.",
    )

    # Removed in rbx v1 (see the "Migrating to rbx v1" troubleshooting guide).
    bocaLanguage: typing.Annotated[typing.Optional[str], Removed()] = Field(
        default=None,
        deprecated=(
            '`bocaLanguage` was removed in rbx v1. Use `languages` (a list) instead, '
            'with an explicit `template`.'
        ),
    )

    @model_validator(mode='after')
    def _require_template_with_languages(self) -> 'BocaLanguageExtension':
        if self.languages and not self.template:
            raise ValueError(
                'A `template` is required when `languages` is set on a BOCA language '
                'extension. Set `template` to one of the on-disk template dirs '
                '(c, cc, cpp, java, kt, py2, py3).'
            )
        return self

    @property
    def resolved_languages(self) -> typing.List[str]:
        return self.languages or []

    @property
    def primary_language(self) -> typing.Optional[str]:
        langs = self.resolved_languages
        return langs[0] if langs else None

    @property
    def resolved_template(self) -> typing.Optional[str]:
        return self.template

CMS#

What env.rbx.yml and contest.rbx.yml say about a CMS contest.

The same cms block lives at both levels: a preset ships an organisation's defaults in env.rbx.yml, and a contest overrides them field by field in contest.rbx.yml (see settings.resolve). It has two halves, because CMS keeps submission limits and tokens on the contest and on each task, and applies both.

Every key maps to one the CMS v1.5.1 loaders read, and every enum lists only values that version accepts. An unset field is not emitted, leaving CMS's own default -- except task.scoreMode, task.publicTestcases and scorePrecision (at both levels), whose CMS defaults do not match what rbx means (see settings).

CmsContestSettings #

Bases: CmsLimits

Settings of the CMS contest itself.

The limits here count across all tasks.

Parameters:

Name Type Description Default
start AwareDatetime | None

When the contest starts (start), with a UTC offset, such as 2026-09-28T08:00:00-03:00. contest.rbx.yml only.

None
stop AwareDatetime | None

When the contest ends (stop), with a UTC offset. contest.rbx.yml only.

None
perUserTime int | None

Seconds each contestant gets, starting when they choose to, within the contest window (per_user_time). contest.rbx.yml only.

None
timezone str | None

IANA name of the timezone CMS shows times in (timezone), such as America/Sao_Paulo. Separate from the UTC offsets on start and stop.

None
allowUserTests bool | None

Whether contestants may run their code on their own inputs (allow_user_tests).

None
allowQuestions bool | None

Whether contestants may ask questions (allow_questions).

None
submissionsDownloadAllowed bool | None

Whether contestants may download their submissions (submissions_download_allowed).

None
allowPasswordAuthentication bool | None

Whether contestants may log in with a password (allow_password_authentication).

None
allowRegistration bool | None

Whether people may register themselves (allow_registration).

None
ipRestriction bool | None

Whether a contestant may log in only from their own IP addresses (ip_restriction).

None
ipAutologin bool | None

Whether a contestant is logged in from their IP address, without a password (ip_autologin).

None
blockHiddenParticipations bool | None

Whether hidden participations are kept from logging in (block_hidden_participations).

None
allowedLocalizations List[str] | None

Interface languages contestants may pick, such as en and pt_BR (allowed_localizations). Unset or empty allows them all.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsContestSettings(CmsLimits):
    """Settings of the CMS contest itself.

    The limits here count across all tasks.
    """

    start: Optional[ContestTime] = Field(
        default=None,
        description='When the contest starts (`start`), with a UTC offset, such as '
        '`2026-09-28T08:00:00-03:00`. `contest.rbx.yml` only.',
    )
    stop: Optional[ContestTime] = Field(
        default=None,
        description='When the contest ends (`stop`), with a UTC offset. '
        '`contest.rbx.yml` only.',
    )
    perUserTime: Optional[PositiveInt] = Field(
        default=None,
        description='Seconds each contestant gets, starting when they choose to, '
        'within the contest window (`per_user_time`). `contest.rbx.yml` only.',
    )
    timezone: Annotated[Optional[str], AfterValidator(_check_timezone)] = Field(
        default=None,
        description='IANA name of the timezone CMS shows times in (`timezone`), '
        'such as `America/Sao_Paulo`. Separate from the UTC offsets on `start` '
        'and `stop`.',
    )
    allowUserTests: Optional[bool] = Field(
        default=None,
        description='Whether contestants may run their code on their own inputs '
        '(`allow_user_tests`).',
    )
    allowQuestions: Optional[bool] = Field(
        default=None,
        description='Whether contestants may ask questions (`allow_questions`).',
    )
    submissionsDownloadAllowed: Optional[bool] = Field(
        default=None,
        description='Whether contestants may download their submissions '
        '(`submissions_download_allowed`).',
    )
    allowPasswordAuthentication: Optional[bool] = Field(
        default=None,
        description='Whether contestants may log in with a password '
        '(`allow_password_authentication`).',
    )
    allowRegistration: Optional[bool] = Field(
        default=None,
        description='Whether people may register themselves (`allow_registration`).',
    )
    ipRestriction: Optional[bool] = Field(
        default=None,
        description='Whether a contestant may log in only from their own IP '
        'addresses (`ip_restriction`).',
    )
    ipAutologin: Optional[bool] = Field(
        default=None,
        description='Whether a contestant is logged in from their IP address, '
        'without a password (`ip_autologin`).',
    )
    blockHiddenParticipations: Optional[bool] = Field(
        default=None,
        description='Whether hidden participations are kept from logging in '
        '(`block_hidden_participations`).',
    )
    allowedLocalizations: Optional[List[str]] = Field(
        default=None,
        description='Interface languages contestants may pick, such as `en` and '
        '`pt_BR` (`allowed_localizations`). Unset or empty allows them all.',
    )

    @model_validator(mode='after')
    def check_window(self):
        if self.start is not None and self.stop is not None:
            if self.stop <= self.start:
                raise ValueError('`stop` must come after `start`.')
            window = self.stop - self.start
            if (
                self.perUserTime is not None
                and datetime.timedelta(seconds=self.perUserTime) > window
            ):
                raise ValueError(
                    f'`perUserTime` ({self.perUserTime}s) is longer than the '
                    f'contest window ({int(window.total_seconds())}s).'
                )
        return self

CmsEnvironmentExtension #

Bases: CmsExtension

CMS settings in env.rbx.yml: a preset's defaults, without a schedule.

Source code in rbx/box/packaging/cms/extension.py
class CmsEnvironmentExtension(CmsExtension):
    """CMS settings in `env.rbx.yml`: a preset's defaults, without a schedule."""

    @field_validator('contest')
    @classmethod
    def reject_event_fields(cls, contest: Optional[CmsContestSettings]):
        if contest is None:
            return contest
        set_fields = [f for f in EVENT_FIELDS if f in contest.model_fields_set]
        if set_fields:
            raise ValueError(
                f'{", ".join(set_fields)} can only be set in contest.rbx.yml: a '
                'preset is shared between contests, and a schedule belongs to one.'
            )
        return contest

CmsExtension #

Bases: BaseModel

CMS settings: the contest's own, and those applied to every task.

Parameters:

Name Type Description Default
contest CmsContestSettings | None

Settings of the CMS contest itself.

None
task CmsTaskSettings | None

Settings applied to every task of the contest.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsExtension(BaseModel):
    """CMS settings: the contest's own, and those applied to every task."""

    model_config = ConfigDict(extra='forbid')

    contest: Optional[CmsContestSettings] = Field(
        default=None, description='Settings of the CMS contest itself.'
    )
    task: Optional[CmsTaskSettings] = Field(
        default=None, description='Settings applied to every task of the contest.'
    )

CmsLanguageExtension #

Bases: BaseModel

CMS settings of one language in env.rbx.yml.

Parameters:

Name Type Description Default
languages List[str] | None

CMS languages this rbx language maps to, by the exact name CMS gives them, such as C++20 / g++, Java / JDK or Python 3 / PyPy. A contest package allows every language of every rbx language's list. Unset, or empty, means the language has no CMS counterpart.

None
flags str | None

Flags g++ gets when the CMS host compiles a checker or interactor written in this language, such as -std=gnu++17 -O2. rbx always adds -static and the include and define flags it needs. Unset means -std=gnu++20 -O2. Graders and stubs are compiled by CMS with its own per-language commands, which this does not change.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsLanguageExtension(BaseModel):
    """CMS settings of one language in `env.rbx.yml`."""

    model_config = ConfigDict(extra='forbid')

    languages: Optional[List[str]] = Field(
        default=None,
        description='CMS languages this rbx language maps to, by the exact name CMS '
        'gives them, such as `C++20 / g++`, `Java / JDK` or `Python 3 / PyPy`. A '
        "contest package allows every language of every rbx language's list. Unset, "
        'or empty, means the language has no CMS counterpart.',
    )
    flags: Optional[str] = Field(
        default=None,
        description='Flags `g++` gets when the CMS host compiles a checker or '
        'interactor written in this language, such as `-std=gnu++17 -O2`. rbx always '
        'adds `-static` and the include and define flags it needs. Unset means '
        '`-std=gnu++20 -O2`. Graders and stubs are compiled by CMS with its own '
        'per-language commands, which this does not change.',
    )

CmsLimits #

Bases: BaseModel

Limits CMS keeps both on the contest and on each task.

Parameters:

Name Type Description Default
maxSubmissionNumber int | None

Most submissions a contestant may make (max_submission_number).

None
maxUserTestNumber int | None

Most user tests a contestant may run (max_user_test_number).

None
minSubmissionInterval int | None

Seconds a contestant must wait between two submissions (min_submission_interval).

None
minUserTestInterval int | None

Seconds a contestant must wait between two user tests (min_user_test_interval).

None
scorePrecision int | None

Decimal places scores are shown with (score_precision).

None
tokens CmsTokens | None

Tokens. A contestant may use one on a task only when both the contest and the task allow it.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsLimits(BaseModel):
    """Limits CMS keeps both on the contest and on each task."""

    model_config = ConfigDict(extra='forbid')

    maxSubmissionNumber: Optional[PositiveInt] = Field(
        default=None,
        description='Most submissions a contestant may make (`max_submission_number`).',
    )
    maxUserTestNumber: Optional[PositiveInt] = Field(
        default=None,
        description='Most user tests a contestant may run (`max_user_test_number`).',
    )
    minSubmissionInterval: Optional[PositiveInt] = Field(
        default=None,
        description='Seconds a contestant must wait between two submissions '
        '(`min_submission_interval`).',
    )
    minUserTestInterval: Optional[PositiveInt] = Field(
        default=None,
        description='Seconds a contestant must wait between two user tests '
        '(`min_user_test_interval`).',
    )
    scorePrecision: Optional[NonNegativeInt] = Field(
        default=None,
        description='Decimal places scores are shown with (`score_precision`).',
    )
    tokens: Optional[CmsTokens] = Field(
        default=None,
        description='Tokens. A contestant may use one on a task only when both the '
        'contest and the task allow it.',
    )

CmsTaskSettings #

Bases: CmsLimits

Settings applied to every task of the contest.

The limits here apply to each task separately.

Parameters:

Name Type Description Default
scoreMode CmsScoreMode | None

How the task score comes out of a contestant's submissions (score_mode). max: the best submission. maxSubtask: the best score on each subtask, summed across submissions. maxTokenedLast: the best of the tokened submissions and the last one. Defaults to max, which is what rbx means by a solution's score; CMS's own default is maxTokenedLast.

None
feedbackLevel CmsFeedbackLevel | None

How much contestants see about a submission on its public testcases (feedback_level). full: every testcase's outcome, time and memory. restricted: less.

None
publicTestcases CmsPublicTestcases | None

Which testcases contestants see results for. samples: the tests of the samples group. all: every test. none: no test. Defaults to samples.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsTaskSettings(CmsLimits):
    """Settings applied to every task of the contest.

    The limits here apply to each task separately.
    """

    scoreMode: Optional[CmsScoreMode] = Field(
        default=None,
        description="How the task score comes out of a contestant's submissions "
        '(`score_mode`). `max`: the best submission. `maxSubtask`: the best score on '
        'each subtask, summed across submissions. `maxTokenedLast`: the best of the '
        'tokened submissions and the last one. Defaults to `max`, which is what rbx '
        "means by a solution's score; CMS's own default is `maxTokenedLast`.",
    )
    feedbackLevel: Optional[CmsFeedbackLevel] = Field(
        default=None,
        description='How much contestants see about a submission on its public '
        "testcases (`feedback_level`). `full`: every testcase's outcome, time and "
        'memory. `restricted`: less.',
    )
    publicTestcases: Optional[CmsPublicTestcases] = Field(
        default=None,
        description='Which testcases contestants see results for. `samples`: the '
        'tests of the `samples` group. `all`: every test. `none`: no test. '
        'Defaults to `samples`.',
    )

CmsTokens #

Bases: BaseModel

CMS tokens. Replaced as a whole when a contest overrides a preset.

Parameters:

Name Type Description Default
mode CmsTokenMode

disabled: no tokens. infinite: a contestant may token every submission. finite: tokens are generated over time, as the fields below say. Written to CMS's token_mode.

required
maxNumber int | None

Most tokens a contestant may use in total (token_max_number). Unset means no cap. finite mode only.

None
minInterval int | None

Seconds a contestant must wait between two tokens (token_min_interval). finite mode only.

None
genInitial int | None

Tokens a contestant starts with (token_gen_initial). finite mode only.

None
genNumber int | None

Tokens generated every genInterval (token_gen_number). finite mode only.

None
genInterval int | None

Seconds between two generations (token_gen_interval). finite mode only.

None
genMax int | None

Most tokens a contestant may hold at once (token_gen_max). Unset means no cap. finite mode only.

None
Source code in rbx/box/packaging/cms/extension.py
class CmsTokens(BaseModel):
    """CMS tokens. Replaced as a whole when a contest overrides a preset."""

    model_config = ConfigDict(extra='forbid')

    mode: CmsTokenMode = Field(
        description='`disabled`: no tokens. `infinite`: a contestant may token every '
        'submission. `finite`: tokens are generated over time, as the fields below say. '
        "Written to CMS's `token_mode`.",
    )
    maxNumber: Optional[PositiveInt] = Field(
        default=None,
        description='Most tokens a contestant may use in total (`token_max_number`). '
        'Unset means no cap. `finite` mode only.',
    )
    minInterval: Optional[NonNegativeInt] = Field(
        default=None,
        description='Seconds a contestant must wait between two tokens '
        '(`token_min_interval`). `finite` mode only.',
    )
    genInitial: Optional[NonNegativeInt] = Field(
        default=None,
        description='Tokens a contestant starts with (`token_gen_initial`). '
        '`finite` mode only.',
    )
    genNumber: Optional[NonNegativeInt] = Field(
        default=None,
        description='Tokens generated every `genInterval` (`token_gen_number`). '
        '`finite` mode only.',
    )
    genInterval: Optional[PositiveInt] = Field(
        default=None,
        description='Seconds between two generations (`token_gen_interval`). '
        '`finite` mode only.',
    )
    genMax: Optional[PositiveInt] = Field(
        default=None,
        description='Most tokens a contestant may hold at once (`token_gen_max`). '
        'Unset means no cap. `finite` mode only.',
    )

    @model_validator(mode='after')
    def check_finite_only_fields(self):
        if self.mode == CmsTokenMode.FINITE:
            return self
        # CMS reads every other field only in finite mode.
        set_fields = sorted(self.model_fields_set - {'mode'})
        if set_fields:
            raise ValueError(
                f'Token mode {self.mode.value!r} takes no other field, but '
                f'{", ".join(set_fields)} {"is" if len(set_fields) == 1 else "are"} '
                'set. Only `finite` mode reads them.'
            )
        return self