Reference guide22Compilers, Linkers, and 64-bit Binary Tools

riscos-cc is the Norcroft C driver in the build environment. It can preprocess, compile, optionally stop after writing assembler or object output, or continue through the link stage to build a final RISC OS image.

The new canonical command documentation broadens the stage-control description beyond the older Part 4 summary. Use -E for preprocessing only, -M or -MX for dependency-oriented preprocessing, -MD for sidecar dependency files during normal compilation, -S for assembler output, -c to suppress linking, and -link when a build script needs to force the link stage back on.

Language and compatibility control includes -ansi, -pcc, -fussy, -strict, -pedantic, and -C++. The canonical documentation also records the accepted APCS qualifier families in more detail, including qualifiers such as /reentrant, /nonreentrant, /fpe3, /fpe2, /swstackcheck, /26bit, /32bit, and /fpregargs with their abbreviated forms.

Diagnostics and build-system integration are also wider than the old short help suggested. -errors redirects diagnostics, -throwback emits desktop-tool throwback messages, -desktop sets the reporting directory prefix expected by desktop tools, and -depend writes make-style dependency information to an explicit file. The warning, error-suppression, pragma-emulation, and feature toggles listed above come directly from the new standalone compiler documentation so that the Part 4 entry remains self-sufficient.

For normal RISC OS work, -apcs 3/32 remains the common 32-bit APCS form, while -zM generates code suitable for relocatable modules. If more control over the final image is needed, compile with -c and then invoke riscos-link directly.

Unlike riscos-amu, which creates its object directories automatically, riscos-cc does not create the directory implied by a o.name-style output path. Create the o directory yourself before compiling directly, or the compiler aborts with Compilation aborted: couldn't write file 'o/main'.

riscos-c++ is the 32-bit Norcroft C++ wrapper. It drives the C preprocessor, the CFront translator, the C compiler, and the linker as needed so that C++ source can be translated, compiled, and linked with one command.

The command accepts a mixture of C++ source files, C source files, and object files. C++ inputs are normally preprocessed, translated to C by CFront, compiled by cc, and then linked. C source files are compiled directly, and object files are passed straight to the linker.

The wrapper recognises the filename extensions .c++, .cpp, .c, and .o. If an input file has no extension, it is treated as a C++ source file. Recognised source and object filenames are rewritten into RISC OS form before the toolchain is invoked.

Unless an explicit output filename is supplied with -o, compiled object files are written to o.leaf, assembler output is written to s.leaf, and linked output defaults to the leafname of the first input file.

If no library list is supplied with -L, the linker uses the default C++ support libraries from C$LibRoot: o.c++lib and o.stubs.

The main stage controls are -E for preprocessing only, -F for preprocessing plus CFront translation only, -c to compile without linking, and -S or -s to stop after assembler output. When both C and C++ sources are present, each file is processed according to its recognised type and the resulting object files are linked together unless linking has been suppressed.

Use repeated -Xcpp, -Xcc, -Xlinker, or +X options to pass tool-specific arguments through directly. The wrapper help recommends repeating these options rather than trying to quote multiple parameters into one string.

The CFront translator itself is not currently supplied in this image, so any stage that needs it fails with riscos-cfront: not found; only the preprocessor, C compiler, and linker stages are usable until CFront is provided.

Links object files into absolute, utility, module, or related output formats, usually with the appropriate C library or stubs object. The stub object (C:o.stubsG for the full C99 library, or C:o.stubsGS for the smaller no-C99 variant; both are suitable for either applications or modules) supplies the entry-point glue between the built image and the shared C library; see Glossary and Building, linking, and outputs for which variant to choose.

The normal output forms are -AIF for executables, -AOF for partially linked objects, -BIN for raw binaries, and -RMF for relocatable modules.

Libraries are searched in command-line order, so provider libraries should normally appear after the objects or libraries that reference them. Use -rescan if a second library pass is needed, though sensible ordering is still preferable.

