Add a new OS, CPU, or VARIANT directory structure to a source tree
addvariant [-c] [-i init_lvls] [-P] [[os_name] cpu_name] variant_name
- 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).
- Create initial directories for a PhAB application.
- The name of the operating system to add (e.g. qnx4, nto, linux).
- The name of the CPU to add (e.g. x86).
- 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 BlackBerry 10 OS build environment. For more information on these rules, see the Conventions for Recursive Makefiles and Directories appendix of the BlackBerry 10 OS 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 BlackBerry 10 OS 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.
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.
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 BlackBerry 10 OS Programmer's Guide.
Last modified: 2013-09-30