Generate a Free Pascal Config Safely with fpcmkcfg

Overwrite /etc/fpc.cfg with a half-checked file and every Pascal build on the box changes behaviour at once. This guide has you generate a Free Pascal configuration with fpcmkcfg into a temporary location first, with the template and version checked before anything touches a real path. It uses the Debian fp-compiler-3.2.2:amd64 package, version 3.2.2+dfsg-32, and its fpcmkcfg 3.2.2 binary.

Allow about fifteen minutes. You need a shell and the Free Pascal compiler package. The examples write only under /tmp until you deliberately pick a real configuration path. Writing into a system directory needs elevated privileges, but inspecting templates and generating a temporary file does not.

1. Check the installed command

Confirm which executable runs and which package supplied it:

$ command -v fpcmkcfg
/usr/bin/fpcmkcfg
$ dpkg-query -W -f='${Package} ${Version}\n' fp-compiler-3.2.2
fp-compiler-3.2.2 3.2.2+dfsg-32
$ fpcmkcfg -V
Version: 3.2.2

The installed manpage is no use as an option reference: it calls the program incomplete and lists no switches. On this build the command's own -h output is the reliable quick reference. The long spelling --help is not accepted by this binary, so use -h.

2. Inspect the templates first

With no output option, fpcmkcfg writes the generated configuration to standard output. Its built-in template is the normal compiler configuration, chosen explicitly with -0 or implicitly when you give no template selector:

$ fpcmkcfg -b | sed -n '1,16p'
#
# Config file generated by fpcmkcfg on %BUILDDATE% - %BUILDTIME%
# Example fpc.cfg for Free Pascal Compiler
#

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

#
# nested #IFNDEF, #IFDEF, #ENDIF, #ELSE, #DEFINE, #UNDEF are allowed
#
# -d is the same as #DEFINE
# -u is the same as #UNDEF

-b prints the selected built-in template instead of a generated file. The other built-in choices:

• -1 selects fp.cfg.
• -2 selects fp.ini.
• -3 selects fppkg.cfg.
• -4 selects the default fppkg compiler template.

Use -m to print the built-in macro values, including paths such as basepath and localbasepath.

$ fpcmkcfg -m | sed -n '1,8p'
BUILDDATE=23-9-26
BUILDTIME=17:13:07
COMPILERCONFIGDIR={LocalRepository}config/
FPCBIN=fpc
FPCTARGET=x86_64
FPCTARGETOS=Linux
FPCVERSION=3.2.2

The date and time come from one run and will change. This is a template inspection, not a promise that every host has the same library or compiler paths.

3. Generate a temporary configuration

Choose an output file with -o. This creates or replaces a file in /tmp, so no root access is needed:

$ workdir=$(mktemp -d /tmp/fpcmkcfg.XXXXXX)
$ fpcmkcfg -0 -o "$workdir/fpc.cfg"
$ test -s "$workdir/fpc.cfg" && echo "generated: $workdir/fpc.cfg"
generated: /tmp/fpcmkcfg.ABC123/fpc.cfg

Your temporary directory suffix will differ. Check the beginning and the target-specific paths before using the file:

$ sed -n '1,12p' "$workdir/fpc.cfg"
$ rg -n '^-F[ulD]' "$workdir/fpc.cfg" | head

Without -o, the equivalent command sends the configuration to standard output, which suits review or redirection:

$ fpcmkcfg -0 > "$workdir/review.cfg"
$ cmp "$workdir/fpc.cfg" "$workdir/review.cfg" || echo "timestamps or generated content differ"

4. Supply template values on purpose

Select a custom template with -t filename. Percent-delimited values in it are substituted from built-in or command-line definitions. The definition syntax is -d name=value, not a bare name:

$ printf '%s\n' 'compiler_root=%basepath%' 'compiler_version=%FPCVERSION%' > "$workdir/template.cfg"
$ fpcmkcfg -t "$workdir/template.cfg" \
    -d 'basepath=/opt/fpc/3.2.2' \
    -o "$workdir/custom.cfg"
$ cat "$workdir/custom.cfg"
compiler_root=/opt/fpc/3.2.2
compiler_version=3.2.2

Quote the whole name=value argument when the value has spaces, shell punctuation or a path built from a variable. An incomplete definition fails before any file is generated:

$ fpcmkcfg -d FPCROOT
Error: Incomplete name-value pair "FPCROOT".

Use -u name to remove a name from the definition list. Keep this apart from the Free Pascal preprocessor directives that may appear in the result: fpcmkcfg does its substitutions, and the compiler later interprets directives such as #IFDEF.

5. Avoid the missing-directory error

fpcmkcfg does not create missing parent directories by default. -p forces creation:

$ fpcmkcfg -0 -p -o "$workdir/generated/fpc.cfg"
$ test -s "$workdir/generated/fpc.cfg" && echo "parent directory created"
parent directory created

Without -p, a missing parent gives an error like Directory of file "..." does not exists. User -p to force creation. That wording is the program's own, grammar slips included.

6. Know how backups work before overwriting

Writing to an existing output file saves the old one beside it with a .bak suffix. That changes state, so inspect the path first:

$ test -f "$workdir/fpc.cfg" && echo "existing file will be backed up"
existing file will be backed up
$ fpcmkcfg -0 -o "$workdir/fpc.cfg"
Saved old "fpc.cfg" to "fpc.bak"
$ test -s "$workdir/fpc.bak" && echo "backup exists"
backup exists

Keep the backup until you have checked the replacement. To undo this example, remove the generated file and move the backup back:

$ rm "$workdir/fpc.cfg"
$ mv "$workdir/fpc.bak" "$workdir/fpc.cfg"

7. Install only after review

Once the temporary file has the paths and options you expect, copy it to the configuration location documented by your Free Pascal installation. This is where elevated privileges may be needed. The command does not name a universal system destination, so do not guess one from a guide written for another package layout.

Before replacing a live file, make a separate administrator-controlled backup and check its ownership:

$ sudo cp -a /etc/fpc.cfg /etc/fpc.cfg.before-fpcmkcfg
$ sudo fpcmkcfg -0 -o /etc/fpc.cfg
$ sudo fpcmkcfg -0 -v -o /etc/fpc.cfg

The second fpcmkcfg command is only meant as a check that generation succeeds at that path. If the compiler then misbehaves, restore the backup and investigate the generated paths:

$ sudo cp -a /etc/fpc.cfg.before-fpcmkcfg /etc/fpc.cfg