The default AIF output adds the host filetype suffix automatically: linking to -o main writes a host file named main,ff8, not a bare main.

riscos-libfile creates and maintains ALF library archives. It may be used for general-purpose file archives, but its most common use in the build environment is to create object libraries from AOF files for later use with riscos-link.

When building object libraries for later linking, use -o so the external symbol table is present and up to date. If -o is omitted during insert or delete operations, the symbol table is removed to avoid leaving stale symbol information behind. Conversely, when extracting files you would usually leave -o off, because rebuilding the symbol table during extraction is rarely useful.

Directories named in the file list are archived recursively. That is convenient for backups and source-tree packaging, but it also means that broad wildcards or directory arguments can include much more content than expected. For distribution libraries, prefer relative pathnames rather than absolute ones so extraction is not tied to one user's disc layout.

Extraction behaviour depends on the stored names. Absolute pathnames are restored to their absolute locations. Relative pathnames are restored relative to the effective current directory, or relative to the directory named by -q if that option is used. Do not mix absolute and relative pathnames in one library unless you are certain that the extraction behaviour will be acceptable.

The -t option is mainly useful for convergence testing and reproducible output, because it stores null timestamps rather than build-time timestamps. The upstream documentation also notes that library creation is performed in memory, so very large create or update operations may be limited by available RAM.

riscos64-cc is the normal configured 64-bit C compiler wrapper for this environment. It wraps aarch64-unknown-linux-gnu-gcc, runs through riscos64-transformcli by default, and adds the target macros, include paths, code-generation defaults, and final RISC OS link stage expected by the 64-bit tool family.

The wrapper defines __riscos and __riscos64, undefines the usual Linux and Unix target macros, adds the current directory plus the ${RO64EXPORT} include trees, selects -nostdlib, -march=armv8-a, -mno-outline-atomics, defaults to -fPIC unless the caller already chose a PIC mode, and adds -fpatchable-function-entry=8,8 so later link processing can patch in RISC OS-style function signatures.

If source files are supplied and neither -c nor -E is used, the wrapper first compiles to object code and then invokes riscos64-link. A one-file build defaults to <leafname>,ff8; a multi-file compile-and-link run defaults to !RunImage,ff8.

If you invoke the wrapper only with existing object files, it behaves as a thin front end to riscos64-link. In that mode you should usually supply -o explicitly, because there is no source leafname from which to derive the output name.

riscos64-link is the normal 64-bit RISC OS link wrapper. It drives GNU ld, but for application, module, and utility output it also performs the extra relocation and post-link processing required to create a usable flat RISC OS image.

The wrapper recognises four output styles: -aif for applications with filetype ff8, -rmf for relocatable modules with filetype ffa, -util for utilities with filetype ffc, and -bin for raw binaries with filetype f95. If -o is omitted, it derives the output name from the input leafname for one-file links, or defaults to !RunImage,ff8, Module,ffa, Utility,ffc, or RISCOS,f95 for multi-file links.

For normal RISC OS outputs, the wrapper selects an installed linker script and entry point beneath ${RO64EXPORT}/linker, optionally performs a partial link followed by riscos64-objdump --reloc --syms --wide and riscos64-mkreloc to build relocation support, then links the final ELF, extracts the loadable sections with objcopy, and patches function signatures into the flat binary through riscos64-addsignatures.

Unless -nostdlib is supplied, the wrapper adds ${RO64EXPORT}/libcrt.a. Library arguments of the form -lname are resolved to ${RO64EXPORT}/libname.a. The compatibility options -rescan and -C++ are accepted but have no effect.

