Description File Variables
|
DEFS.MK
|
|
|
The defs.mk file describes how QMake builds the current directory.
|
The "defs.mk" description file is used by QMake to determine what files are to
be processed when building the current directory. It achieves this by setting
various variables. These fall into several categories listed on the right.
Directory Description
The automatic documentation system requires a one line description of each
directory in your project. This is defined as follows:
- DESCRIPTION
- A one line description of the directory contents. This should give potential
users an idea about the functionality that this directory contributes to
the project.
Multiple Directory Packages
The QMake system is capable of building a tree of directories. The
following variable is used to specify the branches from the current directory.
- NESTED
- The list of subdirectories which are built before the current directory.
A suffix '.r' flag is used to indicate that the directory is ready to be built
otherwise it is ignored. For example:
NESTED = Vector.r Matrix List.r means that the directory Vector is
built first and List is built second. Matrix is skipped.
Platform Support
The default behaviour of the make system is to support all packages on all
platforms. The packages should be written in such a way that they can survive
the arrival of new software and hardware architectures quite easily. Software
written for a specific platform, like an operating system or a hardware card,
usually dies with the platform which often happens within 2-3 years of writing.
There is sometimes a necessity to maintain software for special hardware such
as a frame grabber, etc. For these exceptional circumstances, the following
variables are provided:
- SUPPORT_ONLY
- A list of architectures which are supported. If the contents of this
variable clashes with DONOT_SUPPORT, then the architecture will be supported.
If neither SUPPORT_ONLY or DONOT_SUPPORT is set, then all architectures are
supported. For example:
SUPPORT_ONLY = sol2 alpha means that the
subtree of directories including the current one will be processed only for
the Solaris2 and Alpha architectures.
- DONOT_SUPPORT
- A list of architectures which is not supported. For example:
DONOT_SUPPORT = sgi means that the subtree of directories including
the current one will be processed for all architectures except Silicon
Graphics.
Source Files
The compilation of libraries and executables are controlled by the following
variables:
- MAINS
- All executables that are
installed in the $PROJECT_OUT/bin directory. The suffixes '.cc' or '.c'
control the calling of a compiler and a linker. The following suffixes are
expected:
- .cc for executables compiled and linked by C++ compiler.
- .c for executables compiled and linked by C compiler.
- .f for executables compiled and linked by Fortran compiler.
- .for for executables compiled and linked by Fortran compiler.
For example, MAINS = rgbTool.cc matcher.c will make two executables.
The first one, rgbTool.cc, is compiled using C++ compiler and the compilation
of the second executable, matcher.c, is done by the C compiler.
The names of executables in MAINS variable must be unique.
- SOURCES
- All source files which are added to the library defined by the variable
PLIB. The suffixes play the same role as in the variable MAINS.
The names of files in SOURCES variable should be unique to avoid
clashes of names during restructuring of libraries. However, the
names MUST be unique in the library specified by the variable PLIB
(see below).
- MUSTLINK
- Advanced users only. This is a list of source files that MUST be
linked when using a library. The suffixes play the same role as in the variable MAINS.
The name of files specified in MUSTLINK, must be unique with respect
to all other files specified in MUSTLINK throughout RAVL. This directive
can be used to force files to be included into executables, where dependancies
alone would not caused it to be linked. This mechanism is used where constructors
for global variables modify or add to global databases. An example of this is
the file format register in the RavlIO library.
- HEADERS
- All the public header
files, i.e. those which are needed globally. They are exported to the
directory $PROJECT_OUT/include/$(PACKAGE), to make them available
to other. E.g. if you have a file
headerfile.hh to export, the
line will be
PACKAGE = Ravl
HEADERS = headerfile.hh
Thus to #include the header file, you need to put:
#include "Ravl/headerfile.hh"
if PACKAGE is not set you can include headerfiles as normal.
(For a more structured global header file system, see PACKAGE.)
- LOCALHEADERS
- Header
files which are used only for compilation in the current directory. These
header files are not exported.
- PACKAGE
- Advanced users only. The
name of the package to which the directory belongs. In fact, it is a part of
the subdirectory path where public header files are copied. For example,
PACKAGE = Ravl/Surf3d means that all public header files will be
copied into the directory $PROJECT_OUT/include/Ravl/Surf3d and a header file must
be included in an implementation file as
#include "Ravl/Surf3d/Curve3d.hh"
The default value of PACKAGE variable is no special path, so header files are
place directly into $PROJECT_OUT/include.
ATTENTION!! For code intended for contribution to
RAVL. The directories defined by PACKAGE should be
agreed by a number of contributors, otherwise the whole system will finish with
hundreds of directories each containing a very few header files. Furthermore,
the variable should not be changed arbitrarily because it will break code
that depends on the library.
.
Libraries
These variables control the generation and linking of libraries.
- PLIB
- Use this to give your library a name (hence it must take only one value):
PLIB = mylib
It is the name of the library in which the modules specified by the variable
SOURCES are archived. A unique name for each directory is recommended.
- USESLIBS
- This is an unordered
list of the libraries needed to build the new library specified by PLIB. Use
of this variable causes the automatic creation of a "defs" file called
(PLIB).def. There are different ways of creating this list:
ATTENTION: If this variable is set the .def file is ALWAYS automaticly
generated. If LIBDEPS is set as well then this is used as the name of the
generated file. if you have library which depends on nothing else, but you
wish to set USESLIBS you can use the dummy library 'None'. Example,
USESLIBS = None
- PROGLIBS
- The name of the
libraries used to create executables specified in either MAINS or EXAMPLES that
are not already included with the USESLIBS variable. Typically you would
include things like the Options code which is not need for the PLIB library
itself. For example:
PROGLIBS = Mopt You can use the automatic
methods described under USESLIBS for PROGLIBS as well.
- LIBDEPS
-
LIBDEPS is used to explicitly create references to libraries. E.g. the
following entry in the defs.mk file would create a reference to an external
library RavlImageFilter:
LIBDEPS = RavlImageFilter.def
which could then be referenced in the normal way, e.g.:
USESLIBS = RavlImageFilter
See the file RavlImageFilter.def itself to see what to put in it.
This is used where the source for a library spans several directories, where each
directory creates a .def file but the object files are are added to a single
library.
Example programs
The following two variables can be used for a specification of executables used
for a demonstration how to use packages or for their run-time checking.
- EXAMPLES
- Contains the names of
source files demonstrating the use of the software in the directory. They are
copied into the documentation area. The example sources must be compilable; to
check compilation, include them temporarily in the "MAINS" list, e.g.:
qm MAINS=example.cc
- TESTEXES
- The list of executables testing runtime consistency of the software. They
are compiled and run to test if they produce expected results. The executables
should return 0 on success, non-zero on failure. If the program doesn't exit
normally it will be treated as a failure. Both stdout and stderr of the program are
stored in a log during testing to help trace bugs. Testing done using the 'qm test'.
Special Files
The directory can contain special files which should be extracted from the
database of source files. They can be examples of data input, etc. The size of
these file should be kept to a minimum. The following variables can be used for
a specification of these file:
- LOCAL_FILES
- All files which do not fit to any other category of variables of defs.mk
file. These file are extracted to the current directory from the database of
sources and regularly updated.
Documentation
The documentation of packages is also propagated into the proper installation
directories. The following variables describe what kind of documentation the
files in the current directory have.
- EHT
-
List of EHT files for creating extra documentation for nodes in the tree.
Nodes in the tree should be named for the path in the documentation tree. e.g. the extra
documentation for arrays has the name 'Containers.Arrays.eht'.
Executables MUST start with the prefix exe, followed by the name of
the executable, with a extention of '.eht' or '.html'.
- DOCNODE
- Specifies additional files required by EHT files, ie images.
- HTML
- Contains the names of documentation written in plain hypertext.
- MAN1
- Contains the names of files of manual pages of executables.
- MAN3
- Contains the names of manual pages describing library functions.
- MAN5
- Contains the names of manual pages describing format of files.
|