`addvariant`

Add a new OS, CPU, or VARIANT directory structure to a source tree

Syntax:

addvariant [-c] [-i init_lvls] [-P] [[os_name]
           cpu_name] variant_name

Options:

-c: Add the created directory structure to the CVS repository on the next cvs commit.
-i init_lvls: Create the initial common.mk and Makefile files in the current working directory. The Makefile contains a line defining the level(s) contained in the directory structure. Specify init_lvls as OS, OS/CPU, or OS/CPU/VARIANT (use a slash (/) or a dash (-) to separate multiple levels).
-P: Create initial directories for a PhAB application.
os_name: The name of the operating system to add (e.g. qnx4, nto, linux).
cpu_name: The name of the CPU to add (e.g. mips, ppc, x86).
variant_name: The name of the variant to add (e.g. o, a.be)

The addvariant utility is a shell script that creates a directory structure for your source tree. It also ensures that each level of this structure contains necessary files used by the make utility.

Using addvariant to create your variant directory structure enables you to take advantage of the makefile rules of the QNX build environment. For more information on these rules, see the Conventions for Recursive Makefiles and Directories appendix of the Neutrino Programmer's Guide.

The project level includes a file called common.mk. This file contains any “special” flags and settings needed for compilation and linking.

Each level in the directory structure needs a properly constructed Makefile with appropriate macros and include files. At most levels, Makefile includes recurse.mk, the file used by higher-level makefiles to recurse into lower-levels. The Makefile at the lowest level of the directory tree (the variant level) includes the common.mk file from the project level instead of recurse.mk.

If requested, addvariant also adds the directories and files it has created to CVS, ready for your next cvs commit.

Dealing with GNU projects

The utility begins by checking to see the projects conform to a GNU-type structure. If the current working directory (CWD) contains files named configure and Makefile.in, addvariant assumes that the project is configured in the GNU style. In that case, it automatically squashes the directory levels (as described below) into a single OS-CPU-VARIANT level and creates GNUmakefile files in the newly created directories along with a recursing Makefile to take advantage of them.

After you've run addvariant, create an executable shell script called build-hooks file in the root of the project. This script defines some shell functions that make invokes to build your project properly; for more information, see “GNU configure” in the Conventions for Recursive Makefiles and Directories appendix of the Neutrino Programmer's Guide.

Creating the initial files

The addvariant utility either creates and installs standard Makefile and common.mk files in the CWD, or, if these files already exist, edits them to add the same standard script lines used for recursing.

Creating the subdirectories and files

Starting from the CWD, the addvariant utility searches down into the directory tree looking in each Makefile for a line starting with LIST. This line indicates the particular directory level the Makefile is placed in, like this:

LIST=OS (if three levels are specified)
LIST=CPU (if two levels are specified)
LIST=VARIANT (if one level is specified)

The utility then decides whether to create a subdirectory by looking at the:

LIST macro
*_name options
current subdirectories

If needed, addvariant then creates an appropriately named subdirectory containing a suitable Makefile.

This process continues down into the directory structure until all the required directories have been created and populated with the necessary recursing Makefile.

Squashing levels

The addvariant utility has the ability to “squash” directory levels together. If you enter the command:

addvariant -i OS/CPU/VARIANT nto x86 o

addvariant creates a recursing Makefile in the CWD structure that has a line like this:

LIST=OS CPU VARIANT

and then creates a single subdirectory called nto-x86-o.

Any subsequent invocation of addvariant in the tree notices this squashing of the directory levels and automatically generates the appropriate directory structure.

Examples:

Create a two-level directory called nto-x86/o:

addvariant -i OS/CPU nto x86 o

Create the opposite two-level scheme, nto/x86-o:

addvariant -i OS nto x86/o

For detailed examples, see “Examples of creating Makefiles” in the Conventions for Recursive Makefiles and Directories appendix of the Neutrino Programmer's Guide.