`addvariant`

Add a new OS/CPU/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: Creates the initial common.mk and Makefile files in the current working directory. The Makefile will contain 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, solaris).
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 "Conventions for Makefiles and Directories" in the 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 will also add the directories and files it has created to CVS, ready for your next cvs commit.

Dealing with GNU projects

The utility begins by checking whether 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 will automatically squash the directory levels (as described below), and will create GNUmakefiles in the newly created directories along with a recursing makefile to take advantage of them.

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 will create a recursing makefile in the CWD structure that has a line like this:

LIST=OS CPU VARIANT

and will then create a single subdirectory called nto-x86-o.

Any subsequent invocation of addvariant in the tree will notice this squashing of the directory levels and will automatically generate 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