User Documentation
RAVL, Recognition And Vision Library
DEVELOP HOME PAGE CLASS LIST CONTENTS
Ravl - QMake - Defs


Description File Variables

  CATEGORIES
  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:
    • The easiest usage is simply to use the value "Auto":
        USESLIBS = Auto
      
      This should automatically generate the required list of libraries for both USESLIBS and PROGLIBS, without you even noticing.
    • The previous usage will not pick up any libraries that don't have a corresponding header file anywhere, which happens occasionally. Likely candidates are I/O libraries such as the "RavlImageIO" image I/O library. Use the "QLibs" tool (which is what makes the "Auto" method work) to print out most of the library list for you; all you have to do then is locate and add the missing ones.
    • The traditional way was to create the list yourself, using the libraries indicated in the class pages, e.g.:
        USESLIBS = RavlCore RavlIO
      
      You need only specify libraries you use explicitly; any others will be automatically included.

    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.

Documentation by CxxDoc: Tue Aug 13 10:00:52 2002