addvariant

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

Syntax:

addvariant [-C type] [-c] [-i init_lvls] [[os_name] cpu_name] variant_name

Runs on:

Linux, Microsoft Windows

Options:

-C
Specify the type of software configuration management system for the -c option. The type must be cvs, rcs, or svn.
-c
Add the created directory structure to the SCM repository on the next commital.
-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).
os_name
The name of the operating system to add (e.g., nto, linux).
cpu_name
The name of the CPU to add (e.g., arm, x86).
variant_name
The name of the variant to add (e.g., o, a.le)

Description:

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 Neutrino build environment. For more information on these rules, see the Conventions for Recursive Makefiles and Directories appendix of the QNX 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 QNX 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:

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

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.

For more information, see Andrew Oram and Steve Talbott, Managing Projects with make, O'Reilly and Associates, 1991.

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 QNX Neutrino Programmer's Guide.