Project

General

Profile

Introduction

The frontend.mk include file was developed to improve and standardize the build environment for front-end programmers. Wind Rivers has provided a library of make include files, but it takes discipline to use them effectively and, with each major release of VxWorks, they change enough that using them becomes a hassle. frontend.mk provides a consistent use of these files, as well as hiding their gory details.

frontend.mk is also used by the front-end group to build the various modules and libraries that everyone uses. We call these projects, "products". frontend.mk iterates through VxWorks versions and BSP targets to build each version used by our front-end community. It uses the stage and release commands to place these generated targets into the proper download areas. If you have front-end source code that targets multiple BSPs and/or versions of VxWorks, you can use this mechanism, too.

The Front-end Environment

A majority of our front-end systems use VME-based hardware running some version of VxWorks. Currently, our tools for VxWorks development are found on nova.fnal.gov. To use them, you need an account on nova which needs to be a member of the bdmicrop group.

We have tools installed to develop for VxWorks 5.4, 5.5, 61., 6.4, and 6.7 for several VME processor boards. Due to historical short-sightedness, our BSP targets for VxWorks 5.4 are based on the processor type (MC68020, MC68040, PPC603, and PPC604.) All other targeted versions of VxWorks use the actual BSP designation.

NOTE: VxWorks 5.4, 5.5, and 6.1 are being phased out. Some of these commands may print a warning, reminding you that we will eventually be dropping support for the associated environment.

Content outline (to be written):

  • Mention where boot.bin files are and point to documentation
  • boot machine is chablis
    • need to edit .rhosts
    • discuss directory layout
    • document where "stable" kernels are located
  • describe release cycle
    • frontend.mk, release, and stage pull it all together

Setting Up the Environment

Whether you're writing front-end software or maintaining a public library, you'll need a default development environment. For front-end programmers, this will be the target environment that supports your hardware. For "product" development (like MOOC or ACNET modules), you'll use the environment that supports the hardware used to test the product (eventually you'll test and release the software for all targets.)

On nova.fnal.gov, we've created a set of commands that prepare your login session for developing software targeting a version of VxWorks using a specific BSP. You may type alias at the shell prompt to see the commands. The format is as follows:

env##_BSP

where:  ##   refers to the version of VxWorks and can be 54, 55, 61, 64, or 67.
        BSP  refers to the target hardware and can be MC68020, MC68040, PPC603,
             or PPC604 for VxWorks 5.4. For all other VxWorks versions, the BSP
             can be mv2303, mv2400, mv2401, mv2434, or mv5500.

The commands define environment variables that are necessary for the Wind Rivers tools to function. They also define environment variables used by frontend.mk to build targets. These variables can be used in custom targets you define in your makefile.

PRODUCTS_FEDIR

This symbol points to the base, install directory for front-end projects. Each programmer should make a subdirectory off this base for their front-end's specific files. For instance, the CAMAC front-ends have their startup scripts installed in ${PRODUCTS_FEDIR}/camac. This symbol is the same value under every version of VxWorks and BSP. If your makefile needs to install files in your project's directory, you can use this symbol.

PRODUCTS_INCDIR

This symbol points to the base directory containing header files used by the current VxWorks/BSP environment. frontend.mk automatically adds a -I option, pointing to this location, on compile commands so you don't have to. If your makefile defines the PRODUCT symbol, frontend.mk uses this as the base directory to install header files.

PRODUCTS_LIBDIR

This symbol points to the base directory containing static libraries used by the current VxWorks/BSP environment. frontend.mk automatically adds a -L option on link commands so you don't have to. If your makefile defines the PRODUCT symbol, frontend.mk uses this as the directory to install static libraries.

PRODUCTS_MODDIR

This symbol points to the base directory containing module files usable by the current VxWorks/BSP environment. If your makefile defines the PRODUCT symbol, frontend.mk uses this as the directory to install loadable module files.

Using frontend.mk

Add the following line to your Makefile.

include ${PRODUCTS_INCDIR}/frontend.mk

frontend.mk defines make targets, variables, and macros that you can use in the rest of your Makefile. You can configure the behavior of frontend.mk by defining variables before including it. These variables are shown below.

File Types

We use the following file name extensions when building targets:

.a

