Ubuntu Manpage: Shapefile.tmpl, Makefile.tmpl, Release.tmpl, release.c.tmpl

Provided by: shapetools_1.4pl6-16.1build1_amd64

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

NAME

DESCRIPTION

MACROS

FILES

SEE ALSO