Do use the macros provided in bsd.port.mk
to ensure correct modes and ownership of files in your own
*-install
targets.
INSTALL_PROGRAM
is a command to install
binary executables.
INSTALL_SCRIPT
is a command to install
executable scripts.
INSTALL_KLD
is a command to install
kernel loadable modules. Some architectures don't like it when
the modules are stripped, therefor 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).
If you need to strip a file, but do not wish to use the
INSTALL_PROGRAM
macro,
${STRIP_CMD}
will strip your program. This is
typically done within the post-install
target. For example:
post-install: ${STRIP_CMD} ${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, there is a need to install a big number of files,
preserving their hierarchical organization, ie. copying over a whole
directory tree from WRKSRC
to a target directory
under PREFIX
.
Two macros exists for this situation. The advantage of using
these macros instead of cp
is that they guarantee
proper file ownership and permissions on target files. 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} ${EXAMPLESDIR} (cd ${WRKSRC}/examples/ && ${COPYTREE_SHARE} \* ${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} ${DATADIR}/summer (cd ${WRKSRC}/temperatures/ && ${COPYTREE_SHARE} "June July August" ${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} ${EXAMPLESDIR} (cd ${WRKSRC}/examples/ && \ ${COPYTREE_SHARE} \* ${EXAMPLESDIR} "! -name Makefile")
Note that these macros does not add the installed files to
pkg-plist
. You still need to list them.
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
.
Make the installation dependent on the variable
NOPORTDOCS
so that users can disable it in
/etc/make.conf
, like this:
post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR} .endif
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
.
NOPORTDOCS
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 NOPORTDATA
and
NOPORTEXAMPLES
, 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 NOPORTDOCS
is defined then files and directories listed in
PORTDOCS
would not be installed and neither
would be 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>.