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)