8.6. Expanding Package List with Keywords

All keywords can also take optional arguments in parentheses. The arguments are owner, group, and mode. This argument is used on the file or directory referenced. To change the owner, group, and mode of a configuration file, use:

@sample(games,games,640) etc/config.sample

The arguments are optional. If only the group and mode need to be changed, use:

@sample(,games,660) etc/config.sample

Warning:

If a keyword is used on an optional entry, it must to be added after the helper:

%%FOO%%@sample etc/orbit.conf.sample

This is because the options plist helpers are used to comment out the line, so they need to be put first. See Section 5.13.3.1, “OPTIONS_SUB for more information.

8.6.1. @desktop-file-utils

Will run update-desktop-database -q after installation and deinstallation. Never use directly, add USES=desktop-file-utils to the Makefile.

8.6.2. @fc directory

Add a @dir entry for the directory passed as an argument, and run fc-cache -fs on that directory after installation and deinstallation.

8.6.3. @fcfontsdir directory

Add a @dir entry for the directory passed as an argument, and run fc-cache -fs, mkfontscale and mkfontdir on that directory after installation and deinstallation. Additionally, on deinstallation, it removes the fonts.scale and fonts.dir cache files if they are empty. This keyword is equivalent to adding both @fc directory and @fontsdir directory.

8.6.4. @fontsdir directory

Add a @dir entry for the directory passed as an argument, and run mkfontscale and mkfontdir on that directory after installation and deinstallation. Additionally, on deinstallation, it removes the fonts.scale and fonts.dir cache files if they are empty.

8.6.5. @glib-schemas

Runs glib-compile-schemas on installation and deinstallation.

8.6.6. @info file

Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through INFO. See Section 5.12, “Info Files” for more information.

8.6.7. @kld directory

Runs kldxref on the directory on installation and deinstallation. Additionally, on deinstallation, it will remove the directory if empty.

8.6.8. @rmtry file

Will remove the file on deinstallation, and not give an error if the file is not there.

8.6.9. @sample file [file]

This is used to handle installation of configuration files, through example files bundled with the package. The actual, non-sample, file is either the second filename, if present, or the first filename without the .sample extension.

This does three things. First, add the first file passed as argument, the sample file, to the plist. Then, on installation, if the actual file is not found, copy the sample file to the actual file. And finally, on deinstallation, remove the actual file if it has not been modified. See Section 8.3, “Configuration Files” for more information.

8.6.10. @shared-mime-info directory

Runs update-mime-database on the directory on installation and deinstallation.

8.6.11. @shell file

Add the file passed as argument to the plist.

On installation, add the full path to file to /etc/shells, while making sure it is not added twice. On deinstallation, remove it from /etc/shells.

8.6.12. @terminfo

Do not use by itself. If the port installs *.terminfo files, add USES=terminfo to its Makefile.

On installation and deinstallation, if tic is present, refresh ${PREFIX}/share/misc/terminfo.db from the *.terminfo files in ${PREFIX}/share/misc.

8.6.13. Base Keywords

There are a few keywords that are hardcoded, and documented in pkg-create(8). For the sake of completeness, they are also documented here.

8.6.13.1. @ [file]

The empty keyword is a placeholder to use when the file's owner, group, or mode need to be changed. For example, to set the group of the file to games and add the setgid bit, add:

@(,games,2755) sbin/daemon

8.6.13.2. @preexec command, @postexec command, @preunexec command, @postunexec command

Execute command as part of the package installation or deinstallation process.

@preexec command

Execute command as part of the pre-install scripts.

@postexec command

Execute command as part of the post-install scripts.

@preunexec command

Execute command as part of the pre-deinstall scripts.

@postunexec command

Execute command as part of the post-deinstall scripts.

If command contains any of these sequences somewhere in it, they are expanded inline. For these examples, assume that @cwd is set to /usr/local and the last extracted file was bin/emacs.

%F

Expand to the last filename extracted (as specified). In the example case bin/emacs.

%D

Expand to the current directory prefix, as set with @cwd. In the example case /usr/local.

%B

Expand to the basename of the fully qualified filename, that is, the current directory prefix plus the last filespec, minus the trailing filename. In the example case, that would be /usr/local/bin.

%f

Expand to the filename part of the fully qualified name, or the converse of %B. In the example case, emacs.

Important:

These keywords are here to help you set up the package so that it is as ready to use as possible. They must not be abused to start services, stop services, or run any other commands that will modify the currently running system.

8.6.13.3. @mode mode

Set default permission for all subsequently extracted files to mode. Format is the same as that used by chmod(1). Use without an arg to set back to default permissions (mode of the file while being packed).

Important:

This must be a numeric mode, like 644, 4755, or 600. It cannot be a relative mode like u+s.

8.6.13.4. @owner user

Set default ownership for all subsequent files to user. Use without an argument to set back to default ownership (root).

8.6.13.5. @group group

Set default group ownership for all subsequent files to group. Use without an arg to set back to default group ownership (wheel).