The entry symbol expected differs by output style: -aif links normally through libcrt.a, so an ordinary main is enough, but -rmf and -util link against bare hand-written entry points and expect a function literally named _entry instead. Linking an object that only defines main as a utility fails with undefined symbol `_entry' referenced in expression.

riscos64-c++ wraps aarch64-unknown-linux-gnu-g++ with the defaults used by the 64-bit RISC OS environment. It accepts the usual RISC OS-style source naming used by the local wrappers, can preprocess, compile, or compile-and-link, and uses riscos64-transformcli by default so that source-tree naming and RISC OS path conventions are handled consistently.

The wrapper defines __riscos and __riscos64, undefines the usual Linux and Unix target macros, adds the 64-bit export include paths, selects -nostdlib, -nostdinc++, -march=armv8-a, and -mno-outline-atomics, and defaults to -fPIC unless you override it explicitly. It also adds -fpatchable-function-entry=8,8 so that generated entry points match the expected RISC OS call conventions more closely.

64-bit C++ support is intentionally limited. The wrapper always disables exceptions and RTTI with -fno-exceptions and -fno-rtti, and templates and module builds should still be treated as specialised workflows. The normal project layout therefore keeps implementation files in cc/ and headers in h/, with a conservative C++ style that interoperates cleanly with C APIs.

When source files are supplied and neither -c nor -E is used, the wrapper compiles to object code and then invokes riscos64-link to produce a RISC OS binary. A one-file build defaults to an output named after the source leaf with filetype ,ff8; multi-file compile-and-link defaults to !RunImage,ff8.

When invoked only with existing object files, riscos64-c++ becomes a thin front end to riscos64-link. In that object-only mode it does not add the C++ support libraries automatically, so manual link commands may still need to supply -lsupc++ and the C++ runtime library file explicitly. In makefile-driven builds, use ${C++LIB} rather than spelling out that library path by hand.

riscos64-gcc is the thinnest 64-bit C compiler wrapper. It calls aarch64-unknown-linux-gnu-gcc, undefines the usual Linux and Unix target macros, and defines __riscos and __riscos64.

Unlike riscos64-cc, it does not add the 64-bit export include paths, does not select a RISC OS-oriented output naming convention, does not default to PIC, and does not switch the final link stage over to riscos64-link. Use it when you want direct GCC behaviour with only the target-identification macros normalised.

riscos64-fortran is the configured 64-bit Fortran wrapper for this environment. It wraps aarch64-unknown-linux-gnu-gfortran, accepts the local RISC OS-style source layout, and when linking from source it passes the final stage to riscos64-link so that the result is a normal RISC OS binary.

The wrapper adds the target macros __riscos and __riscos64, removes the usual Linux and Unix target macros, selects -march=armv8-a -mno-outline-atomics, adds -fPIC unless the caller already chose a PIC mode, adds -fpatchable-function-entry=8,8, and includes both the current directory and ${RO64EXPORT}/Fortran.

Fortran source files normally live in f90/ without a host .f90 suffix, so a compile such as riscos64-fortran -c -o o.hello f90.hello maps naturally to host file f90/hello. Compile modules before the files that use them so that the compiler-generated .mod interface files are available.

If source files are linked directly and neither -c nor -E is used, the wrapper adds -lgfortran automatically for the final link. A single source file defaults to <name>,ff8; multiple inputs default to !RunImage,ff8. If you invoke the wrapper only with existing object files, it behaves as a front-end to riscos64-link and does not add the Fortran runtime automatically, so supply -lgfortran yourself when any Fortran object is present.

For C and Fortran interworking, use iso_c_binding, bind(C, name="..."), and the Fortran value attribute for scalar C arguments passed by value.

Linking a Fortran program directly prints a few Failed to patch symbol name '...' at &offset warnings from riscos64-addsignatures. These come from prebuilt libgfortran runtime functions that were not compiled with the wrapper's patchable-entry padding; they are harmless and the link still succeeds.

riscos64-gfortran is the thin wrapper around aarch64-unknown-linux-gnu-gfortran. It is intended for cases where you want raw GFortran behaviour but still want the RISC OS target macros defined consistently.

Unlike riscos64-fortran, it does not add the Fortran include path, does not apply the wrapper-level PIC and output naming defaults, and does not switch the final link stage over to riscos64-link. Its additions are limited to defining __riscos and __riscos64 and undefining the usual Linux and Unix target macros.

Use this command for direct compiler experiments or when you deliberately want ordinary GFortran option handling. For normal RISC OS 64-bit builds from the local f90/ source layout, the higher-level riscos64-fortran wrapper is usually the better fit.

riscos64-libfile provides a familiar libfile-style interface for 64-bit object libraries, but internally it uses GNU ar for archive operations and GNU nm for symbol listing.

The wrapper normally runs through riscos64-transformcli, so RISC OS-style file and path naming can still be used. Operation names broadly match the 32-bit riscos-libfile command, but the file format is an ordinary GNU archive of 64-bit ELF objects rather than an ALF library.

If you modify a library and are not extracting members, the wrapper normally adds an archive symbol index automatically unless you were only listing content. Use -l for a member listing and -s for a global-symbol listing.

The documented -v file syntax is not implemented by the current wrapper source, so do not rely on via-file input here.

riscos64-objdump is the direct wrapper for aarch64-unknown-linux-gnu-objdump. It exists so that users can inspect 64-bit target objects without remembering the full cross-tool name.

The wrapper adds no RISC OS policy of its own; all options are passed straight through to GNU objdump. In this environment it is especially useful for --syms, --reloc, and disassembly output when debugging 64-bit links or feeding symbol listings to the helper tools used by riscos64-link.

riscos64-objcopy is the direct wrapper for aarch64-unknown-linux-gnu-objcopy. It is supplied for convenience when working with 64-bit target objects from the build environment.

The wrapper adds no extra policy; all options are passed through unchanged. In the normal 64-bit link pipeline, the same underlying tool is used by riscos64-link to extract the loadable sections from the final ELF and write the flat RISC OS binary.

riscos64-mkreloc is a specialist helper for the 64-bit link pipeline. It reads a combined objdump listing, finds the relocations that must survive into the final flat RISC OS binary, and emits the relocation data and helper code needed to apply those relocations at run time.

The tool is normally invoked automatically by riscos64-link after an initial partial ELF link. That wrapper runs riscos64-objdump --reloc --syms --wide over the intermediate ELF, then passes the resulting text file to this command in object-output mode.

The generated object defines __RelocData in a dedicated .riscos.reloc section and, unless the linked objects already provide one, a default __RelocCode routine. The relocation table records the source and target regions as code, read-only data, or read-write data so that the binary can repair embedded addresses when loaded somewhere other than its link-time base.

The tool expects ordinary AArch64 absolute relocations described by the objdump output, and classifies sections by their conventional names such as .text, .rodata*, .data.rel.ro*, .data*, and .bss*. Use it as part of the wrapper-controlled 64-bit build flow rather than as a general relocation extractor.

For diagnostics, set ROBUILD_MKRELOC_DEBUG to a non-zero value before running the command. That enables verbose reporting about the relocations and symbols being processed.

riscos64-addsignatures is the final metadata-patching step used by the 64-bit link wrappers. It scans a finished binary for the reserved padding placed immediately before function entry points and replaces that padding with RISC OS-style function signatures containing the function names.

In the normal build flow, riscos64-link invokes this command automatically after producing the final flat binary from the linked ELF. Most users therefore never need to run it manually unless they are debugging a custom link pipeline or repairing a binary that was linked outside the wrapper.

The first argument may be either a linker map or an objdump symbol-table listing. A linker map is sufficient for normal external function names, but an objdump --syms listing is more complete because it can also include local and static function symbols from the .text section.

Only function symbols in code are considered, and only when the binary still contains the expected NOP padding before the function entry. In wrapper-driven builds that padding is normally created by the compiler wrappers with -fpatchable-function-entry=8,8. Hand-written assembler routines or objects built without those defaults are usually skipped rather than causing a failure.

If a function name is longer than the available reserved space, the tool truncates it to fit instead of aborting the build. The binary named in the second argument is rewritten in place.