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_LIB is a command to install shared libraries.
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). 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} ${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. 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} ${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.
Note: 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/*
Note: 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.