8.6.13.6. @comment string

This line is ignored when packing.

8.6.13.7. @dir directory

Declare directory name. By default, directories created under PREFIX by a package installation are automatically removed. Use this when an empty directory under PREFIX needs to be created, or when the directory needs to have non default owner, group, or mode. Directories outside of PREFIX need to be registered. For example, /var/db/${PORTNAME} needs to have a @dir entry whereas ${PREFIX}/share/${PORTNAME} does not if it contains files or uses the default owner, group, and mode.

8.6.13.8. @exec command, @unexec command (Deprecated)

Execute command as part of the installation or deinstallation process. Please use Section 8.6.13.2, “@preexec command, @postexec command, @preunexec command, @postunexec command instead.

8.6.13.9. @dirrm directory (Deprecated)

Declare directory name to be deleted at deinstall time. By default, directories created under PREFIX by a package installation are deleted when the package is deinstalled.

8.6.13.10. @dirrmtry directory (Deprecated)

Declare directory name to be removed, as for @dirrm, but does not issue a warning if the directory cannot be removed.

8.6.14. Creating New Keywords

Package list files can be extended by keywords that are defined in the ${PORTSDIR}/Keywords directory. The settings for each keyword are stored in a UCL file named keyword.ucl. The file must contain at least one of these sections:

  • attributes

  • action

  • pre-install

  • post-install

  • pre-deinstall

  • post-deinstall

  • pre-upgrade

  • post-upgrade

8.6.14.1. attributes

Changes the owner, group, or mode used by the keyword. Contains an associative array where the possible keys are owner, group, and mode. The values are, respectively, a user name, a group name, and a file mode. For example:

attributes: { owner: "games", group: "games", mode: 0555 }

8.6.14.2. action

Defines what happens to the keyword's parameter. Contains an array where the possible values are:

setprefix

Set the prefix for the next plist entries.

dir

Register a directory to be created on install and removed on deinstall.

dirrm

Register a directory to be deleted on deinstall. Deprecated.

dirrmtry

Register a directory to try and deleted on deinstall. Deprecated.

file

Register a file.

setmode

Set the mode for the next plist entries.

setowner

Set the owner for the next plist entries.

setgroup

Set the group for the next plist entries.

comment

Does not do anything, equivalent to not entering an action section.

ignore_next

Ignore the next entry in the plist.

8.6.14.3. arguments

If set to true, adds argument handling, splitting the whole line, %@, into numbered arguments, %1, %2, and so on. For example, for this line:

@foo some.content other.content

%1 and %2 will contain:

some.content
other.content

It also affects how the action entry works. When there is more than one argument, the argument number must be specified. For example:

actions: [file(1)]

8.6.14.4. pre-install, post-install, pre-deinstall, post-deinstall, pre-upgrade, post-upgrade

These keywords contains a sh(1) script to be executed before or after installation, deinstallation, or upgrade of the package. In addition to the usual @exec %foo placeholders described in Section 8.6.13.2, “@preexec command, @postexec command, @preunexec command, @postunexec command, there is a new one, %@, which represents the argument of the keyword.

8.6.14.5. Custom Keyword Examples

Example 8.2. Example of a @dirrmtryecho Keyword

This keyword does two things, it adds a @dirrmtry directory line to the packing list, and echoes the fact that the directory is removed when deinstalling the package.

actions: [dirrmtry]
post-deinstall: <<EOD
  echo "Directory %D/%@ removed."
EOD

Example 8.3. Real Life Example, How @sample is Implemented

This keyword does three things. It adds the first filename passed as an argument to @sample to the packing list, it adds to the post-install script instructions to copy the sample to the actual configuration file if it does not already exist, and it adds to the post-deinstall instructions to remove the configuration file if it has not been modified.

actions: [file(1)]
arguments: true
post-install: <<EOD
  case "%1" in
  /*) sample_file="%1" ;;
  *) sample_file="%D/%1" ;;
  esac
  target_file="${sample_file%.sample}"
  set -- %@
  if [ $# -eq 2 ]; then
      target_file=${2}
  fi
  case "${target_file}" in
  /*) target_file="${target_file}" ;;
  *) target_file="%D/${target_file}" ;;
  esac
  if ! [ -f "${target_file}" ]; then
    /bin/cp -p "${sample_file}" "${target_file}" && \
      /bin/chmod u+w "${target_file}"
  fi
EOD
pre-deinstall: <<EOD
  case "%1" in
  /*) sample_file="%1" ;;
  *) sample_file="%D/%1" ;;
  esac
  target_file="${sample_file%.sample}"
  set -- %@
  if [ $# -eq 2 ]; then
      set -- %@
      target_file=${2}
  fi
  case "${target_file}" in
  /*) target_file="${target_file}" ;;
  *) target_file="%D/${target_file}" ;;
  esac
  if cmp -s "${target_file}" "${sample_file}"; then
    rm -f "${target_file}"
  else
    echo "You may need to manually remove ${target_file} if it is no longer needed."
  fi
EOD

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.