Use the macros provided in
bsd.port.mk
to ensure correct modes of
files in the port's *-install
targets. Set ownership directly in
pkg-plist
with the corresponding entries,
such as
@owner
and
owner
@group
.
These operators work until being overridden, or until the end
of group
pkg-plist
, so do not forget to reset
them after they are no longer needed. The default ownership
is root:wheel
.
INSTALL_PROGRAM
is a command to
install binary executables.
INSTALL_SCRIPT
is a command to
install executable scripts.
INSTALL_LIB
is a command to install
shared libraries (but not static libraries).
INSTALL_KLD
is a command to
install kernel loadable modules. Some architectures
do not like having the modules stripped, so
use this command instead of
INSTALL_PROGRAM
.
INSTALL_DATA
is a command to
install sharable data, including static libraries.
INSTALL_MAN
is a command to
install manpages and other documentation (it does not
compress anything).
These are basically the install
command with all the appropriate flags.
Do not use INSTALL_LIB
to install
static libraries, because stripping them render them
useless. Use INSTALL_DATA
instead.
Do not strip binaries manually unless you have to. All
binaries should be stripped, but the
INSTALL_PROGRAM
macro will install and
strip a binary at the same time (see the next section). The
INSTALL_LIB
macro does the same thing to
shared libraries.
If you need to strip a file, but wish to use neither
INSTALL_PROGRAM
nor
INSTALL_LIB
macros,
${STRIP_CMD}
will strip your program or
shared library. This is typically done within the
post-install
target. For
example:
post-install: ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl
When multiple files need to be stripped:
post-install: .for l in geometry media body track world ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0 .endfor
Use file(1) on a file to determine if it has been
stripped. Binaries are reported by file(1) as
stripped
, or
not stripped
. Additionally, strip(1)
will detect programs that have already been stripped and exit
cleanly.
Sometimes, a large number of files must be installed while
preserving their hierarchical organization. For example,
copying over a whole directory tree from
WRKSRC
to a target directory under
PREFIX
. Note that
PREFIX
, EXAMPLESDIR
,
DATADIR
, and other path variables must
always be prepended with STAGEDIR
to
respect staging (see Section 6.1, “Staging”).
Two macros exist for this situation. The advantage of
using these macros instead of cp
is that
they guarantee proper file ownership and permissions on target
files. The first macro, COPYTREE_BIN
, will
set all the installed files to be executable, thus being
suitable for installing into PREFIX/bin
.
The second macro, COPYTREE_SHARE
, does not
set executable permissions on files, and is therefore suitable
for installing files under PREFIX/share
target.
post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})
This example will install the contents of
examples
directory in the vendor distfile
to the proper examples location of your port.
post-install: ${MKDIR} ${STAGEDIR}${DATADIR}/summer (cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)
And this example will install the data of summer months to
the summer
subdirectory of a
DATADIR
.
Additional find
arguments can be
passed via the third argument to the
COPYTREE_*
macros. For example, to install
all files from the first example except Makefiles, one can use
the following command.
post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && \ ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")
These macros do not add the installed files to
pkg-plist
. They must be added manually.
For optional documentation (PORTDOCS
, see
Section 5.15.4, “Install Additional Documentation”) and examples
(PORTEXAMPLES
), the
%%PORTDOCS%%
or
%%PORTEXAMPLES%%
prefixes must be prepended
in pkg-plist
.
If your software has some documentation other than the
standard man and info pages that you think is useful for the
user, install it under PREFIX/share/doc
.
This can be done, like the previous item, in the
post-install
target.
Create a new directory for your port. The directory name
should reflect what the port is. This usually means
PORTNAME
. However, if you think the user
might want different versions of the port to be installed at
the same time, you can use the whole
PKGNAME
.
Since only the files listed in
pkg-plist
are installed, it is safe to
always install documentation to STAGEDIR
(see Section 6.1, “Staging”). Hence .if
blocks are only needed when the installed files are large
enough to cause significant I/O overhead.
post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}
Here are some handy variables and how they are expanded by
default when used in the Makefile
:
DATADIR
gets expanded to
PREFIX/share/PORTNAME
.
DATADIR_REL
gets expanded to
share/PORTNAME
.
DOCSDIR
gets expanded to
PREFIX/share/doc/PORTNAME
.
DOCSDIR_REL
gets expanded to
share/doc/PORTNAME
.
EXAMPLESDIR
gets expanded to
PREFIX/share/examples/PORTNAME
.
EXAMPLESDIR_REL
gets expanded to
share/examples/PORTNAME
.
The DOCS
option only controls
additional documentation installed in
DOCSDIR
. It does not apply to standard
man pages and info pages. Things installed in
DATADIR
and
EXAMPLESDIR
are controlled by
DATA
and EXAMPLES
options, respectively.
These variables are exported to
PLIST_SUB
. Their values will appear there
as pathnames relative to PREFIX
if
possible. That is, share/doc/PORTNAME
will be substituted for %%DOCSDIR%%
in the
packing list by default, and so on. (See more on
pkg-plist
substitution
here.)
All conditionally installed documentation files and
directories should be included in
pkg-plist
with the
%%PORTDOCS%%
prefix, for example:
%%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT %%PORTDOCS%%@dirrm %%DOCSDIR%%
As an alternative to enumerating the documentation files
in pkg-plist
, a port can set the variable
PORTDOCS
to a list of file names and shell
glob patterns to add to the final packing list. The names
will be relative to DOCSDIR
. Therefore, a
port that utilizes PORTDOCS
and uses a
non-default location for its documentation should set
DOCSDIR
accordingly. If a directory is
listed in PORTDOCS
or matched by a glob
pattern from this variable, the entire subtree of contained
files and directories will be registered in the final packing
list. If the DOCS
option has been unset
then files and directories listed in
PORTDOCS
would not be installed or added to
port packing list. Installing the documentation at
PORTDOCS
as shown above remains up to the
port itself. A typical example of utilizing
PORTDOCS
looks as follows:
PORTDOCS= README.* ChangeLog docs/*
The equivalents of PORTDOCS
for files
installed under DATADIR
and
EXAMPLESDIR
are
PORTDATA
and
PORTEXAMPLES
, respectively.
The contents of pkg-message
are
displayed upon installation. See
the section on using
pkg-message
for details.
pkg-message
does not need to be added
to pkg-plist
.
Try to let the port put things in the right subdirectories
of PREFIX
. Some ports lump everything and
put it in the subdirectory with the port's name, which is
incorrect. Also, many ports put everything except binaries,
header files and manual pages in a subdirectory of
lib
, which does not work well with the
BSD paradigm. Many of the files should be moved to one of the
following: etc
(setup/configuration
files), libexec
(executables started
internally), sbin
(executables for
superusers/managers), info
(documentation
for info browser) or share
(architecture
independent files). See hier(7) for details; the rules
governing /usr
pretty much apply to
/usr/local
too. The exception are ports
dealing with USENET “news”. They may use
PREFIX/news
as a destination for their
files.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/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>.