Supporting tools and tests

 

The implementation trees rely on declarations, target wrappers, Make policy and regression harnesses maintained elsewhere in the repository. These trees answer different questions: how a program calls an API, how it is packaged, which sources enter its libraries, and how its behavior is checked.

Target wrappers and application bridges

src/tools contains tools shipped or used with particular targets. These tools coordinate SDKs and application lifecycle details outside the compiler's language implementation.

• src/tools/android: fbc-android coordinates native compilation and APK packaging; Java input/activity classes and fb_android_app.c bridge the Android application environment
  
• src/tools/js: fbc-js-app chooses browser output and stages assets through the Emscripten wrapper
  
• src/tools/wii: fbc-wii supplies devkitPro/libogc tools and ELF/DOL packaging
  
• src/tools/wince: Windows CE compiler wrappers and architecture-specific invocation defaults
  
• src/tools/win32: The fbc-win32 wrapper
  
• src/tools/xbox: fbc-xbox-xiso packages an Xbox application image
  
• src/tools/riscos: Native application !Run, !Boot and !Help integration
  
  

A wrapper can select a compiler and SDK or construct an application package. The compiler still owns BASIC parsing and code generation. Native services remain in the runtime libraries. When tracing Android input, for example, follow the Java/native bridge and the selected runtime driver as well as the packaging script.

build_scripts contains developer automation, source validators, packaging and target qualification runners. Start at the script called by the relevant Make target instead of running every similarly named script. The root tools directory also contains local probes and automation; it is separate from the target helper tree under src/tools.

BASIC declarations and examples

inc supplies BASIC-facing declarations for runtime interfaces, native APIs and external libraries. A .bi file describes how compiled code calls an implementation; it does not necessarily supply that implementation. Read its calling convention, type widths and structure layout alongside the runtime or external API it describes.

examples demonstrates language and library use. The examples/manual tree supplies compact language examples, while graphics, sound and platform directories demonstrate larger APIs. Some examples need optional libraries or SDKs. An example is useful as a reproduction, but a permanent regression should assert the specific behavior in the test suite.

Choose the test that owns the failure

The main compiler/runtime suite is tests, with the harness described in tests/readme.txt. The .ss fixtures under src/tests/tmp are a separate data tree and are not the main language test entry point.

• Accepted/rejected language form or emitted diagnostic: Topic directory under tests, using the appropriate TEST_MODE
  
• Runtime result, lifetime or descriptor behavior: Topic tests built through tests/unit-tests.mk, or a focused native/runtime runner
  
• Multi-module or C interoperability behavior: A .bmk fixture consumed by tests/bmk-make.mk
  
• Software graphics or queued-renderer behavior: tests/gfx and tests/gfx3
  
• Sound state, timing or captured samples: tests/sfx
  
• Source ownership, includes or selected archive members: check-compiler-structure.py, check-rtlib-structure.py or check-gfx-source-graph.py under build_scripts
  
• Build ordering, tool failures, packaging or cleanup: mk/tests and build_scripts/test-make-contracts.py
  
  

tests/log-tests.mk handles compile-only, compile-and-run and multi-module expectations. Its saved records distinguish expected compiler rejection from abnormal failure or timeout. The log-test guide (docs/compiler-test-harness.md) explains retry selections and artifact ownership.

make warning-tests generates reports in disposable storage and compares all five target profiles with tests/warnings/r. Differences fail without changing reference files. Use make warning-tests-update only for an intentional diagnostic change, then review the reference diff. make gfx-locking-test checks input callbacks, temporary allocation, allocation failure and repeated shutdown with native MT libraries; the contract is explained in docs/gfx-locking.md.

Build ownership and generated files

The root GNUmakefile composes the layers under mk. Platform identity and feature policy precede source selection; compile and archive rules consume the resulting lists. Installation and distribution consume completed artifacts. The Make file map (mk/File-Map.md) identifies the owner of each decision.

Use make print-config to inspect the effective configuration. Structural entry points include make compiler-structure-test, make gfx-structure-test, and make make-contracts-test. The runtime structure checker is build_scripts/check-rtlib-structure.py. These checks validate ownership and build contracts; behavioral changes still need the corresponding executable regression.

Object trees, emitted bootstrap sources, linked libraries and test logs are generated inputs or outputs. Do not edit them to repair the maintained source. Quick/full build workflows include cleanup and bootstrap/package operations, so use one workflow per owned worktree. Normal and bootstrap compiler builds track effective commands, flags and selected tool contents. Independent compiler/library builds can use separate BUILD_ROOT=build/name output roots. Follow the Make guide (mk/README.md) for record ownership. make source-artifacts-test rejects generated .dump and .ctu-info files under maintained source directories and fails if a directory cannot be scanned; put analysis output in build storage.

doc contains the generated manual's source cache and tools as well as API notes. docs (docs/README.md) contains maintainer and platform guides. Keep language syntax documentation, implementation explanations and validation records linked to each other, with each retaining its own purpose.

make source-docs-test checks source-guide links and native navigation. make source-docs-render-test FBDOC=/path/to/fbdoc also generates fresh HTML, fbhelp and text in disposable storage and checks the resulting pages.