Reference guide24Module and Interface Generation Tools

Reads a CMHG or CMunge module description and generates the veneer object and optional headers needed to connect RISC OS module entry points, command tables, SWI tables, and callback veneers to C or C++ code.

This tool is most often used in module projects and is usually driven by makefile rules rather than by hand for every build. CMunge extends the original CMHG format with support for newer toolchains, extra directive forms, and 32-bit and 64-bit targets.

The normal modern 32-bit form uses -32bit. For AArch64 veneers, use -64bit with the GCC-oriented toolchain option -tgcc. The architecture and APCS settings should match the rest of the module build.

Include -p or -px whenever the description file uses C preprocessor directives, such as the #include "VersionNum" line in the generated skeleton; without it, CMunge fails with Unknown preprocessor command encountered: #include "VersionNum".

The CMHG description syntax is summarised in Appendix G: CMHG File Format.

riscos-defmod reads a Def interface description from standard input and generates source or documentation for the SWIs, constants, and types described within it. It is the compact interface-generator tool traditionally used by OSLib-style trees to derive C headers, ObjAsm veneers, assembler headers, SrcEdit help, and StrongHelp content from one reviewed Def file.

Most output forms are written to standard output. The directory-producing forms use -o to select where the generated tree is written. The supported output selectors are: -s for one ObjAsm source file, -l for a per-SWI library-style directory tree, -h for a C header, -h++ for an experimental C++-flavoured header, -hdr for an ObjAsm header, -chelp and -asmhelp for SrcEdit help, and -cstrong for a StrongHelp directory tree.

Veneer generation depends on type-width knowledge. Locally-defined Def types can be resolved from the file itself, but externally-defined byte-sized types need to be listed with -byte_wide so the generator can distinguish byte-wide and word-wide arguments correctly. If neither -26bit nor -32bit is supplied, the default veneer output is 26-bit.

The local help still mentions a Pascal output mode with -p, but the current command-line parser does not recognise it. Conversely, -asmstrong is accepted by the parser but the main dispatch code does not produce output for it. The command entry here follows the implemented behaviour rather than the historical help text.

The Def input language consumed by the tool is summarised in Appendix R: DefMod file format.

For -l, the output directory must already contain the subdirectories the tool assembles into: s for the generated veneer source, o for 26-bit objects, and o32 for 32-bit objects. The tool does not create them itself, so create LibraryOut/s, LibraryOut/o, and LibraryOut/o32 before running it with both architecture switches.

riscos-tboxmethods is the command-line replacement for the desktop MethodGen tool. It reads a Toolbox method-definition file and generates C-callable veneers which invoke the corresponding Toolbox methods through Toolbox_ObjectMiscOp.

The input format is the MethodGen binary method-file format headed by METH. Accepted file versions are 100, 101, 102, and 103. The class record supplies the class title, object name, source path, and dependency headers, while each method record supplies its method identifier, name, optional description, and input/output register descriptions.

The generated veneer naming follows the method names recorded in the input file. The class prefix is lower-cased, and the method suffix is converted from camel-case style to underscore-separated lower case, so a method such as Window_SetTitle becomes window_set_title.

Every generated veneer returns _kernel_oserror *. Its first two arguments are always unsigned int flags for R0 and the Toolbox ObjectId for R1. Method-specific input registers are appended as additional value parameters, and method-specific output registers are exposed as pointer parameters so the veneer can write results back to the caller after a successful Toolbox call.

The generated header includes kernel.h, toolbox.h, and the dependency headers recorded in the method file. The generated source includes the same headers plus the class header itself. Unlike the original desktop tool, this command emits one C source file containing all the veneers rather than one source file per method.

You may request the header, the source, or both in one invocation. If neither -cheader nor -csource is supplied, the tool still reads and validates the method file, which is mainly useful together with -debug.

.Methods files (RISC OS filetype &FAD) are normally produced by the desktop MethodGen tool, not written by hand; this command exists to read that tool's output, not to replace it. Methods are named ClassName_MethodName in the file, such as MyObject_SetTitle, and the class title supplies the lower-cased prefix used in the generated veneer name, here myobject_set_title.

riscos-mergemoduleswis exists for module projects where CMHG owns the SWI number allocation, but the exported public header also needs hand-maintained declarations, comments, structures, or helper macros. It merges those two sources by taking the generated SWI definition block from the CMHG header and inserting it into the maintained header template.

