SHAPE_TMPL(7)

📦 version 1.4pl6, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 SHAPE_TMPL(7) 💅

okay so welcome to the Miscellaneous Information Manual, bestie. This is SHAPE_TMPL(7), and it's giving template lore. Sit down, grab a strawberry, we're doing this. 🍓

🌸 NAME 🌸

Shapefile.tmpl, Makefile.tmpl, Release.tmpl, release.c.tmpl — the templates in the shapeTools RMS

✨ DESCRIPTION ✨

When you're working inside the shapeTools Release Management System, all the system model files (that means your Shapefiles and your Makefiles) must be derived from templates, namely Shapefile.tmpl and Makefile.tmpl. No skipping this step, it's not optional. 💀

Those templates define a certain number of standard macro names that get used throughout the shapeTools RMS. Deriving system model files from the templates is mainly just... filling in the appropriate macro values. That's it. That's the job. You're basically decorating. 🎀

The next section gives you an overview of every macro name defined in the templates, plus a short explanation of 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. Like, at all. Leave them alone, they're perfect. 👑

🔥 MACROS 🔥

Here's the list of macros that occur in the Shape- and Makefile templates. Most of them are defined in the Makefile. And since Makefiles are included in the Shapefiles, both calls of make and calls of shape use them. Some shape specific macros (the ones defined in the Shapefile template) get described at the end of this section, don't worry, we get there. 🦋

Because the shapeTools RMS performs recursive calls of shape (resp. make), some of the standard macro settings get inherited down into a recursively called sub-build-process. Those macros are marked in the list accordingly. This inheritance mechanism is honestly iconic: it lets installation dependent macros (eg. BASE) be set for the whole entire project by only modifying the value in the top level Shape-/Makefile. One edit. Whole project. ate. ✨

📍 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, set it to the path relative to $(BASE) (eg. "/subsystem/library").
NODENAME — a short name for the developed system node. This name will also 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, so pay attention bestie:
- make treats it as 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 a 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 of 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
- Installing 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 its 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 ! (yes, that exclamation mark is staying, this one is serious)
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, $(VERSIONFILE) should never be saved explicitly by the user. 🙈
VERSIONOBJECT — the object file (.o file) derived from VERSIONFILE. This macro 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 built 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 of 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 tests 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. slay.
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. fr fr, keep it global.
BINDDEFAULT (inherited) — internal name for VERSIONS. Should not be redefined.
BINDINSTALL (inherited) — the default version binding rule to be applied when installing a system or system part for project wide or global use. 💜

COMPILER (inherited) 💻✨

okay so bestie, this macro is literally the compile environment. It's 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. Same as version selection rules, the variant raster should be defined project wide. Local variant definitions can very easily lead to confusion and improper configurations. So maybe don't do that. 🙈

QUALITY (inherited) 🎀

The desired quality of the produced object code. This is also a variant definition (see stdvar for other options). Slay.

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. Periodt.

RELEASESRCPATH 🛣️

The relative path within the release or partial release area where the source files are to be copied to. Usually, 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 pseudo-target than a Macro. Shape interprets this as a 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