8.5 Role-File include.mk

8.5.1 Purpose

The purpose of the include role is to install all .h and .i under INCSRC_DIR into the local install-tree or into the drops install-tree. This role facilitates two goals with respect to managing include-files:

1. The path where the include-files are found is entirely defined by the package name and the target system of the include-files.
2. Once written, the make file need not be modified, even when new include files are added or old include files are removed from the package.

The target system of an include file is determined by putting it into a specific subdirectory. The role-file will then install it accordingly. By default, INCSRC_DIR points is set to the source directory. To install generated header files, set INCSRC_DIR to OBJ_DIR. There is currently no mechanism to exclude header files.

When generating header files, add them to the headers target (which all depends on).

The following table defines the subdirectories depending on the target systems.

if the include-file is designated for ...	put it into ... or subdirectories thereof
any system	./
CPU architecture <arch>	ARCH-<arch>/
CPU architecture <arch> and L4API <api>	ARCH-<arch>/L4API-<api>/

The installation paths are determined according to the following table:

Designated system	Local and global installation paths
no system dependency	$(L4DIR)/include/l4/$(PKGNAME)/, $(DROPS_STDDIR)/include/l4/$(PKGNAME)/
CPU architecture <arch>	$(L4DIR)/include/<arch>/l4/$(PKGNAME)/, $(DROPS_STDDIR)/include/<arch>/l4/$(PKGNAME)/
CPU architecture <arch> and L4API <api>	$(L4DIR)/include/<arch>/<api>/l4/$(PKGNAME)/, $(DROPS_STDDIR)/include/<arch>/<api>/l4/$(PKGNAME)

8.5.2 Make-Targets

all::

Phony target. Install all header-files found in this directory-tree into the local install-tree.

install::

Phony target. Install all header-files found in this directory-tree into the global install-tree.

8.5.3 Optional Parameters

INSTALLDIR_INC	The directory in the global install tree to install an include to. Default: $(DROPS_STDDIR)/include/
INSTALLDIR_INC_LOCAL	The directory in the local install tree to install an include to. Default: $(L4DIR)/include/
INSTALL_INC_PREFIX	The prefix of installed files. Think twice before changing this, as it pollutes the name space of include files. Default: l4/$(PKGNAME)
PKGNAME	The name of the package. Default value is determined from the name of the package directory.
TARGET	The list of file to install on all:: or install::. Default: all *.h-files found in the subdirectory tree.

8.5.4 Example

PKGDIR = ..
L4DIR ?= \$(PKGDIR)/../..
include \$(L4DIR)/mk/include.mk

8.5.5 How to use the Include Role

Note, that all include files found in the subdirectory tree are subject to installation.

Generally, you would insert an include file with no system dependency, hence directly into the include/ directory. Admittedly, this may result in a wrong compilation if you use this include file with a system target it was not intended for. But, as no library is available for that system target, the linker should catch this wrong package use later.

If you realize later that you need different versions of the include file to support different systems, you can move the include files into appropriate subdirectories. The dependencies of the make system ensure that no old include files will be used: Files in system-dependent subdirectories will be found first when the preprocessor is looking for include files. Moreover, the symbolic links in the local installation directory $(L4DIR)/include/ will become invalid, so that an undesired use of them is avoided safely.