The merge is deliberately text-based rather than a general C parser. The tool looks for the fixed CMHG marker /* SWI number definitions */, copies the following generated SWI block up to the first blank line, removes any #undef lines, removes generated X... SWI definitions, and substitutes the result for the /* SWIs here */ marker in the user header.

If the first generated numbered SWI name ends in _00, the merged block is wrapped in a matching #ifndef guard with a closing #endif. The rest of the user header is preserved unchanged.

The command requires exactly three positional parameters. If any are omitted, it prints a short syntax line and exits with failure status. If either required marker comment is absent, the merge also fails.

On non-RISC OS hosts the implementation stages its inputs and output through riscos-copy and temporary files so that file handling stays aligned with the cross-compilation environment. That detail does not change the visible three-file interface.

riscos-resgen packages one or more files into a relocatable object that can later be linked into an application or module and registered with ResourceFS, the filing-system module that exposes bundled resource files through the Resources: prefix; see Glossary.

Each file pair contributes one ResourceFS record. The tool preserves the source file length, load and exec information, and contents, padding the stored data to a word boundary as required. The generated data area is read-only.

The exported symbol named by area-name identifies a small entry stub; calling it returns the address of the packaged ResourceFS block for registration. This makes riscos-resgen the normal tool when the resources should live inside some larger linked component rather than in a standalone module.

-via is cumulative with direct file pairs on the command line. The via file is parsed as whitespace-separated tokens only; quoting is not supported. On non-RISC OS hosts, filetypes are inferred from comma-suffixed hexadecimal host filename endings such as messages,fff.

The live command reports its help under -help, and reports Unrecognised flag --help if the GNU long-option form is used. This entry documents the supported switch name rather than the unsupported alias.

riscos-modgen builds a loadable ResourceFS module rather than a plain object file. It is intended for resource collections such as messages files, templates, token files, or helper resources that should be registered automatically when the module is loaded.

Each input pair contributes one ResourceFS file entry. The generated module stores the input contents, load address, execution address, and length so that the registered resource appears with the expected metadata.

The -via file is tokenised on whitespace only, with no comment syntax and no support for filenames containing spaces. On non-RISC OS hosts, filetypes are inferred from trailing comma-suffixed hexadecimal filetypes in the source filenames; otherwise filetype &FFF is assumed.

If no resources are supplied, the tool still creates a module shell and warns that no resource files were specified. Zero-length inputs are also accepted with a warning.

The generated module includes the logic needed to register its files with ResourceFS when initialised, deregister them when removed, and re-register them if Service_ResourceFSStarting is seen.

riscos-modsqz compresses a normal relocatable RISC OS module into the squeezed form understood by later RISC OS module loaders. The input is still a module image with a normal relocatable-module header; the output is still a module file, but with a compact squeezed header and a compressed body.

The command validates the input module header before attempting compression. It rejects files whose key offsets are absent, point beyond the end of the file, or are misaligned where word alignment is required. Modules whose initoffset already has bit 31 set are treated as already squeezed and are rejected.

The module body is treated as a sequence of 32-bit words. The compressor builds tables of common full-word values and common upper-24-bit values, then estimates the final encoded size including its tables and decompressor margin. Without -f, compression is normally abandoned if that estimate exceeds about 90% of the original size. With -f, the command still proceeds provided that the real encoded output is not larger than the input.

The output file is always written with RISC OS filetype &FFA. If compression is not worthwhile and an explicit output filename was supplied, the unsqueezed input is copied unchanged to that output file. The binary squeezed-module layout is summarised in Appendix M: Squeezed module format.

In this image, riscos-modsqz segfaults when given a real relocatable module built by this environment (with or without -v); it only completes normally on inputs small enough that compression is declined outright as not worthwhile. Treat module squeezing as currently unavailable here rather than retrying with different switches.

riscos-buildrom assembles a ROM image from already prepared binary components. It does not compile or transform those inputs; it reads the named kernel and module files, writes them into a fixed-size image, and zero-fills the remaining padding space.

The description file is plain text. Its first line names the kernel image, its second line is an output name recorded by the parser, its third line is a ROM length field which is currently ignored, its fourth line is a blank separator line which is also ignored, and the remaining non-empty lines name the modules to include.

The tool always constructs a 6 MiB image and always writes the final host output file as img2. Although the description file contains an output-name field, that field is not used for the written filename.

The kernel image is written first, omitting its final four bytes. Each listed module is then written as a four-byte length word followed by the module data padded to a four-byte boundary. If the selected inputs leave too little room in the fixed-size image for the required padding, the command fails rather than writing a truncated ROM.

