SCons: targets, options and reproducible configuration
Editor/templates, debugging, profiles, parallelism and build diagnostics.
SCons reads options from SConstruct and platform/module configuration. Run commands from Source and choose platform, target and arch explicitly so repeat builds do not depend on host autodetection.
Basic commands
For an already-configured Windows x64 toolchain:
python -m SCons platform=windows target=editor arch=x86_64 -j4
python -m SCons platform=windows target=template_debug arch=x86_64 -j4
python -m SCons platform=windows target=template_release arch=x86_64 -j4These are three separate builds. Four jobs is an example, not a recommendation for every computer. Increasing -j can speed compilation or exhaust memory; reduce jobs when memory is insufficient. An unspecified target defaults to editor, but platform support still applies.
Use python -m SCons --help after installing platform dependencies to list options. It still reads project configuration; a toolchain-detection failure does not necessarily mean an option name is wrong.
Distinguish these options
| Option | Effect |
|---|---|
| target | editor, template_debug or template_release |
| arch | Target binary architecture; auto depends on platform/host |
| dev_build=yes | DEV_ENABLED; optimize=auto chooses no optimization and debug symbols default on |
| dev_mode=yes | Strict build defaults: verbose, warnings=extra, werror, tests, strict_checks, unless overridden |
| debug_symbols=yes | Symbol generation; does not enable every developer feature |
| optimize | auto, none, custom, debug, speed, speed_trace, size or size_extra |
| production=yes | Defaults for use_static_cpp, symbols and lto=auto; platform-specific details apply |
| precision | single/double built-in numerical precision; requires a consistent ABI |
| module_mono_enabled=yes | Native C# integration on supported platforms; managed artifacts are prepared separately |
With optimize=auto, current SConstruct chooses none for dev_build, speed_trace for editor/template_debug and speed for template_release. Thus an editor is not always unoptimized. Explicit optimize can change that choice.
production=yes does not guarantee LTO with every compiler: current Windows MSVC configuration maps lto=auto to none. Record effective options from logs rather than inferring them only from target names.
Configuration files
custom.py is a Python options file in Source. profile=... adds another options file; a path or a name without .py can be supplied. Command-line arguments are processed alongside these files. Retain them with the build configuration.
build_profile=... is a different mechanism: JSON containing disabled_classes and disabled_build_options. It applies after ordinary option reading and can change environment values. It is not a synonym for profile, and “the last argument always wins” does not describe every configuration stage.
custom_modules=... supplies your own module directories. Setting modules_enabled_by_default=no requires explicitly retaining dependencies of required features. Do not copy a large disable list from another project.
Incremental builds and IDEs
SCons tracks dependencies and reuses suitable outputs. Clean with --clean and the same configuration rather than an unrelated target/arch combination. SCU combines compilation units and changes memory/incremental-build behavior; establish a working ordinary configuration first.
compiledb=yes enables a C++ compilation database. compiledb_gen_only=yes finishes database generation without ordinary compilation; it does not produce a ready binary. ninja and cache_path are separate acceleration options rather than evidence of correctness.
Locate the failing stage
| Stage | Check |
|---|---|
| Python cannot find SCons | Interpreter and its environment |
| Platform/toolchain is unavailable | SDK, compiler, terminal environment and platform |
| C/C++ compilation fails | First meaningful diagnostic, include paths, compiler version and configuration |
| Linking fails | Architecture, required libraries and compatible flags |
| Binary exists but the project fails | Modules, .NET package, precision and project dependencies |
| Export fails | Required template was actually built and selected in the preset |
Options and processing order were checked against current Source. The full-build commands were not executed during this verification; querying the SCons version does not replace compilation or exported-game acceptance.
Continue with build setup and outputs, size reduction.