This file type represents a static library. The ${make-lib} macro is used to build them. These targets are typically added to the LIB_TARGETS symbol so they'll get installed in the PRODUCTS_LIBDIR directory.

.o

This file type represent an object file and is considered an intermediate file by our build environment. Even though object files generated from C code can be loaded by VxWorks, we prefer consistency and recommend that .o files be only used to build .a, .out, or .vxo files. You don't normally specify .o as targets because the implicit rules of frontend.mk know how to build them based on what source files are available.

.out

This file type represents a loadable VxWorks module. The ${make-mod} macro is used to build them. These targets are added to the MOD_TARGETS symbol so they'll get installed in the PRODUCTS_MODDIR directory. These types of files are .o files that have gone through one addition phase of processing so global C++ constructors will be invoked when the module is loaded in VxWorks. Because of this extra step, .out files can no longer be safely linked with other .o files (hence the reason we gave them a different extension.)

.vxo

This file type represents a VxWorks real-time process. The ${make-vxe} is used to build real-time processes. These targets are added to the VXE_TARGETS symbol and get installed in the PRODUCTS_VXEDIR directory. We don't fully support this file target yet.

Makefile Variables

Defining these variables, before including frontend.mk, will modify the build environment to support your project's needs.

ADDED_C++FLAGS

This symbol is used to specify additional compiler options for every C++ file in your project. Since your current build environment will already have the correct, default compiler options, this variable should only be used to add nonstandard options required by your project.

ADDED_CFLAGS

This symbol is used to specify additional compiler options for every C file in your project. Since your current build environment will already have the correct, default compiler options, this variable should only be used to add nonstandard options required by your project.

ADDED_ vv _ bsp _C++FLAGS

This symbol specifies additional C++ compiler options to be used when building a particular target/BSP combination. vv is the two-digit, VxWorks version number and bsp is the BSP target.

ADDED_ vv _ bsp _CFLAGS

This symbol specifies additional C compiler options to be used when building a particular target/BSP combination. vv is the two-digit, VxWorks version number and bsp is the BSP target.

AS_SUBDIR

