Provided by: shapetools_1.4pl6-16.1build1_amd64 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)