NAME
Shapefile.tmpl, Makefile.tmpl, Release.tmpl, release.c.tmpl — templates
in the shapeTools RMS
DESCRIPTION
When working with the shapeTools Release Management System, all system
model files (Shape- and Makefiles) must be derived from templates,
namely Shapefile.tmpl and Makefile.tmpl. The templates define a certain
number of standard macros names used througout the shapeTools RMS.
Deriving system model files from the templates is mainly filling in the
appropriate macro values. The following section gives an overview of
all macro names defined in the templates and a short explanation on the
semantics of each macro.
Release.tmpl and release.c.tmpl are templates for release
identification files. They do not need to be adapted in any way.
MACROS
The following is a list of macros that occur in the Shape- and Makefile
templates. Most of them are defined in the Makefile. As Makefiles are
included in the Shapefiles, these are used by both, calls of make and
calls of shape. Some shape specific macros (defined in the Shapefile
template) are described at the end of this section.
As the shapeTools RMS performs recursive calls of shape (resp. make),
some of the standard macro settings get inherited to a recursively
called sub-build-process. The macros are marked in the list
accordingly. The inheritance mechanism allows installation dependent
macros (eg. BASE) to be set for the whole project by only modifying
the value in the top level Shape-/Makefile.
Locations and General Macros
BASE (inherited)
The base directory of the project’s central source repository.
NODEPATH
The relative path name of a system node within the project’s
source repository. In the top node, this macro has an empty
value. For subsystems, it is to be set to the path relative to
$(BASE) (eg. "/subsystem/library").
NODENAME
A short name for the developed system node. This name will also
to be used for generating release identification strings having
the form <system_name>-<release_number>.
HOSTSYSTEM (inherited)
The underlying operating system. The value of the HOSTSYSTEM
macro is built after the schema s-<opSys>. This macro has
different meanings in make and in shape.
Make treats it as an an extension to a known base path for
accessing the appropriate versions of operating system dependent
files. The base path points to a directory containing
subdirectories for each supported operating system type. All
subdirectories carry the same list of filenames with in each
case different (operating system specific) contents.
For shape, the HOSTSYSTEM macro is treated as variant
definition. With the corresponding variant definition defined in
the variant definitions include file (see shape_stdvar(7)), a
whole bunch of macros is set (resp. modified).
HOSTTYPE (inherited)
The machine architecture. This macro should be used for
installing different binaries (for different machine
architectures) compiled from the same program source in a
heterogeneous network. On systems containing the arch command,
HOSTTYPE may be dynamically set by HOSTTYPE=‘arch‘. This macro
is currently not supported in the default installation setup.
SWITCHES (inherited)
Preprocessor switches for conditional compilation. This macro
may be used for system wide switching on/off certain program
behavior. The SWITCHES are passed as arguments to the language
preprocessor.
INSTALLBASE (inherited)
Locations and modes for installation of executables, header
files, libraries, and manuals. The INSTALLBASE macro eases the
definition and redefinition of the following installation path
macros, as the values of these may cite INSTALLBASE. Each of the
installation path macros may also be set to a value independent
of INSTALLBASE.
INSTALLBINPATH (inherited) - installation directory for executables
INSTALLBINMODE (inherited) - file protection mode to be set for installed executables
INSTALLINCPATH (inherited) - installation directory for include files
INSTALLINCMODE (inherited) - file protection mode to be set for installed include files
INSTALLLIBPATH (inherited) - installation directory for libraries
INSTALLLIBMODE (inherited) - file protection mode to be set for installed libraries
INSTALLMANPATH (inherited) - installation directory for manuals
INSTALLMANMODE (inherited) - file protection mode to be set for installed manuals
Installimn manuals using the INSTALLMANPATH macro expects
appropriate manX (man1, ...) subdirectories there.
LIBPATH (inherited)
The directory, where local libraries, developed within the
project, shall be installed for project wide use.
INCLUDEPATH (inherited)
Similar to LIBPATH. The location of project internal header
files.
The System Components
TARGET The name of the main target to be built. This can be a program,
a library, or anything else to be produced. If the construction
of the main target does not require any real transformation (if
eg. only subsystems are to be built), it is advisable to have a
file $(SUBSYSTEMNAME).date as main target. The system building
action should just touch this file, so that it’s modification
date shows, when the last system building action happened. If
the managed system consists of multiple programs, this macro
should be multiplied (eg. TARGET_1 TARGET_2 ... TARGET_N). In
that case, all places in the Makefile, where $(TARGET) occurs
have to be modified accordingly !
VERSIONFILE
The name of a file, used as release number generator. With each
new release, a new version of this file is generated
automatically. When developing a program, this file ideally
contains exactly one function returning a version identification
string. When using the ShapeTools version control system’s
attribute citation mechanism, the contents of such a file needs
only to be written once and never be changed afterwards. There
are different prototypes for such a file in $(LIBPATH)/shape.
For system parts not incorporating an executable program, any
other source file could be chosen as release number generator.
In any case should $(VERSIONFILE) never be saved explicitly by
the user.
VERSIONOBJECT
The object file (.o file) derived from VERSIONFILE. This macros
is only to be set, when VERSIONFILE contains program text.
SUBSYSTEMS
All subdirectories, where additional parts of the system wait
for being built. For each subtarget, a recursive shape (resp.
make) call is performed with the current macro settings getting
inherited. The SUBSYSTEMS will be build before TARGET. This
macro may also be empty.
ALIASES
This is a list of aliases for TARGET. This macro is to be set,
when TARGET should be accessible by multiple names (eg. a
program to be activated under different names).
SOURCES
A list of all programming language source files belonging to the
system. In the case of C development, these are the .c files
HEADERS
The header files belonging to the system. The .h files in case
on C development.
AUXSOURCES
Auxiliary source files. These are source files that shall also
be processed when building the system, but that are not genuine
part of the system. These are for example sources of auxiliary
test programs, needed to perform test in the development area.
AUXHEADERS
Auxiliary header files, similar to auxiliary sources.
VARIANTSOURCES
VARIANTHEADERS
Equally named source and header files, located in
subdirectories, each named after a certain variant. For system
building, only one of the directories is used, according to the
specified HOSTSYSTEM. In the shape_RMS environment, the
subdirectory names should be chosen from the value set of the
HOSTSYSTEM macro (for more details, see the description of the
HOSTSYSTEM macro above).
MANUALS
The manual files for the system, distinguished by categories.
COMPONENTS
All source components belonging to the system. These are the
source files (SOURCES), the include files (HEADERS), the manuals
(MANUALS), the Shapefile, the Makefile and a (generated) file
named Dependencies.
OBJECTS
All files, automatically produced during a build process except
TARGET. These are usually the .o files.
Tools, Flags and Libraries
MAKE (inherited)
The make program. This macro is used for recursive calls of
make. During execution of shape, this macro is explicitly (in
the Shapefile) set to the value of the SHAPE macro. This causes
recursive builds also to be performed by shape.
SHELL (inherited)
The shell to be used by make, resp. shape for interpreting the
build actions in the Makefile or Shapefile.
CC (inherited)
The C compiler to be used.
CFLAGS (inherited)
The C compilation flags (see SWITCHES for additional compilation
flags).
LDFLAGS (inherited)
The linker flags.
RANLIB (inherited)
The program for adding a table of contents to archives.
SYSLIBS (inherited)
Additional system libraries to be linked to TARGET
LOCALLIBS
Local libraries to be linked to TARGET
LINTLIBS
Libraries to be invoked when executing "lint".
Shape Specific Macros
VERSIONS
The default version binding (version selection) rule to be
applied for each component. Selection rules are globally defined
in the $(SHAPELIBPATH)/stdrules file (see shape_stdrul(7)). It
is strongly recommended, to define a project wide version
selection policy only in the stdrules file and to renounce
version selection rules in local Shapefiles.
BINDDEFAULT (inherited)
Internal name for VERSIONS. Should not be redefined.
BINDINSTALL (inherited)
THe default version binding rule to be applied when installang a
system or system part for project wide or global use.
COMPILER (inherited)
The compile environment. This macro represents a shape variant
selection. With each variant, a whole bunch of macro settings
may be associated, so that the COMPILER variant not only sets
the actual compiler (CC), but also some compilation flags. See
stdvar for the default variant raster. The same as version
selection rules, the variant raster should be defined project
wide. Local variant definitions can very easyly lead to
confusion and improper configurations.
QUALITY (inherited)
The desired quality of the produced object code. This is also a
variant definition (see stdvar for other options).
RELEASEBASE (inherited)
PARTIALRELEASEBASE (inherited)
The base of the directory tree, where prereleases and releases
of the system are to be constructed. When building a
(pre)release, the appropriate versions of all components of the
system are copied from the development area to the release area.
The release area should only be used for performing final tests
and for bundling up a shippable package.
RELEASESRCPATH
The relative path within the release or partial release area
where the suorce files ar to be copied to. Ususally, this is
identical to $(NODEPATH).
RELEASEMANPATH
The relative path within the release or partial release area
where all manuals are gathered.
SHAPELIBPATH (inherited)
The directory, where all common parts of the shape_RMS
environment reside. Here are all the templates and shape include
files located.
.BPOOL:
This is rather a pseudu-target, than a Macro. Shape interprets
this as directive that causes only the listed files ($(OBJECTS))
to be put into the derived object cache. Defining the pseudo
target .NOBPOOL: (without dependents) deactivates the derived
object cache. This is necessary, when the development
environment requires access to the same derived object cache
from machines with different architectures. The reason is, that
"dbm" databases (and derived object caches use dbm databases)
are not portable between different machine architectures.
FILES
Shapefile.tmpl- Template for node specific Shapefiles
Makefile.tmpl- Template for node specific Makefiles
release.c.template
Release.template
SEE ALSO
shape_RMS(1)