skip to main content

LCFG Build Tools : Substitution Variables

This document gives details of all the macros available for building packages from LCFG software sources.

Note that not all macros are available at every stage of the source packing and building process. Particularly, it should be noted that in an RPM specfile you can only use the macros provided as part of the package information and standard directories. This is deliberately different from the way things were done with the previous incarnation of LCFG build tools. Anything which is platform or architecture specific can only be resolved at build time and that could occur much later than when the specfile is built.

  1. Basic Usage
  2. Not Supported
  3. Package Information
  4. Standard Directories
  5. Platform Specific
  6. Linux Specific
  7. MacOSX
  8. Miscellaneous

Basic Usage

Most people will be familiar with the autoconf style macros. For example:

#!@SHELL@
##########################################################################
#
# LCFG new generic component
#
# Author: @LCFG_AUTHOR@
# Version: @LCFG_VERSION@
# Date: @LCFG_DATE@
#
# @MSG@
#
##########################################################################

There is one subtle difference between using autoconf to fill in these values and using CMake instead. With autoconf (and also the old LCFG build tools) it will only replace variables which are known to the system in some way. However, CMake will replace ALL variables placed between a pair of "@" symbols. If that variable has not been set it will replaced with an empty string. Generally this is what people want but it can cause some gotchas until you become used to this mode of operation.

With the new build tools there is one caveat to this advice. When metadata files are generated (e.g. the RPM specfile), at the time of source packing, a different system is used to carry out macro replacement on the template files. This system will only replace known variables and will leave any others in place, a warning will be printed to STDERR for each occurrence. If you are not using CMake as the build tool (in the case of Perl modules, for instance) it is also possible to use this system on any input files you specify. That is all documented elsewhere.

If you need to write some CMake files to get more control over the build process then you can use all these variables in the standard way which is to refer to them like ${FOO}.

Macros which are NOT supported.

We deliberately do not support any of the following:

Any code using these macros will have to be modified. This type of macro is a maintenance nightmare requiring scripts to be unnecessarily altered for every new platform. There are always better ways based around conditionals using the other platform-specific macros. In most cases an even better solution is to use LCFG resources and make the platform specific changes in the LCFG header files instead.

Package Information

This is the list of standard macros which provide access to package information. Most of them come directly from fields in the LCFG build tools metadata file, lcfg.yml, and the others are generated by a combination of the fields. For backwards compatibility there are various aliases provided but these should be considered as deprecated. We want to move away from them to avoid any possible conflicts with variables already used by CMake.

