Do use the macros provided in
bsd.port.mk
to ensure correct modes of
files in your own *-install
targets.
Ownership should be set directly in the
pkg-plist
file with the corresponding
entries, such as @owner
and owner
@group
. Note that these
operators work until being overridden, or until the end of
group
pkg-plist
, so do not forget to reset them
afterwards they are not needed any more. 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:
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, there is a need to install a big number of
files, preserving their hierarchical organization, i.e.,
copying over a whole directory tree from
WRKSRC
to a target directory under
PREFIX
. Note that
PREFIX
, EXAMPLESDIR
,
DATADIR
, and such have to be always
prepended with STAGEDIR
in order 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
.
The second macro, PREFIX
/binCOPYTREE_SHARE
, does
not set executable permissions on files, and is therefore
suitable for installing files under
target.PREFIX
/share
This example will install the contents of
examples
directory in the vendor
distfile to the proper examples location of your
port.
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.
Note that these macros does not add the installed files
to pkg-plist
. You still need to list
them. For optional documentation
(PORTDOCS
, see Section 5.15.4, “Install Additional Documentation”) and examples
(PORTEXAMPLES
), the
%%PORTDOCS%%
or
%%PORTEXAMPLES%%
prefixes have to 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
.
This can be done, like the previous item, in the
PREFIX
/share/docpost-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 has to only be associated when the installed files are
large enough to cause significant I/O overhead.
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
if possible.
That is,
PREFIX
share/doc/
will be substituted for PORTNAME
%%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:
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:
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
as a
destination for their files.PREFIX
/news
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>.