Reference guide32Quality and Maintenance

Runs static analysis on source code with build-environment resources configured for common RISC OS projects.

By default the wrapper adds RISC OS target macros and platform settings: -D__riscos, a 32-bit or 64-bit architecture macro set depending on BUILD64, --platform=riscos or --platform=riscos64, and a default language standard of --std=c89 for 32-bit or --std=c11 for 64-bit.

If you specify --platform=... or --std=... yourself, your values replace those defaults. Reported filenames are rewritten back into RISC OS form by default; use --filename-format=posix to keep transformed POSIX-style names instead.

When --platform=<name> uses a simple name rather than a path, the wrapper looks for platform descriptions in ~/.config/cppcheck/platform-<name>.xml, /etc/cppcheck/platform-<name>.xml, or the current directory.

This reference concentrates on the wrapper-specific behaviour. Other upstream cppcheck options are passed through unchanged.

Formats source files while using the environment's RISC OS-oriented support resources.

The wrapper accepts RISC OS-style filenames through riscos-transformcli, selects the environment's default /etc/indent.pro profile if the user does not already have a personal ~/.indent.pro, and sets VERSION_CONTROL=never so that indent does not leave backup files behind.

If you want a different personal style profile, create ~/.indent.pro on the host side and the wrapper will leave your profile selection alone.

This reference documents the wrapper behaviour and positional file handling. Other GNU indent switches are passed through unchanged.

Searches the system and built library databases to find headers, functions, defines, and library names. It is intended as a discovery tool when you are trying to work out which include file or library export a project needs.

Bare queries ending in .h are treated as header lookups. Other bare queries are treated as function or define lookups. Use --func, --lib, --lib-list, or --symbols when you need a more specific query mode.

The search covers both the locally built export tree and the installed system export tree, with locally built results taking priority. The --less option can open matched files directly for inspection, and --index or --index-system rebuild the SQLite indexes when needed.

riscos-tooltester runs a command-line tool repeatedly according to a plain text test description, captures output, checks return codes, and can validate files or directories created by the tool.

The normal calling convention is to place any switches first, then pass the tool under test and the directory containing the suite. By default the runner reads tests.txt from that directory. The script format is designed for repository-local maintenance: it is simple to diff, easy to split with Include:, and keeps expected output in ordinary text files.

Tests are arranged into Group: blocks and Test: entries. A group establishes default statements such as Command:, Replace:, or Env:; each following test inherits those values and may override them or clear them with a leading minus form such as -Expect:.

Captured output is compared against the file named by Expect: after any optional replacement script named by Replace: has normalised unstable data such as paths, timestamps, branch names, or memory addresses. When output mismatches, the runner writes the post-replacement actual output to the expectation pathname with -actual appended, which makes it easy to inspect the real result before updating the expected file.

The tool also checks side effects. Creates: and CreatesDir: assert that files or directories were created, Removes: and Absent: assert that paths are absent after the run, and built-in checker families such as text, binary, aof, alf, and elf can validate the created file content or structure.

Use -group and -test for narrow reruns while debugging. Add -show-command, -show-output, or -show-diff when you need more diagnostics, and use -junitxml when integrating the results with CI reporting.

The installed topic help mentions a -fast-fail option, but that switch is not implemented by the runner; do not rely on it.

riscos-fixuptemplate reads a Template file, walks each window object, classifies its icons, and reports warnings against individual icons or against the window as a whole. The checks are advisory rather than a complete style-guide validator, but they are useful when cleaning older templates or checking the consistency of generated resources.

The warning passes cover window flags, title formatting, approximate aspect ratio, validation-string usage, questionable flag combinations, recommended icon sizes, edge spacing, alignment, label and button content, and dialogue-box structure such as divider placement and default-button uniqueness.

Automatic correction is limited mainly to dialogue-box geometry. When a window looks like a dialogue box with a divider and one or more action or default buttons, the tool may move the divider, resize the window, reposition buttons into expected local-action and activation groups, and update the visible-area extents before writing an output file.

If no output file is supplied, the command operates in report-only mode and writes warnings to standard output. An output file may be supplied either positionally or through -o. When written, that file is given RISC OS filetype &FEC. The live command does not provide a separate -h help flag; its built-in usage text is shown when invoked without the required template filename.

