NAME

makeplist —

generate a pkg-plist file for ports(7)

SYNOPSIS

makeplist -h

makeplist [-lOq] [-I make-vars] [-o plist-file] [port-name]

DESCRIPTION

The makeplist script is a tool for ports(7) maintainers and committers, to generate a pkg-plist file.

ARGUMENTS

The following arguments are accepted:

port-name: The name or origin of the port to generate a pkg-plist for. This may also be the directory the port can be found in.
If omitted the current directory is used.

OPTIONS

The following options are support:

-h --help

Displays the available options.

-I --ignore-vars make-vars

Takes a comma separated list of make variables to ignore when postprocessing the generated plist. The following variables may be specified:

DESKTOP_ENTRIES
PLIST_FILES
PLIST_SUB
PORTDATA
PORTDOCS
PORTEXAMPLES
USE_RC_SUBR

-l --licenses

Usually makeplist runs with with the ports(7) license auditing framework disabled. This option turns it on.

This flag cannot be combined with -q.

-O --orig

Includes files with the .orig suffix in the plist.

-o --outfile plist-file

Sets the output file for the generated plist. Defaults to the ports pkg-plist with a .makeplist suffix appended.

-q --quiet

Suppress build/stage output.

This flag cannot be combined with -l.

IMPLEMENTATION NOTES

In order to make effective use of makeplist some knowledge about it is required.

The exponential growth of possible combinations of options puts a hard limit on automated plist generation. The makeplist script does not support cases where files are only installed if a combination of options is given.

The tool is built around the assumption that options do not affect each other. The following subsections describe what exactly is supported and workarounds for common cases where this is not the case.

Configurations

The core idea of makeplist is to run “make stage” and create a list of the files in the staging area. This functionality is provided by the ports(7) when running “make makeplist”.

In order to identify all the files installed by each option staging is performed for every option. The trivial approach of staging with one option at a time is not possible when OPTIONS_SINGLE or OPTIONS_MULTI groups are defined, because every such group must be represented in all configurations. Even so under the assumption that options do not affect each other n + 1 stage cycles suffice to identify all files provided by all options (n being the number of options).

Staging

Usually makeplist calls “

make
  clean stage

” for each configuration. One exception to this rule is when ports define NO_BUILD in which case “make restage” is called. This means that the extract target is only performed during the first stage cycle. And it breaks if extraction is affected by options.

Build Failure

In case one or more configurations fail an error message with the build options and the name of the log file will be printed after the plist is created. Only logs of failed builds are kept. The logs are created under /tmp and compressed using gzip(1). They can be viewed with the command “gunzip -c logfile | less -R”.

Plist Accumulation

After every stage cycle all files installed into the STAGEDIR are collected for later assembly of the plist.

Certain files are not included, these files are selected using the following ports(7) variables:

DESKTOP_ENTRIES: Macro for creating/installing desktop icons.
USE_RC_SUBR: Macro for creating/installing rc(8) scripts.
PLIST_FILES: A list of files automatically added to the plist.
PORTDOCS, PORTEXAMPLES, PORTDATA: Lists of files / glob patterns in DOCSDIR, EXAMPLESDIR and DATADIR.

This can be used to deal with cases that violate the independent option principle. E.g. if there is a number of options to switch certain modules on/off and a DOCS option which causes each of these modules to generate some documentation, setting PORTDOCS=* keeps everything in DOCSDIR out of the plist.

Plist Creation

Files in the generated plist are sorted alphabetically by sort(1) -n.

Common files installed independent of the given options are listed first, followed by the option specific files. Option specific files appear in alphabetical order of the options. The options DOCS and EXAMPLES are implicitly replaced with PORTDOCS and PORTEXAMPLES. Files with a .sample suffix are automatically prefixed with “@sample ”.

In the next stage of plist creation the reverse of the substitutions defined in PLIST_SUB is applied. The substitutions are sorted by size and applied largest first. Empty substitutions, PREFIX substitutions and substitutions starting with an @ character are discarded. Lines starting with %%DOCSDIR%% are prefixed with %%PORTDOCS%% and %%EXAMPLESDIR%% with %%PORTEXAMPLES%%.

In the final stage of plist creation makeplist attempts to transplant the @ keywords (see pkg-create(8)) from the old plist to the new one. The script makes an effort to place them in the same context. The prefix “@sample ” is stripped from all files that appear in the old plist without it.

EXAMPLES

The current directory is a port to create a pkg-plist for:

% makeplist

The quiet mode suppresses the build output:

% makeplist -q

Instead of creating the file pkg-plist.makeplist overwrite the pkg-plist file:

% makeplist -o pkg-plist

To create a pkg-plist as an unprivileged user run:

% env
  WRKDIRPREFIX='/var/tmp/obj.${USER}' makeplist -o ~/myplist

The WRKDIRPREFIX can be set in the make.conf(5) file:

WRKDIRPREFIX?=/var/tmp/obj.${USER}

There is no need to cd into a ports directory:

% makeplist
  games/ioquake3-devel

The ports tree does not have to be in /usr/ports:

% env PORTSDIR=$HOME/ports.svn
  makeplist games/ioquake3-devel

Or just use cd:

% cd ~/ports.svn/games/ioquake3-devel
  && makeplist

A port listing all its files in PLIST_FILES results in an empty plist. PLIST_FILES can be ignored:

% makeplist -I
  PLIST_FILES

HISTORY

The makeplist script first appeared in the bsda2-0.2.0 release.

AUTHORS

Dominic Fandrey <freebsd@k4m1.org>