If defined (and if SUBDIR_NAME isn't defined), the project will get installed in a subdirectory of the default, install location. The name of the subdirectory is determined by the CVS project name, if available, or the base name of the working directory. To have better, consistent results, SUBDIR_NAME should be used instead of this variable.

C++FLAGS_ obj

This symbol form can be used to specify C++ compiler option(s) targeted for a specific module. For instance, if you want to shut off warnings for unused variable only for example.o, you can do this: "C++FLAGS_example.o = -Wno-unused".

CFLAGS_ obj

This symbol form can be used to specify C compiler option(s) targeted for a specific module. For instance, if you want to shut off warnings for unused variable only for example.o, you can do this: "CFLAGS_example.o = -Wno-unused".

CLEAN_TARGETS

Specifies additional files which should be deleted when the clean-all make target is used.

HEADER_TARGETS

If defined, it should be a list of file names -- separated by spaces -- which should get installed in $PRODUCTS_INCDIR. These are typically .h files.

HEADER_ bsp _TARGETS

Similar to HEADER_TARGETS except these files will only be installed when the specified BSP is the target.

HEADER_ vv _TARGETS

Similar to HEADER_TARGETS except these files will only be installed when the specified version of VxWorks is the target.

HEADER_ vv _ bsp _TARGETS

Similar to HEADER_TARGETS except these files will only be installed when the specified BSP and version of VxWorks is the target.

LIB_TARGETS

If defined, it should be a list of file names -- separated by spaces -- which should get installed in $PRODUCTS_LIBDIR. These are typically static libraries with a .a suffix.

LIB_ bsp _TARGETS

Similar to LIB_TARGETS except these files are only built and installed when the current build environment targets the specified BSP.

LIB_ vv _TARGETS

Similar to LIB_TARGETS except these files are only built and installed when the current build environment targets the specified version of VxWorks.

LIB_ vv _ bsp _TARGETS

Similar to LIB_TARGETS except these files are only built and installed when the current build environment targets the specified version of VxWorks and BSP.

MOD_TARGETS

If defined, it should be a list of file names -- separated by spaces -- which should get installed in $PRODUCTS_MODDIR. These are typically loadable modules with a .out suffix. These are files that booting front-ends will download.

MOD_ bsp _TARGETS

Similar to MOD_TARGETS except these files are only built and installed when the current build environment targets the specified BSP.

MOD_ vv _TARGETS

Similar to MOD_TARGETS except these files are only built and installed when the current build environment targets the specified version of VxWorks.

MOD_ vv _ bsp _TARGETS

Similar to MOD_TARGETS except these files are only built and installed when the current build environment targets the specified version of VxWorks and BSP.

PRODUCT

When this symbol is defined, you are designating that your project is a "product" that can be used by all front-end programmers. These projects typically are built for all VxWorks versions and BSPs using the beta-install target (for development) and promote to promote them to release status. If your project is backed by CVS or GIT, frontend.mk won't install any files until all changes are committed.

SUBDIR_NAME

If defined, it will be used as the name of a subdirectory in the install area. This allows a project to install in the download area, but still be partitioned from other projects' files. If this variable is used, AS_SUBDIR is ignored.

SUPPORTED_VERSIONS

Indicates which versions of VxWorks the project supports. The value is a list of two-digit numbers (representing the version) separated with spaces. The default value is "54 55 61 64 67".

SUPPORTED_VXWORKS_ vv _TARGETS

Indicates which BSPs of the specified VxWorks version are supported by the project. The default values enable all BSPs:

Symbol Default
SUPPORTED_VXWORKS_54_TARGETS "MC68020 MC68040 PPC603 PPC604"
SUPPORTED_VXWORKS_55_TARGETS "mv162 mv2303 mv2400 mv2401 mv2434 mv5500"
SUPPORTED_VXWORKS_61_TARGETS "mv2400 mv2401 mv2434 mv5500"
SUPPORTED_VXWORKS_64_TARGETS "mv2400 mv2401 mv2434 mv5500"
SUPPORTED_VXWORKS_67_TARGETS "mv2400 mv2401 mv2434 mv5500"

VID

Specifies the project's current version number. This number will be appended to the base name of generated files. For instance, if VID is set to "1.0" and your Makefile builds example.out, it will get installed as example-1.0.out.

frontend.mk has skeletal support for OTHER_TARGETS and VXE_TARGETS. Currently, however, there's no install location for OTHER_TARGETS and we don't know how to build real-time processes so VXE_TARGETS doesn't do anything either.

Adding Build Rules

Content Outline (to be written):

  • The CURRENT_TARGET variable.
  • $(make-mod), $(make-mod-nomunch), $(make-vxe), $(make-lib).

Targets Defined by frontend.mk

These are the useful, make targets that frontend.mk defines.

all

If no targets are defined before including frontend.mk, then this becomes the default target. all simply builds all the targets defined in LIB_TARGETS, MOD_TARGETS, and VXE_TARGETS.

beta-install

Iterates through all targets defined with SUPPORTED_VXWORKS_**_TARGETS and SUPPORTED_VERSIONS. The project is built in each environment and installed as a beta in the download area. NDEBUG is not defined during a beta build, so you can use assert macros for testing. All targets that are installed get the version number, specified by the VID symbol, added to their file name. If the project defines PRODUCT, then all changes must be committed before anything can be installed in the download area.

build-all

Iterates through all targets defined with SUPPORTED_VXWORKS_**_TARGETS and SUPPORTED_VERSIONS. The project is built in each environment, but not installed. This target is used to make sure all environments can build the source code without modifying the download area.

clean-all

Deletes generated files in the current directory. You can define CLEAN_TARGETS to add more file specifications to delete.

help

Displays a page of text describing the available targets.

install

Builds and installs the project only for the current environment. If the project defines PRODUCT, then all changes must be committed before the generated files can be installed in the download area.

project-info

Displays information about the project. It shows settings which affect all targets supported by the project and it shows settings that are active for the currently selected environment.

promote

Promotes the current project to "release" status. The project must currently have a BETA version. The project will be rebuilt for every supported BSP/VxWorks combination with the symbol NDEBUG defined. Once everything has been built and installed in the download area, the beta status is removed for all targets. Before a new beta can be built and installed (via beta-install), the project's VID symbol needs to be updated.

show-var

A diagnostic target which shows the expanded value of a make symbol. You must set VARNAME to the name of the variable to show. For instance, to see ADDED_CFLAGS, you would use "make show-var VARNAME=ADDED_CFLAGS".

Topics Remaining

  • Making .s files.
  • Discuss stage and release.