11. File manifests

The last part of the specfile contains the package file manifests. The main package's manifest begins with the %files line. If the application contains subpackages, each subpackage's manifest begins with %files name, where name is the subpackage's name, which matches the name given in the %package line.

The package manifest declares which files are installed by the package. Each filename may be listed one per line, or several filenames may be listed on the same lines, separated by spaces. Shell wildcards are permitted. Example: /usr/bin/* declares everything in $__installdir/usr/bin.

Each filename must exist in the installation tree, and everything in the installation tree (with one exception) must be claimed by someone's manifest. The sole exception are the directories themselves. As mentioned earlier, the directory /usr/bin must be created in the installation image directory, before installing /usr/bin/gizmo. Even though /usr and /usr/bin technically exist in the installation tree they do not, and should not be, declared in the manifest.

/usr/bin's presence in the package manifest means that this directory is technically installed by this package. This is unlikely to be the case, even though it's not an error if a package installs a directory that already exist. When installing a new package LPMtool creates any new directories in the package, and it is not an error if the directory already exists (although, as a side effect, the directory's ownership and permissions are set to the ownership and the permissions set by the package).

One or more modifiers may be present at the beginning of each manifest line. if present, the following modifiers apply to all filenames that follow on the same line:

%dir - declare directories

Normally a filename that refers to a directory automatically includes that directory, plus its entire contents. Specifying a filename /usr/lib/gizmo, where that filename is a directory, includes the directory itself, in the package, plus its entire contents. On the other hand, /usr/lib/gizmo/* declares only the non-hidden files in this directory (files that do not begin with the . character).

%dir disables the automatic inclusion of any directory filename for the filenames listed on this line. %dir /usr/lib/gizmo includes only this directory in the package, without including its contents. If there are any files in this directory, they should be listed elsewhere in the manifest, or in another subpackage's manifest.

%doc - documentation files

All filenames in the package manifest section must be absolute filenames, that refer to a file in the installation image. Many packages include documentation files in the source tree that do not get installed. %doc indicates that the filenames on this line are relative filenames, and refer to files in the source directory. lpbuild automatically copies these files to a designated documentation directory in the installation tree (see Section 7, “Installation image”), and automatically includes this directory in the package's manifest.

%config - configuration files

These files are configuration files. When installing or upgrading a package the checksums of all configuration files are checked, to determine whether an existing configuration file was modified (presumably the application's default configuration settings were changed).

This is done to prevent LPMtool from erasing custom configuration settings. When uninstalling a package, changed configuration files are not removed, but are renamed to a backup filename, formed by appending the current time to the configuration file's filename. The configuration file is removed if its checksum is still the same, indicating that the configuration file was left with its initial, default settings, and can be safely removed.

This also happens when upgrading a package. The new package's configuration files are installed (since LPMtool cannot assume that the older version's default configuration settings are still valid, it's always safer to install the new package's default settings since they are presumed to be valid), and if the older version's checksum has changed, it is renamed as a backup. After the new version is installed, the older configuration file's contents can be examined, and any necessary changes to the configuration settings can be reapplied to the new default configuration file.

%config(noreplace) - precious configuration files

Same as %config except that, when upgrading, the older configuration file is left untouched. The current time is appended to the new version's configuration file's name. This is done when it's important to not only preserve any changed configuration settings in the older version, but also to leave them as the default settings for the new version (any new configuration settings can be manually backported from the new version's configuration file's dated filename).

%attr(perms,user,group) - file permissions and ownership

lpbuild reads the permission of each file in the installation image. The file will be installed with the same permissions, owner by the root user. %attr overrides the default permissions and ownership.

perms explicitly specifies the permission bits, in octal. user and group specifies the ownership of the file. Any of these can be specified as - indicating that the default value should be used for the corresponding value.

%defattr(perms,user,group) - default permissions and ownership

Like %attr, but specify the default permission and ownership for the rest of this package's, or subpackage's file manifest. %attr, like all modifiers, applies only to the line it appears on. %defattr is an exception, and these settings apply to the rest of the file manifest.

%dev(type,major,minor) - special device files

lpbuild is not (should not, actually) invoked by the root user, so it cannot created special device files (which only the root user can do). Use the %dev file to specify that the following filename (or filenames) refer to a special device file (which the build script must create in the installation tree as plain files, with empty contents). type should be either B or C, which indicates a block-special, or a character-special device file. major and minor specify the special file's major and minor device numbers.

type can also be F or S, without providing major and minor. This specifies a FIFO or a filesystem-based socket entry. These special filetypes can also be created by a build script directly, root privileges are not required. This is just an alternative mechanism for getting these special files into a package. Sometimes it's more convenient for the build script to create a dummy plain file, as a placeholder, then use this approach to include these special files in the package's manifest.

%verify(list) - specify file properties to verify

lpm's --verify option checks if each file installed by a package was modified since it was installed. lpm checks a number of things: the file's size, modification time, permissions, and several other things. %verify controls which properties should be checked. The default is to check all of the following properties. Manually specify %verify when it is desirable to disable checking of certain attributes. For example, a typical log file is expected to have different contents, size, and checksum. Turning off checking of these attributes keeps --verify from complaining.

list is a space-delimited list of the following keywords, which specify the attributes to be checked. All other attributes will not be checked by --verify:

size

The file's size.

mode

The file's permission mode.

md5

The file's MD5 checksum (detects changes to the file's actual contents).

type

The file's type (FIFO, socket, block or character special device, etc...).

user

The file's owner userid.

group

The file's owner groupid.

mtime

The file's modification timestamp.

The keyword not inverts the list - all the attributes are checked except those ones that appear in the list. For example: %verify(not size md5 mtime) /var/log/*.

%ghost - ghost files

This keyword marks ghost files. The actual contents of ghost files will not be included in the package file, but their information is still included in the package file manifest. When the package is installed the ghost files are not actually created, but their information is added to the package repository. When the package gets eventually removed, any ghost files that exist at that time are removed alongside with all other files in the package.

In other words, ghost files are processed in all respects like all other files except that their contents are not added to the package file, and are not installed together with the other files in the package.

The most common example of %ghost files are log files that are generated by the application. The log files are created at runtime, but they are not installed. It is always possible to simply leave these log files out of the package manifest. Using %ghost allows these runtime files to get the benefit of LPMtool's file conflict resolution. LPMtool now prevent the application files from being overwritten by installing some other package that claims to install the same files. If these files are excluded from the manifest LPMtool won't know about their existence, and won't be able to prevent such an occurence.

Note

The build script must still create these files in the application's installation image. They will typically be zero-length files, with the correct ownership and permissions. In nearly all cases the files should also have the %verify(not size md5 mtime) keyword, so that lpm's --verify option won't complain about them, too much.