Introduction and Overview
This chapter groups the Pascal-to-C translation tools used in the build environment. They are more specialised than the normal C and assembler build path, so they are kept later in the reference section while still remaining self-sufficient for projects that depend on Pascal sources or P2C configuration.
Technical Details
Translator workflow
Use riscos-p2c when you want to inspect or retain the generated C output, generate headers, or check how configuration files affect the translation stage. Use riscos-p2cc for routine builds where the translation and compilation stages should be driven together. Where 64-bit support is present, riscos64-p2cc provides the matching convenience wrapper for the 64-bit compiler path.
For a guide-oriented overview of how Pascal translation fits into the broader build workflow, see Building, Linking, and Outputs. For the configuration file structure, see Appendix H: p2crc file format.
Commands
-o | - | Write translated C output to the named file. |
-h | - | Write the translated interface header to the named file. |
-s | - | Read additional interface text from the named file before translation. |
-p | - | Display a progress line every given number of source lines. |
-c | - | Read a local configuration commands file. |
-v | - | Documented as vanilla mode with no configuration file, but see the warning in the description below: in this build it has the opposite effect. |
-H | - | Set the home directory used for configuration lookup. |
-I | - | Add a module-search pattern. |
-i | - | Write the resolved configuration to standard output. |
-q | - | Suppress status messages. |
-E | - | Limit the number of reported errors. |
-e | - | Write source text to the output file. |
-a | - | Produce ANSI C output. |
-L | - | Select the Pascal language variant, such as TURBO or UCSD. |
-V | - | Enable verbose mode and generate a log file. |
-comp | - | Enable compiler mode to favour better generated code. |
-local | - | Use local settings for the system the translator was built on. |
-R | - | Enable regression-test mode. |
-throwback | - | Enable desktop-tool throwback error reporting. |
-depend | - | Write AMU-style dependency information to the named file. |
-d | - | Set the translator debug level. |
-t | - | Enable token-level debugging output. |
-B | - | Enable line-breaker debugging. |
-C | - | Enable comment-placement debugging. |
-F | - | Enable flow-analysis debugging. |
<file> | - | Pascal source file to translate. |
<modulename> | - | Optional module or unit name to select when the source file contains more than one module. |
riscos-p2c is the RISC OS-facing Pascal-to-C translator. It converts Pascal source into C, and when the input is a unit or module it can also generate a corresponding header file describing the translated interface.
The command is most useful when you want to inspect or keep the generated C output, generate headers, inspect the resolved system configuration with -i, or experiment with a project-local translation policy through a p2crc file. For most routine builds, riscos-p2cc is the more convenient front end because it continues directly into compilation and linking.
Configuration is resolved through the system home directory, the system configuration file, and an optional local override. The home directory comes from -H or P2C$Home. Unless -v is used, the command reads the file named by P2C$RC, or the normal %H.p2crc configuration if that variable is not set. A further local override may be supplied with -c; -c - suppresses that local stage completely.
In this build, -v does the opposite of what its description says: omitting it lets translation proceed normally even though no system p2crc file is shipped anywhere in this image, while adding -v fails outright with Unable to find required system p2crc file. Leave -v off in this environment; plain invocation, and the riscos-p2cc front end (which does not pass -v through by default), both translate without needing any configuration file to exist.
The main output controls are -o for the generated C file, -h for the generated header, and -s for additional interface text to read before translation. Source dialects are selected with -L, with common values such as TURBO, UCSD, VAX, HPUX, or MODULA. RISC OS-specific build integration is provided by -throwback for desktop diagnostics and -depend for AMU-style dependency output.
The structure of the p2crc configuration language is summarised in Appendix H: p2crc file format.
The optional modulename argument and the debugging switches are available as listed above. Use them when you need to select one module from a multi-module source file or inspect the translator's internal decisions.
<+v> | - | Print the constructed translator and compiler command lines before execution. |
-F | - | Translate Pascal source only; do not compile or link the generated C. |
-26 | - | Select the 26-bit Norcroft compiler path with the default APCS string 3/26/swst/fpr. |
-32 | - | Select the 32-bit Norcroft compiler path with the default APCS string 3/32/swst/fpr. |
-64 | - | Select the 64-bit compiler path. This is also available through the wrapper riscos64-p2cc. |
-littleend | - | Pass -littleend through to the selected C compiler. |
-bigend | - | Pass -bigend through to the selected C compiler. |
-apcs | - | Pass an explicit APCS setting through to the selected C compiler. |
-zM | - | Pass -zM through to the selected C compiler for relocatable-module code generation. |
-o | - | Pass the output filename through to the selected C compiler or linker stage. |
-S | - | Pass -S through to the selected C compiler to stop after generating assembler output. |
-c | - | Pass -c through to the selected C compiler to stop after compilation. |
-g | - | Pass debugger-generation options through to the selected C compiler. |
-l | - | Pass library-selection arguments through to the selected C compiler or link stage. |
-W | - | Pass warning-control options through to the selected C compiler. |
-e | - | Pass error-control options through to the selected C compiler. |
-z | - | Pass other compiler -z... options through, other than -zM, which has its own dedicated switch above. |
-f | - | Pass compiler feature-selection options through to the selected C compiler. |
-I | - | Pass include-path options through to the selected C compiler. |
-D | - | Pass predefined-symbol options through to the selected C compiler. |
-O | - | Pass optimisation options through to the selected C compiler. |
-throwback | - | Pass throwback support through to the translator and compiler stages. |
-depend | - | Generate dependency output suitable for makefile-driven builds. |
-L | - | Pass the Pascal language variant through to riscos-p2c. |
-h | - | Pass header-generation output through to riscos-p2c. |
<input> | - | Pascal source file to translate and build. Exactly one input file must be supplied. |
riscos-p2cc is the normal front end for building Pascal in this environment. It accepts one Pascal source file, translates it to ANSI C with P2C, then compiles and optionally links the result with the selected C toolchain.
The translator always runs first. If -F is supplied, the process stops after writing the translated C file. Otherwise the generated C is compiled, and linked unless the compiler-only switch -c was used. This is why riscos-p2cc is the usual tool for day-to-day work: it keeps the Pascal source as the true build input while hiding the temporary C artefacts.
The wrapper splits the supplied switches between P2C and the compiler. It also adds the P2C support header include path automatically and links the appropriate P2C runtime library when linking is required.
Architecture is selected by -26, -32, or -64. An explicit -apcs setting containing /26 or /32 also selects the Norcroft target, but may not be combined with the explicit architecture switches. The convenience wrapper riscos64-p2cc simply runs this command with -64 preselected.
When -depend is used, P2CC rewrites the temporary dependency output so that the final target depends on the original Pascal source rather than on the intermediate generated C file. That makes the results suitable for normal makefile-driven builds.
The wrapper forwards whole families of compiler switches to the selected C toolchain. For compiler-specific details, use the riscos-cc and riscos-p2c entries in this chapter.
<option> | - | Any riscos-p2cc option, passed through after forcing 64-bit mode. |
<input> | - | Pascal source file to translate and build. |
riscos64-p2cc is a redirect wrapper for riscos-p2cc. It runs that command with -64 already inserted, which selects the 64-bit C compiler path and the corresponding link stage.
This wrapper is the 64-bit Pascal path used both for direct command-line builds and by Pascal project makefiles when BUILD64=1 is selected. In images that include the 64-bit toolchain and Pascal runtime support, translation, compilation, and linking complete normally and produce the expected o64/ and aif64/ outputs. The 64-bit P2C runtime library (libP2C-64) is a RISC OS format archive, like its 32-bit counterpart, so it is exported alongside the other P2C libraries under Export/Lib/P2C/o/ rather than under Export64, which is reserved for host-format (non-RISC OS) build assets.
Because the underlying implementation is the normal riscos-p2cc command, that entry remains the primary reference for the translator options, compile-and-link flow, and dependency handling. This 64-bit form is mainly a convenience for users and scripts that want the architecture choice encoded in the command name.