Provided by: shapetools_1.4pl6-10_i386 bug

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)