Reference guide27Inspection and Conversion Tools

Produces a disassembly similar to the RISC OS memory inspection tools and is useful for quick investigation of built output.

If the instruction set is not explicit, the tool guesses from the file header where possible. When no base address is supplied, the default is zero unless the file is recognised as an Absolute file, in which case its default load address is used.

The supported DebuggerPlus flags for --debuggerplus are ANDEQasDCD, APCS, Lower, QuoteSWIs, UseDCD, UseNOP, and UseVDU. Prefix a flag with - to disable it.

Produces a byte-oriented dump similar to Dump or Memory, with an ASCII column for printable content.

fileoffset is interpreted as hexadecimal. If baseaddr is omitted, the displayed base address defaults to zero unless the file is recognised as an Absolute file, in which case the file load address is used.

Processes a textual BASIC source file and writes a tokenised BASIC V program. Input lines may already contain line numbers, but they do not need to: lines without numbers are numbered from 10 in steps of 10.

The input should already be in line-number order. The tool does not reorder lines, and it does not apply special line-number tokenisation to statements such as GOTO. Lines beginning with * are treated as star commands rather than ordinary BASIC statements.

Converts tokenised BASIC into readable text for review, migration, or source recovery. If no output file is given, the detokenised text is written to standard output.

The tool formats the tokenised input back into readable source rather than attempting a byte-for-byte recreation of the original editor input.

Summarises the sprites present in a file, reports one named sprite field by field, validates sprite structures, or emits JSON for other tooling.

With only a sprite file argument, the command prints a column summary of all sprites in the file. Supplying sprite-name selects one sprite and prints a field-by-field description instead.

For the underlying saved format, see ../appendix/sprite-file-format.

riscos-intergif is the command-line form of InterGif. It converts between GIF images and RISC OS sprite files, and can also read Draw files and Complete Animator files as input. It is suitable for simple one-file conversions and for animation-oriented workflows.

If -s is not supplied, the normal output is a GIF. With -s, the tool produces sprite output instead. This gives the common conversions of GIF to sprite, sprite to GIF, and Draw or Animator input to either sprite or GIF output.

-split writes one output file per frame from a multi-frame input, and -join usually takes one frame from each input file. The -list form is useful when the input frame order is easier to describe in a text file than on the command line.

The help also records some practical details: -trim is often useful for Draw-derived input, -best uses a median-cut palette selection, -diffuse and -zigzag tend to improve appearance at the cost of GIF compression efficiency, and -xdpi and -ydpi are intended for the values 22, 45, 90, or 180 when writing new-format sprites.

For the saved sprite structure used by sprite output, see Appendix J: Sprite File Format.

Converts between Toolbox Resource files, Wimp Template files, and the editable text form used on the host. This allows UI resources to be kept under source control as text and regenerated as binary resources when needed.

The tool decides the conversion direction from the input file contents rather than from the filename. Toolbox Resource binaries are recognised from their RESF header and version, Wimp Template binaries are recognised from their header layout, and text input is recognised only when the first sixteen bytes contain no disallowed control characters. It is commonly used with template files of type &FEC and Toolbox resource files of type &FAE.

The command takes exactly two positional arguments and has no option switches. On success it is silent in both directions. If the input is text, only the headers RESF:1.01 and Template: are accepted, selecting Toolbox Resource and Wimp Template output respectively.

CCres recreates equivalent binary content in its own normal serialisation rather than attempting a byte-for-byte copy of files made by other editors. The reliable validation workflow is therefore text-to-binary-to-text round-tripping and comparison of the textual form, not binary comparison against the original file.

For the Wimp Template binary structure, see Appendix K: Template File Format. For the editable text syntax used for both Templates and Toolbox Resources, see Appendix P: CCres textual file formats.

riscos-templateheader scans a template file and extracts named icon constants into a generated C header. It is the usual follow-on tool when code needs symbolic icon numbers derived directly from the template resource rather than maintained by hand.

The tool processes window entries in the template file, examines indirected text icons, and emits only icons whose validation strings contain an N or n term. Validation tags are parsed as semicolon-separated terms with escaped semicolons honoured. Non-window entries are ignored apart from warnings.

The default processor is the Nettle form, which reads simple tags such as Nsave and emits C enum values using the default prefix icon_. The alternative WinEdit processor selected with -t winedit reads tags such as N3/save and emits #define constants using the default prefix I. In WinEdit mode, gadget type 11 is treated as an adjuster and produces paired _down and _up names.

The built-in usage text still names the tool TemplHeadr, which reflects the historical source program name rather than the exported host wrapper name used in this environment.

A dotted output name such as h.icons is read as a RISC OS path and mapped to the host path h/icons, so the h subdirectory must already exist; if it does not, the command fails with Failed to open '...' for writing, quoting the original dotted name rather than the host path it actually tried to open.

For the template file structure that the command scans, see Appendix K: Template File Format.

riscos-mkdrawf reads a mkdrawf textual description and creates a RISC OS DrawFile. It is useful when diagrams, logos, test DrawFiles, or generated artwork need to be reproducible from source-controlled text rather than maintained only as binary Draw files.

