NOTE: See the BSP Developer's Guide for important information on BSP distribution standards. Acceptable makefile customization is limited by the guidelines described in that section.

Most of the makefile macros fall into two categories: macros intended for use by the BSP developer, and macros intended for use by the end user. When building a VxWorks image, the needs of these two audiences differ considerably. Maintaining two separate compile-time macro sets lets the make separate the BSP-specific requirements from user-specific requirements.

Macros containing EXTRA in their name are intended for use by the BSP developer to specify additional object modules that must be compiled and linked with all VxWorks images.

Macros containing ADDED in their name are intended for use by the end-user on the make command line. This allows for easy compile time options to be specified by the user, without having to repeat any BSP-specific options in the same macro declaration.

You can add an object module to VxWorks by adding its name to the skeletal makefile. To include fooLib.o, for example, add it to the MACH_EXTRA definition in Makefile. This macro causes the linker to link it into the output object.

Finally, regenerate VxWorks with make. The module will now be included in all future VxWorks builds. If necessary, the module will be made from fooLib.c or fooLib.s using the .c.o or .s.o makefile rule.

MACH_EXTRA can be used for drivers that are not included in the VxWorks driver library. BSPs do not usually include source code for Ethernet and SCSI device drivers; thus, when preparing your system for distribution, omit the driver source file and change the object file's name from .o to .obj (update the makefiles, too). Now the end user can build VxWorks without the driver source, and rm *.o will not inadvertently remove the driver's object file.

The LIB_EXTRA makefile variable makes it possible to include library archives in the VxWorks build without altering the standard VxWorks archive or the driver library archive. Define LIB_EXTRA in Makefile to indicate the location of the extra libraries.

The libraries specified by LIB_EXTRA are provided to the link editor when building any VxWorks or boot ROM images. This is useful for third-party developers who want to supply end users with network or SCSI drivers, or other modules in object form, and find that the MACH_EXTRA mechanism described earlier in this chapter does not suit their needs.

The extra libraries are searched first, before Wind River libraries, and any references to VxWorks symbols are resolved properly.

The makefile variable EXTRA_INCLUDE is available for specifying additional header directory locations. This is useful when the user or BSP provider has a separate directory of header files to be used in addition to the normal directory locations.

EXTRA_INCLUDE = -I../myHdrs

The normal order of directory searching for #include directives is:

$(INCLUDE_CC) (reserved for compiler specific uses)

$(EXTRA_INCLUDE)

.

$(CONFIG_ALL)

$(TGT_DIR)/h

$(TGT_DIR)/src/config

$(TGT_DIR)/src/drv

The makefile variable EXTRA_DEFINE is available for specifying compile time macros required for building a specific BSP. In the following example the macro BRD_TYPE is given the value MB934. This macro is defined on the command line for all compiler operations.

EXTRA_DEFINE = -DBRD_TYPE=MB934

By default a minimum set of macro names are defined on the compiler command line. This is primarily used to pass the same memory addresses used in both the compiling and linking operations.

These default macro definitions include:

-DCPU=$(CPU)

Sometimes it is inconvenient to modify config.h to control VxWorks configuration. ADDED_CFLAGS is useful for defining macros without modifying any source code.

Consider the hypothetical Acme XYZ-75 BSP that supports two hardware configurations. The XYZ-75 has a daughter board interface, and in this interface either a Galaxy-A or a Galaxy-B module is installed. The drivers for the modules are found in the directory src/drv/multi.

The macro GALAXY_C_FILE determines which driver to include at compile-time. The file named by GALAXY_C_FILE is #included by sysLib.c.

The default configuration (Galaxy-A module installed) is established in config.h:

#ifndef GALAXY_C_FILE

#define GALAXY_C_FILE "multi/acmeGalaxyA.c"

#endif /* GALAXY_C_FILE */

When make is called normally, VxWorks supports the XYZ-75 with the Galaxy-A module installed. To override the default and build VxWorks for the XYZ-75/Galaxy-B configuration, do the following:

% make ADDED_CFLAGS='-DGALAXY_C_FILE=\"multi\/acmeGalaxy02.c\"' vxWorks

For ease of use, you can encapsulate the lengthy command line within a shell script or independent makefile.

To ensure that a module is incorporated in vxWorks, remove the module's object file and vxWorks before running make.

The ADDED_MODULES makefile variable makes it possible to add modules to VxWorks without modifying any source code.

While MACH_EXTRA requires the makefile to be modified, ADDED_MODULES allows one or more extra modules to be specified on the make command line. For example, to build VxWorks with the BSP VTS support library included, copy pkLib.c to the target directory and enter:

% make ADDED_MODULES=pkLib.o vxWorks

One disadvantage of using ADDED_MODULES is that makefile dependencies are not generated for the module(s). In the above example, if pkLib.c, pkLib.o, and vxWorks already exist, you must remove pkLib.o and vxWorks before running make to force the latest pkLib.c to be incorporated into vxWorks.

Under extreme circumstances, the files in the config/all directory might not be flexible enough to support a complex BSP. In this case, copy all the config/all files to the BSP directory (config/bspname) and edit the files as necessary. Then redefine the CONFIG_ALL makefile variable in Makefile to direct the build to the altered files. To do this, define CONFIG_ALL to equal the absolute path to the BSP's config/bspname directory as shown in the following example:

CONFIG_ALL            =    $(TGT_DIR)/config/bspname/

The procedure described above works well if you must modify all or nearly all the files in config/all. However, if you know that only one or two files from config/all need modification, you can copy just those files to the BSP's config/bspname directory. Then, instead of changing the CONFIG_ALL makefile macro, change one or more of the following (which ever are appropriate).

USRCONFIG

The path to an alternate config/all/usrConfig.c file.

BOOTCONFIG

The path to an alternate config/all/bootConfig.c file.

BOOTINIT

The path to an alternate config/all/bootInit.c file.

DATASEGPAD

The path to an alternate config/all/dataSegPad.s file.

CONFIG_ALL_H

The path to an alternate config/all/configAll.h file.

TGT_DIR

The path to the target directory tree, normally $(WIND_BASE)/target.

COMPRESS

The path to the host's compression program. This is the program that compresses an executable image. The binary image is input through stdin, and the output is placed on the stdout device. This macro can contain command-line flags for the program if necessary.

BINHEX

The path to the host's object-format-to-hex program. This program is called using HEX_FLAGS as command line flags. See target/h/make/rules.bsp for actual calling sequence.

HEX_FLAGS

Command line flags for the $(BINHEX) program.

BOOT_EXTRA

Additional modules to be linked with compressed ROM images. These modules are not linked with uncompressed or ROM-resident images, just compressed images.

EXTRA_DOC_FLAGS

Additional preprocessor flags for making man pages. The default documentation flags are -DDOC -DINCLUDE_SCSI. If EXTRA_DOC_FLAGS is defined, these flags are passed to the man page generation routines in addition to the default flags.