Compile Pascal Directly with ppcx64

ppcx64 is the x86-64 backend behind Free Pascal, and calling it directly pins exactly that backend and shows exactly what it does. Allow about ten minutes if Free Pascal is already installed. The examples use the fp-compiler-3.2.2 package, version 3.2.2+dfsg-32, on amd64.

Its own manpage points elsewhere: use fpc, which picks the right backend for you. Going direct still earns its keep when you are checking this installed compiler, forcing an explicit output directory, or diagnosing a backend invocation that fpc is hiding from you.

1. Check the Installed Compiler

Start with read-only checks. None of these need sudo or any other elevated privilege:

$ command -v ppcx64
/usr/bin/ppcx64
$ dpkg-query -W -f='${Package} ${Version} ${Architecture}\n' fp-compiler-3.2.2
fp-compiler-3.2.2 3.2.2+dfsg-32 amd64
$ ppcx64 -iV
3.2.2
$ ppcx64 -iTP
x86_64
$ ppcx64 -iTO
linux

The -i family prints compiler information: the suffixes above report the version, target processor and target operating system. Keep the package version and the compiler-reported version together in bug reports, since distribution packaging can add a revision such as +dfsg-32.

Checkpoint: You should have a working command, version 3.2.2, and an x86-64 Linux target. If command -v finds nothing, install or repair the compiler through your normal package-management process. Do not hand-copy a compiler binary into /usr/bin.

2. Create a Minimal Source File

Make a new file in a working directory. This is an ordinary, unprivileged file operation. The program takes no input, touches no network, and writes exactly one line:

program CompileCheck;
begin
  writeln('ppcx64 compile check passed');
end.

Save it as compile-check.pas. Pascal source normally uses the .pas extension, though the compiler accepts other source names too. Check the file before compiling:

$ sed -n '1,10p' compile-check.pas
program CompileCheck;
begin
  writeln('ppcx64 compile check passed');
end.

A common distraction is starting with a large project. This tiny source isolates the compiler, linker and local configuration from project-specific units and build scripts.

3. Compile Into a Separate Output Directory

Create a destination you own, then pass it with -FE. Keeping generated files out of the source directory makes a first test easier to inspect:

$ mkdir -p build
$ ppcx64 -FEbuild compile-check.pas
Free Pascal Compiler version 3.2.2+dfsg-32 [2024/01/05]
Copyright (c) 1993-2021 by Florian Klaempfl and others
Target OS: Linux for x86-64
Compiling compile-check.pas
Linking build/compile-check
4 lines compiled, 0.6 sec

The elapsed time and some diagnostic wording will vary. What matters is a zero exit status, a link step, and an executable under build. An object file left alongside it is normal intermediate output.

Checkpoint: Verify the generated files without running anything yet:

$ find build -maxdepth 1 -type f -printf '%f\n' | sort
compile-check
compile-check.o
$ file build/compile-check
build/compile-check: ELF 64-bit LSB pie executable, x86-64, ...

Your file output can carry different compiler, linker or build metadata. It should identify an executable for x86-64, not a text file or an object file.

4. Run and Verify the Executable

Run the newly created file from the shell. Still unprivileged, since the output lives in your working directory:

$ ./build/compile-check
ppcx64 compile check passed
$ printf 'exit status: %s\n' "$?"
exit status: 0

Checking both the line and the exit status catches two different problems. The line proves this executable contains the source program's code; status 0 proves the process returned successfully. Neither proves a larger application has every unit or runtime resource it needs.

5. Keep Configuration and Backend Usage Straight

Free Pascal reads fpc.cfg before processing a source file. That configuration supplies paths for the RTL and packages and can add default switches, which is why a direct invocation can behave differently across machines even with identical source.

See the full installed option list with:

$ ppcx64 -h | sed -n '1,24p'
Free Pascal Compiler version 3.2.2+dfsg-32 [2024/01/05]
Copyright (c) 1993-2021 by Florian Klaempfl and others
/usr/lib/x86_64-linux-gnu/fpc/3.2.2/ppcx64 [options] <inputfile> [options]
 Put + after a boolean switch option to enable it, - to disable it.
  @<x>   Read compiler options from <x> in addition to the default fpc.cfg
  -a     The compiler does not delete the generated assembler file

For ordinary project builds, start with fpc project.pas. The ppcx64 manpage explicitly describes itself as a backend and points readers to fpc for selecting the right target compiler. Reach for direct ppcx64 calls when you have a reason to pin that backend, not as a habit that replaces the project build system.

6. Diagnose Failures Without Guessing

If the compiler cannot find a unit, read the exact missing filename first and inspect the configured or supplied unit paths. Do not solve a path error by running as root. For a project unit directory, retry with an explicit path:

$ ppcx64 -Fu/path/to/project/units -FEbuild project.pas

Need more messages? -vi enables general information and -vw enables warnings. Add one at a time for a reproducible diagnostic, and keep the full command in your build notes:

$ ppcx64 -vi -vw -FEbuild compile-check.pas

Warning: If compilation stops after a previous failed attempt, inspect the output directory before rerunning. A stale executable can make a failed build look successful if you run it anyway. Use a new directory, or remove only the known generated files: removing files is irreversible, so do not aim a broad wildcard at a directory containing source or hand-written artefacts.

To clean this example safely, remove the dedicated output directory once you have finished checking it:

$ rm -r -- build

That command changes state and needs no elevated privilege, but it permanently deletes everything under build. Keep the executable by not running that command. The source file compile-check.pas sits outside that directory and is untouched.

Done means