The normal form takes exactly an input text file and an output file. The upstream manual states that the output file is created if necessary and its RISC OS filetype is set to DrawFile. The host wrapper appends the conventional host filename suffix ,aff to whatever output name it is given, so supplying that suffix explicitly produces a doubled ,aff,aff filename; give a bare output name and let the wrapper add the suffix.

The mkdrawf language can describe the DrawFile header and object types including FontTable, Text, Path, Sprite, Group, Tagged, TextArea, Options, XfText, XfSprite, and JPEG. It also supports variables, macros, named macro parameters, arithmetic, infix expressions, loops, conditionals, unit changes, colour names, and file inclusion.

Diagnostics are reported as warnings, errors, or fatal errors. The manual explains that mkdrawf tries to continue after errors to expose more than one problem, but output after an error should not be trusted even if a structurally valid DrawFile is produced. After 100 errors, the tool gives up. Use -e when the filename prefix in diagnostics would make output harder to compare.

Use riscos-decdrawf to decode an existing DrawFile back into the mkdrawf textual language. That is useful for inspection and recovery, but the best long-term workflow is to keep the mkdrawf source as the authoritative file and regenerate the DrawFile during the build.

Converts a DrawFile into the text format accepted by riscos-mkdrawf. This is useful for inspection, recovery of editable source form, and controlled changes to generated drawings.

The decoded description is written to standard output. Redirect it to a file when you want to edit the result, keep it under source control, or feed it back to riscos-mkdrawf.

The output is deliberately plain mkdrawf source. It does not use macros or variables, but it may include comments which relate the decoded text back to the original DrawFile data or remind you of editable values such as Options settings.

With -s, sprites are written to a separate sprite file and the decoded text uses FromFile references. If the DrawFile contains no sprites, the sprite file is not created. Renaming the sprite file requires the generated FromFile references to be updated before round-tripping through riscos-mkdrawf.

The upstream manual warns that -s does not emit multiple copies of duplicated sprites. If different sprites have the same name, all are written to the sprite file as they occur, with warnings. In that case, feeding the decoded text straight back to riscos-mkdrawf is not guaranteed to reproduce the intended sprite references without inspection.

With -j, JPEG image objects are written to separate files named from the supplied prefix followed by sequential numbers such as 01. The tool does not try to avoid overwriting existing files, so choose a prefix that cannot collide with files you want to keep. This also matters when a DrawFile contains enough JPEGs for generated names to be truncated or collide.

By default, dimensions are emitted in points. Use -u to request scaled points, OS units, points, millimetres, centimetres, or inches. Use -x when comparing against the binary DrawFile by hand; it shows dimensions in full 32-bit hexadecimal form and implies scaled-point units. Do not combine -x with a conflicting explicit unit selection.

Examines AOF files and reports their areas, relocations, debug records, symbols, mapping symbols, string table, and optionally disassembled code. It is useful when checking compiler or assembler output before link time.

The switches can be combined freely. A combination such as -drsg, shown in the example below, gives a broad inspection of one file: declarations, relocations, the symbol table, and debug areas. -agst (area contents with declarations, the symbol table, and the string table) is an equally valid alternative combination for a different mix of detail.

riscos-dem is a simple text filter for encoded C++ symbol names. It reads from standard input or from one or more named files, preserves whitespace exactly, and examines each non-whitespace token independently.

When a token can be decoded as a recognised mangled C++ name, the readable form is written to the output. Tokens which are not recognised are copied unchanged, so mixed text streams such as compiler output, linker maps, or assembler listings can be filtered safely.

The command has no documented option switches of its own. Any command-line word after the command name is treated as an input filename. If a named file cannot be opened, an error is written to standard error and processing continues with the next file; the final return code is non-zero if any input file could not be processed.

riscos-toansi is a source-to-source translation tool for older C code. It rewrites suitable top-level K&R-style or PCC-style function declarations and definitions into ANSI C form while leaving the rest of the source text largely unchanged.

The translator is intentionally heuristic rather than a full C parser. It only works on top-level function declarations and definitions, tracks brace nesting and conditional preprocessor structure to stay at top level, and copies constructs it does not recognise through unchanged.

When a parameter name appears in an old-style function header but no matching declaration follows, the command assumes the old C default type of int. A parameter named va_alist is rewritten to ... when no explicit declaration is found. The command also recognises a limited declaration form where an ANSI parameter list has been enclosed in comment markers and removes those markers again.

Because the translation is heuristic, unusual source forms and declarations which exceed the command's internal limits may not translate correctly. Review and rebuild the converted source after running it.

riscos-sed is the build environment wrapper for the local sed command. Its public interface is intentionally small and is limited to script selection, optional suppression of default output, built-in help, and version reporting.

Scripts may be supplied directly with -e, loaded from files with -f, or taken from the first non-option argument when neither of those options is present. Multiple -e and -f options are compiled in the order supplied.

If one or more input files are named, they are processed sequentially as a single run. If an input file cannot be opened, the command reports the problem, continues with any remaining inputs, and exits with status 2 when the run completes. Successful execution returns status 0. Usage errors and fatal internal failures terminate immediately with status 4.

This tree does not document newer GNU sed command-line additions such as in-place editing. Canonical use of the packaged command should therefore be written against the supported option set above rather than against a more recent host sed implementation.