Macro Description Aliases
LCFG_NAME This is the name of the package, stored in the name field. This will always be specified. COMP
LCFG_FULLNAME This is the full name of the package. If the base field is specified then this is base-name, otherwise it will be the same as LCFG_NAME. NAME
LCFG_ABSTRACT This is a short description of the package, stored in the abstract field. This is optional. DESCR
LCFG_VERSION This is the version of the package, stored in the version field. This will always be specified. V, VERSION
LCFG_RELEASE This is the release of the package, stored in the release field. As this only makes sense on some platforms (e.g. RPM or Debian based systems) it is optional. R, RELEASE
LCFG_SCHEMA This is the schema version of the package, stored in the schema field. This is only applicable to LCFG components so is optional. SCHEMA
LCFG_VENDOR This is the vendor or organization responsible for the packaghe, stored in the vendor field. You probably do not need this field and it is provided mainly for backwards compatibility, for this reason it is optional. VENDOR, ORGANIZATION
LCFG_GROUP This is the software group to which the package belongs, stored in the group field. You probably do not need this field and it is provided mainly for backwards compatibility and is only meaningful for RPM packages, for this reason it is optional. GROUP
LCFG_AUTHOR This is the author (or authors) of the package, stored in the author field. If there are multiple authors they will be in a comma-separated list. This is optional. AUTHOR
LCFG_PLATFORMS This is a list of the supported platforms, stored in the platforms field. if there are multiple values they will be in a comma-separated list. This is optional. PLATFORMS
LCFG_DATE This is the date at which the last release of the package was made, stored in the date field. There is no specific format but it is normally like  day/month/year hour:min:sec . This is optional. DATE
LCFG_LICENSE This is the license under which the package is distributed, e.g. GPLv2, stored in the license field. This is optional.  
LCFG_TARNAME This is the file name of the gzipped tar file of the package source which is created during the packing stage (i.e. before any builds are carried out. It is equivalent to LCFG_FULLNAME-LCFG_VERSION.tar.gz TARFILE

Standard Directories

Macro Description Value
INITDIR Location of init scripts directory /etc/init.d
LCFGBIB Directory for BIB files /usr/lib/lcfg/doc/bib
LCFGBIN Directory for user binaries /usr/bin
LCFGCLIENTDEF Directory for default resource files used by client /usr/lib/lcfg/defaults/client
LCFGCOMP Directory for components /usr/lib/lcfg/components
LCFGCONF Directory for generated files to be preserved between object runs /var/lcfg/conf
LCFGDATA Directory for templates and other fixed configuration files /usr/lib/lcfg/conf
LCFGDOC Base directory for documentation /usr/lib/lcfg/doc
LCFGHTML Directory for HTML files /usr/lib/lcfg/doc/html
LCFGLIB Base directory for read-only files /usr/lib/lcfg
LCFGLOCK Directory for lock files /var/lcfg/lock
LCFGLOG Directory for log files /var/lcfg/log
LCFGMAN Base directory for man pages /usr/share/man
LCFGPDF Directory for PDF files /usr/lib/lcfg/doc/pdf
LCFGPOD Directory for POD files /usr/lib/lcfg/doc/pod
LCFGROTATED Directory for log rotate config files /etc/logrotate.d
LCFGSBIN Directory for system binaries /usr/sbin
LCFGSERVERDEF Directory for default resource files used by server /usr/lib/lcfg/defaults/server
LCFGSTATUS Directory for status files /var/lcfg/status
LCFGTMP Directory for temporary files /var/lcfg/tmp
LCFGVAR Base directory for writeable files /var/lcfg
LIBMANDIR The directory for library man pages /usr/share/man/man3
MANDIR The directory for admin man pages /usr/share/man/man8

Platform Specific

For the locations of commands which are discovered at build-time you should note that to find them the executables need to be installed. This might not be the case if you are building in a chroot using something like mock. You should ensure you adjust your build-dependencies appropriately if you need those commands! Note also that on Solaris things might be in really weird places and those might not be found, you might need to adjust the search paths appropriately, that's explained in the CMake documentation.

Macro Description Value
HAS_PROC Specifies whether /proc will be there. Yes on Linux, no otherwise.
BOOTCOMP Specifies the name of the boot component. "boot" on Linux and Solaris, "macboot" on MacOSX.
PERL, PERL_EXECUTABLE The location of the perl binary. Discovered at build-time
PERL_INSTALLDIRS Specifies what type of Perl install is required. Either "site" or "vendor"
PERL_ARCHDIR The directory for installing architecture-specific Perl modules. Discovered at build-time
PERL_LIBDIR The directory for installing architecture-independent Perl modules. Discovered at build-time
SHELL The location of the bash binary Discovered at build-time
EGREP The location of the egrep binary Discovered at build-time
SED The location of the sed binary Discovered at build-time
SORT The location of the sort binary Discovered at build-time
LCFGOS The operating system name. Taken directly from CMAKE_SYSTEM_NAME
LCFGARCH The processor architecture of the system. Taken from CMAKE_SYSTEM_PROCESSOR with cleanup (e.g. i586 and i686 would both become i386)

Linux Specific

Note that a lot of these variables are found using the lsb_release command. If you do not have LSB (Linux Standard Base) available for your platform you will have to do without these variables. If you want access to them for RPMs built with mock you will need to add lsb as a build requirement.

Macro Description Value
LSB_VERSION The version of LSB available. e.g. :core-3.1-ia32:core-3.1-noarch:graphics-3.1-ia32:graphics-3.1-noarch
DISTRIB_ID The id of the Linux distributor. e.g. FedoraCore or ScientificSL
DISTRIB_DESCRIPTION The description of the Linux distribution. e.g. Scientific Linux SL release 5.2 (Boron)
DISTRIB_RELEASE The release number of the Linux distribution. e.g. 5.2
DISTRIB_CODENAME The codename of the Linux distribution release. e.g. Boron
OS_VERSION The LCFG short name for the distribution. fc3, fc5, fc6, sl5, etc..
OS_RELEASE The major number of the Linux distribution release. 3, 5, 6, etc..
LIBDIR Library installation location Either /usr/lib or /usr/lib64 depending on your distribution and architecture.
LIBSECURITYDIR PAM library installation location. Either /lib/security or /lib64/security depending on your distribution and architecture.

MacOSX Specific

We do not fully support MacOSX at the moment so there is only a very short list of specific macros available.

Macro Description Value
OSX_VERSION The minor version of the release. For 10.4.7 this would be 4

Miscellaneous

These are mainly provided for reasons of backwards compatibility or because they are used by lots of different components.

Macro Description Value
MSG A standard message which can be added to the top comment section of configuration files and scripts. " ** Generated file : do not edit **"
CONFIGDIR A per-component directory to hold various generated configuration files. ${LCFGCONF}/${LCFG_NAME}
ICONDIR A per-component directory to hold various images. ${LCFGDATA}/${LCFG_NAME}/icons
SCRIPTDIR A per-component directory to hold various scripts. ${LCFGDATA}/${LCFG_NAME}/scripts
LCFG_TMPLDIR A per-component directory to hold templates. ${LCFGDATA}/${LCFG_NAME}