riscos-hdrtoh reads the simple assembler-style definition headers used in the RISC OS source tree and writes equivalent constants for other languages. The default output language is C, but the tool can also generate BASIC, Pascal, Python, and Fortran forms.

Unlike most other wrappers in this guide, the -o filename is used exactly as given, with no RISC OS dot-as-directory translation. A dotted name such as h.swis therefore creates a literal host file called h.swis in the current directory rather than h/swis, and the generated C include guard embeds that literal name, producing an invalid identifier such as RISCOS_h.swis_H. Give a normal host-style path such as h/swis instead, with any intermediate directory created in advance.

The parser is intentionally simple. It is designed for interface headers that define constants, SWIs, and related values, not for arbitrary assembler source or headers that rely on complex conditional logic and macro programming.

The tool recognises or ignores the simple directive vocabulary used in these headers, including directives such as SUBT, TTL, GBLA, GBLL, GBLS, SETA, SETL, and SETS, but it should not be treated as a general assembler.

riscos-prminxml is the main PRM-in-XML conversion and validation tool. It turns structured XML interface documentation into presentation formats such as HTML, StrongHelp skeletons, command-help text, generated headers, or indexed multi-document books.

The normal controls are -f to choose the output format, -o or -O to choose where the generated output will go, and --lint to validate the source while formatting it. If no format is selected explicitly, the default is html, but the usual local workflow is to choose the format deliberately.

The most common formats are skeleton to create a starter document, lint to validate structure against the PRM DTD, html5+xml for modern HTML plus a copy of the XML, command to generate VTranslate-style command help, header to generate C constants, stronghelp to generate a StrongHelp directory skeleton, and index to build a complete indexed documentation set from an index.xml control file.

-f lint performs only validation. The separate --lint switch can be combined with another output format so that the document is both validated and rendered in one run. For multi-document builds the indexed form is described by --help-indexed, which explains the index.xml layout, output directories, and section/page listing structure.

--param passes stylesheet-specific settings through to the selected renderer. Useful controls include create-contents, css-base, css-variant, override-docgroup, and chapter-number or edge-index overrides for HTML5 output. Use --help-params to inspect the parameter set supported by the installed transforms before relying on one in a build script.

Do not write generated output into the same directory as the source when using -O. Generated files may overwrite the source tree. The installed reference material for the format lives in /riscos-resources/Install/Tools/Linux/riscos-prminxml-resources/docs, with HowTo.md and PRMinXML.txt being the most useful starting points.

git absorb examines the staged changes in the Git index, works out which earlier commits those changes most likely belong to, and creates fixup! commits targeted at those earlier commits. It is designed for the common review-cleanup case where you have several small fixes that should be merged into earlier atomic commits rather than left as one opaque follow-up change.

The normal workflow is: stage the fixes with git add, run git absorb, inspect the generated fixup commits, and then fold them back with git rebase -i --autosquash. The convenience flag --and-rebase performs the rebase automatically after generating the commits. Use --dry-run to inspect what would happen without creating commits.

By default the tool considers staged changes and matches them against earlier commits on the current branch. Use --base to set the absorb base explicitly, --force-author to allow fixups to commits by other authors, --force-detach to work on a detached HEAD, and --one-fixup-per-commit to reduce multiple fixups to one per target commit.

If the result is not what you wanted, you can recover the previous branch state with git reset --soft PRE_ABSORB_HEAD or by using the reflog.

The shipped build-environment topic help covers the normal workflow and a small subset of switches, but it does not document every installed option and still mentions options that are not present in the current git absorb -h output. The switch list above is therefore based on the installed command help rather than the shorter topic summary.

riscos64-cppcheck is a thin wrapper around riscos-cppcheck. It sets BUILD64 to 1 unless BUILD32 is already explicitly set, then runs the normal checker wrapper.

That means the real analysis behaviour still comes from riscos-cppcheck: the same wrapper resources, platform defaults, filename rewriting, and passthrough option handling apply. The only extra behaviour is the 64-bit build selection, which changes the default platform and architecture macro assumptions to match a 64-bit build.