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
owner
and @group
group
. These
operators work until being overridden, or until the end of
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.
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.
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 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
Use the file(1) command on the installed executable
to check whether the binary is stripped or not. If it does
not say not stripped
, it is stripped.
Additionally, strip(1) will not strip a previously
stripped program; it will instead 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 varialbes 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.
You can also use the pkg-message
file to display messages upon installation. See
the section on using
pkg-message
for details. The
pkg-message
file 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>.