Generate a Free Pascal Configuration Safely with fpcmkcfg

You will use the installed x86_64-linux-gnu-fpcmkcfg-3.2.2 to inspect its built-in configuration templates, supply a value, and write a usable configuration file without losing the previous copy. The command is a template processor, not a compiler and not a general configuration editor.

Allow about fifteen minutes. You need a shell, the fp-units-rtl-3.2.2:amd64 package on this Debian-family system, and a destination where you can write a file. The installed package version is 3.2.2+dfsg-32, and the program reports version 3.2.2.

The examples write under /tmp first. Generating a file in a system directory may require elevated privileges, but the generator itself normally does not. Do not use sudo merely to make an example work: first choose a destination you own.

1. Check the installed command

Confirm the binary, package and option syntax. These are ordinary read-only checks:

$ command -v x86_64-linux-gnu-fpcmkcfg-3.2.2
/usr/bin/x86_64-linux-gnu-fpcmkcfg-3.2.2
$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -V
Version: 3.2.2
$ dpkg-query -W -f='${Package} ${Version} ${Architecture}\n' fp-units-rtl-3.2.2:amd64
fp-units-rtl-3.2.2 3.2.2+dfsg-32 amd64

The Debian executable has the target and version in its name. If your shell provides an unqualified fpcmkcfg, check that it is the program you intend to run before comparing output with this guide.

2. Inspect templates and macros before generating anything

The default template is the built-in fpc.cfg template. Print its opening lines to standard output:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 | head -12
#
# Config file generated by fpcmkcfg on 28-9-26 - 10:19:34
# Example fpc.cfg for Free Pascal Compiler
#

# ----------------------
# Defines (preprocessor)
# ----------------------

The date and time are generated values, so yours will differ. The -0 option selects the built-in fpc.cfg template and is also the default. The other built-in selections are -1 for fp.cfg, -2 for fp.ini, -3 for fppkg.cfg and -4 for the fppkg default compiler template.

Use -m to see the macros that this binary knows about, and -b to print the selected built-in template. Both commands print to standard output and change no files:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -m | head -8
BUILDDATE=28-9-26
BUILDTIME=10:19:13
COMPILERCONFIGDIR={LocalRepository}config/
FPCBIN=fpc
FPCTARGET=x86_64
FPCTARGETOS=Linux
FPCVERSION=3.2.2

Checkpoint: identify the template and the values it expects before adding definitions. A macro listed by -m is not proof that every template uses it; a custom template can introduce its own names.

3. Generate a configuration to a new file

Use -o for a file destination. This example makes an isolated directory and writes fpc.cfg there:

$ workdir=$(mktemp -d /tmp/fpcmkcfg.XXXXXX)
$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -o "$workdir/fpc.cfg"
$ head -5 "$workdir/fpc.cfg"
#
# Config file generated by fpcmkcfg on 28-9-26 - 10:19:34
# Example fpc.cfg for Free Pascal Compiler
#
$ test -s "$workdir/fpc.cfg" && echo "configuration written"
configuration written

Without -o, the generated configuration goes to standard output. That makes inspection and a deliberate redirection possible:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 > "$workdir/fpc-from-stdout.cfg"
$ test -s "$workdir/fpc-from-stdout.cfg" && echo "configuration written"
configuration written

Do not redirect output over a configuration you may need until you have checked the template and destination. Shell > truncates its target before the program starts.

4. Supply a template value correctly

The -d option takes exactly one name=value pair. The equals sign is part of the syntax. For example, the built-in release branch reacts to a RELEASE definition:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -d RELEASE=1 | grep -E '(^[[:space:]]+-O2|^[[:space:]]+-Xs|#WRITE)'
  -O2
  -Xs
  #WRITE Compiling Release Version
  -Xs

The output contains the template's conditional sections, so seeing a line in the generated text is not the same as compiling a program. The definition is input to template processing; it does not change the compiler's settings until the resulting configuration is used.

A bare name is an error on this installed version:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -d RELEASE
Error: Incomplete name-value pair "RELEASE".

Use -u name to remove a name from the processor's list. Put options before the output destination, and quote a value if the shell could interpret spaces or metacharacters.

5. Protect an existing configuration

Writing to an existing file changes state. Make a separate copy first when the file matters, then generate a replacement in a location you have checked. By default, this program saves an overwritten file as fpc.bak in the same directory:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -o "$workdir/fpc.cfg"
Saved old "fpc.cfg" to "fpc.bak"
$ test -f "$workdir/fpc.bak" && echo "backup exists"
backup exists

This is a safety net, not a full backup policy. Check the generated file and keep the backup until the compiler works with the replacement. If you need to restore the previous file, stop and use an explicit, reviewed move or copy command for your own paths; do not blindly run a generated command as root.

The -s option skips creation of that backup. Treat it as a deliberate destructive choice, useful only when another trusted backup already exists:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -s -o "$workdir/fpc.cfg"
$ test -f "$workdir/fpc.bak" && echo "backup exists" || echo "no backup created"
no backup created

6. Create missing parent directories only when intended

If the output parent does not exist, a normal write fails. The -p option tells the program to force directory creation:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -o "$workdir/nested/fpc.cfg"
Error: Directory of file ".../nested/fpc.cfg" does not exists. User -p to force creation.
$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -p -o "$workdir/nested/fpc.cfg"
$ test -s "$workdir/nested/fpc.cfg" && echo "nested configuration written"
nested configuration written

The error wording is from the installed binary. Review the complete destination before adding -p; a typo in a path can create an unwanted directory tree. This example creates only temporary directories. A system path may need elevated privileges and a maintenance plan.

7. Use a custom template when the built-ins are not enough

The -t filename option selects a template file instead of a built-in one. Start by inspecting a copy of the template, then generate to a new output path:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -t /path/to/checked-template.cfg \
    -d PROJECT_ROOT=/srv/example \
    -o "$workdir/project.cfg"
$ test -s "$workdir/project.cfg" && echo "custom configuration written"
custom configuration written

The template controls which names have an effect. Do not assume that PROJECT_ROOT is meaningful in the standard FPC template just because it is a valid name=value pair. Keep custom templates under version control or another reviewable backup, and test the generated configuration with the intended compiler account before replacing a shared file.

8. Use verbose output for a failed write

The -v option asks for verbose processing. It does not repair a bad path, create permissions, or validate that the resulting settings suit your project. Check the exit status and inspect the file separately:

$ x86_64-linux-gnu-fpcmkcfg-3.2.2 -0 -v -o "$workdir/verbose.cfg"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test -s "$workdir/verbose.cfg" && echo "output is non-empty"
output is non-empty

If generation fails, correct the template, definition or destination and rerun it to a new file. Avoid repeatedly overwriting a live configuration while diagnosing a problem. For a service or shared build host, schedule the replacement, retain the old file, and record the exact command used so the change can be reversed.