FreeBSD Porter's Handbook
Prev | Chapter 5 Configuring the Makefile | Next

# 5.15 Installing Files

## 5.15.1 `INSTALL_*` Macros

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 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.

## 5.15.2 Stripping Binaries and Shared Libraries

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.

## 5.15.3 Installing a Whole Tree of Files

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`.

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} ${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.

## 5.15.4 Install Additional Documentation

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 `DOCS` option so that users can disable it in `/etc/make.conf`, like this:

    post-install:
    .if ${PORT_OPTIONS:MDOCS}
    	${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: 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/*

> 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`.

## 5.15.5 Subdirectories Under `PREFIX`

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.

Prev | Home | Next
Conflict Handling | Up | Special Considerations

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.