If -d is omitted, the live command reports Error: No description file supplied and exits with failure status.

riscos-bison is the build environment's packaged Bison command. It reads one grammar file, analyses it into LALR parser tables, and writes a generated C parser source file together with optional support outputs.

The repository port contains built-in copies of the normal parser skeletons, so the command remains usable even when external skeleton files are not installed. If external skeletons are required, the command first checks the BISON_SIMPLE and BISON_HAIRY environment variables, and otherwise falls back to the default RISC OS locations choices:bison.simple and choices:bison.hairy.

Temporary files are created beneath <Wimp$ScrapDir>.bison. Without explicit naming options, a grammar with base name name produces parser source at the RISC OS-style path c.name_tab (host c/name_tab), using _tab rather than the Unix .tab convention. With -d, the token-definition header is written alongside it at h.name_tab (host h/name_tab). When -b prefix is used, the prefix replaces name in both paths.

Grammars which use semantic-parser support may also produce extra files for semantic value types and guard code, named from the same base. Warnings are treated as a failed run, so parser output is not written when the grammar contains problems that the command considers significant.

This command does not create its own c and h output directories; create them yourself before running it, or the command crashes instead of reporting a clean error. A grammar filename containing a literal dot, such as a Unix-style expr.y, also crashes immediately with No such file or directory even though the file exists; use a plain RISC OS-style leafname with no dot instead. -v crashes separately, trying to write its verbose report into a directory named after the grammar file and aborting with a double-free when that path collides with the grammar file itself; avoid -v until this is fixed.

riscos-flex reads one or more scanner specifications and emits generated scanner source. The normal output is C, but -+ selects C++ scanner output instead.

When no input file is supplied, or when an input is named as -, the specification is read from standard input. If more than one input file is supplied they are processed in sequence as one logical scanner source.

The RISC OS port uses RISC OS-oriented default output names. Without explicit naming options the generated C scanner is written to c.lexyy, the generated C++ scanner to cc.lexyy, the backing-up report to bck.lex, and external tables to tbl.lexyy. Use -o, --header-file, or --tables-file when a project needs explicit filenames.

Important option conflicts are enforced by the local parser. --header-file cannot be combined with -t. -f and -F are mutually exclusive, and either of them conflicts with -Cm, -I, and -l. -+ conflicts with -l, -CF, --reentrant, and --bison-bridge. The option --reentrant-bison is accepted as a deprecated alias for --bison-bridge.

This command does not currently work in this image. Even the smallest valid input, a file containing only %%, fails with bad start condition list and a fatal parse error, whether read from a named file or from standard input. Treat riscos-flex as unavailable until this is fixed.

If a project depends on a generated scanner, generate it outside this environment with a working flex (any recent upstream release) and commit the generated .c/.h pair into the project's source tree, building from those directly rather than re-running riscos-flex as part of the build. This sidesteps the broken generation step entirely; only regeneration after editing the .l source needs a working flex elsewhere.

riscos-rpcgen generates Sun RPC support sources from one RPC interface definition. It runs the definition through the C preprocessor and writes the C source and header files needed for the defined types and remote procedures.

The normal invocation is riscos-rpcgen infile. That full-generation mode writes XDR support, a header, client stubs, and server stubs using filenames derived from the input base name. Add -T when dispatch-table support is required, and add -a when skeleton client and server examples are also wanted.

If only one generated file class is needed, select exactly one explicit generation switch such as -c, -h, -l, -m, -t, -Sc, or -Ss. In those single-output modes, -o may be used to choose the output filename.

The source definition is expected in the usual Sun RPC .x form containing declarations such as const, typedef, struct, union, enum, and program. Extra preprocessor symbols may be added with -D, so conditional compilation in the definition file can control which declarations appear in the generated output.

Only one explicit generation mode may be selected. Dispatch-table generation is incompatible with new-style multi-argument mode selected by -N. The built-in help banner is reached through -help, which matters because -h generates the header file rather than printing help.

Server generation has two distinct registration styles. Use -I and optionally -K for the older inetd-oriented form. Use -n for the transport-aware form. The -s registration form accepts only udp or tcp.

The infile and -o outfile arguments go through the same Unix-extension-to-RISC-OS-directory mapping as other tools in this environment. Give infile with its .x suffix, such as msg.x; the tool reads it from x.msg (host x/msg), not from a bare msg in the current directory. Likewise, -o msg_hdr.h writes to h.msg_hdr (host h/msg_hdr), not to a literal msg_hdr.h.