addvariant

Runs on:

Linux, Mac, Microsoft Windows

Options:

-C type

Specify the type of Software Configuration Management (SCM) system. This setting is used when the directory structure is added with the -c option. The type must be cvs, rcs, or svn.

-c

Add the created directory structure to the SCM repository on the next commit.

-i init_lvls

Create the initial common.mk and Makefile files in the Current Working Directory (CWD). 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; these two characters are parsed in the same way).

The -i option is useful for “squashing” directories, which entails combining multiple levels together; for an explanation, see “Squashing Levels” below.

Note: You must specify this option in a clean (empty) directory, or else nothing gets done.

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_64).

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.

Dealing with GNU projects

The utility begins by checking to see if the projects conform to a GNU-type structure. If the 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 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 (when -i is specified), or if these files already exist, edits them to add the same standard script lines used for recursing.

Squashing levels

The addvariant utility has the ability to “squash” directory levels together. For instance, if you enter the command:

addvariant -i OS/CPU/VARIANT nto x86_64 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_64-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_64/o:

addvariant -i OS/CPU nto x86_64 o

Create subdirectories for two CPU variants with their own Makefiles:

addvariant -i OS
addvariant nto x86_64 o
addvariant nto aarch64 o.le

The first addvariant command in this sequence creates a common.mk and Makefile in the CWD. The common.mk file contains all of the rules for building the project. The Makefile includes the recurse.mk content, which allows make to recurse into all of the subdirectories when you build from the top-level directory. When you build from one of the variant subdirectories, make uses the Makefile from that subdirectory. This Makefile simply includes the common.mk file from the top-level directory, and binaries for only that CPU variant are generated.

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