Generate a Free Pascal Configuration Safely with fpcmkcfg

You will finish with a Free Pascal configuration file generated into a chosen location, with its template and version checked first. This guide 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 choose a real configuration path. Writing into a system directory will require elevated privileges, but inspecting templates and generating a temporary file does not.

1. Check the installed command

Start by confirming which executable is being run 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 not a useful option reference: it describes the program as incomplete and lists no actual 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 when you need help.

2. Inspect the templates before generating anything

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

$ 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 are -1 for fp.cfg, -2 for fp.ini, -3 for fppkg.cfg, and -4 for 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 are examples from one run and will change. Treat the output as a template inspection, not as a promise that every host has the same library or compiler paths.

3. Generate a temporary compiler configuration

Choose an output file with -o. This ordinary command 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. Verify 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 is convenient for review or redirection:

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

The generated file contains conditional compiler options and host-derived paths. Do not copy it blindly to another architecture or distribution. Inspect and adjust it for the compiler installation that will consume it.

4. Supply template values deliberately

A custom template is selected with -t filename. Percent-delimited values in that template are substituted from built-in or command-line definitions. The definition syntax is -d name=value, not just 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 contains spaces, shell punctuation or a path assembled by a variable. An incomplete definition fails before a 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 separate from the Free Pascal preprocessor directives that may appear in the resulting configuration: fpcmkcfg performs its substitutions, while the compiler later interprets configuration directives such as #IFDEF.

5. Prevent an accidental directory failure

fpcmkcfg does not create missing parent directories by default. -p forces directory 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 produces an error similar to Directory of file "..." does not exists. User -p to force creation. That wording is from the program, including its grammatical error. Create the directory yourself if you need tighter control over ownership and permissions.

6. Understand backups before overwriting a file

Writing to an existing output file saves the old file beside it with a .bak suffix. This is a state-changing operation, 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 into place:

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

Do not run rm against a system configuration path copied from an example. For an overwrite where you have an independent backup and explicitly do not want fpcmkcfg to create another one, use -s. That suppresses the automatic backup; it does not make the replacement reversible.

7. Install only after reviewing the result

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 the point where elevated privileges may be required. The command itself does not identify 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 command is only a verification that generation succeeds at that path. If the compiler then behaves unexpectedly, restore the backup and investigate the generated paths:

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

The -v switch enables verbose output. It is useful when reviewing generation, but it does not validate that every referenced unit or library directory exists on the machine.