FreeBSD Porter's Handbook
Prev | Chapter 7 Advanced `pkg-plist` Practices | Next

# 7.3 Configuration Files

If your port installs configuration files to ``PREFIX`/etc` (or elsewhere) do not simply list them in the `pkg-plist`. That will cause pkg_delete(1) to remove the files carefully edited by the user, and a re-installation will wipe them out.

Instead, install sample file(s) with a ``filename`.sample` suffix. Then copy the sample file to the real configuration file name, if it does not already exist. On deinstall delete the configuration file, but only if it is identical to the `.sample` file. You need to handle this both in the port `Makefile`, and in the `pkg-plist` (for installation from the package).

Example of the `Makefile` part:

    post-install:
    	@if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \
    		${CP} -p ${PREFIX}/etc/orbit.conf.sample ${PREFIX}/etc/orbit.conf ; \
    	fi

For each configuration file, create the following three lines in `pkg-plist`:

    @unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
    etc/orbit.conf.sample
    @exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi

The order of these lines is important. On deinstallation, the sample file is compared to the actual configuration file. If these files are identical, no changes have been made by the user and the actual file can be safely deleted. Because the sample file must still exist for the comparison, the `@unexec` line comes before the sample configuration file name. On installation, if an actual configuration file is not already present, the sample file is copied to the actual file. The sample file must be present before it can be copied, so the `@exec` line comes after the sample configuration file name.

To debug any issues, temporarily remove the `-s` flag to cmp(1) for more output.

See pkg_create(1) for more information on `%D` and related substitution markers.

If there is a very good reason not to install a working configuration file by default, leave the `@exec` line out of `pkg-plist` and add a message pointing out that the user must copy and edit the file before the software will work.

Prev | Home | Next
Empty Directories | Up | Dynamic Versus Static Package List

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.