skip to main content

LCFG Build Tools : LCFG CMake Macros

CMake provides all the functionality required to build source code and install the generated output into the desired filesystem hierarchy. As such we could require all package maintainers to write their own CMake code. It is clear, however, that there is a large amount of duplication in requirements so it makes sense to create a library of CMake macros which can be used to carry out the common tasks. This suggests that it should be possible to take things another conceptual level higher - a common task will be to call a set of macros which carry out common tasks. Taken to the extreme this should mean that a totally standard LCFG component should require no specific CMake code at all.

This page documents the LCFG CMake macros which are available for building packages which are managed with the LCFG build tools. For examples of how to use the various macros listed below you should read the CMake Recipes page.

lcfg_add_component(compname)

For a standard LCFG component a call to this macro is all that is required to build the source and install it into the correct locations. It does no work for itself but rather calls the necessary macros from the list below. Basically it does this:

  lcfg_translate()
  lcfg_add_comp_script(${compname})
  lcfg_add_comp_pod(${compname})
  lcfg_add_schema(${compname} ${LCFG_SCHEMA})
  lcfg_add_logrotate()
  lcfg_add_templates()
  lcfg_add_nagios_support()

It also creates the empty CONFIGDIR directory which many components use for storing generated files.

lcfg_translate()

This macro will do the substitution of the @FOO@ style variables in source files. The list of files on which to carry out substitution is built at source packaging time NOT build time. The list is controlled through the translate option in the LCFG build tools metadata file. Typically this will be files matching the "*.cin" or "*.in" glob. To carry out the translation it uses the CMake CONFIGURE_FILE

lcfg_add_comp_script(compname)

If a script exists for this component name (e.g. for the LCFG foo component there would need to be a script named "foo") this macro will install it into the correct location (LCFGCOMP) with the correct permissions so that it is executable. Note that a missing file is not an error.

lcfg_add_schema(schema_name schema_ver)

If a schema file ("foo.def" for the component foo) exists then it will be installed into the directories specified by LCFGSERVERDEF and LCFGCLIENTDEF. Note that a missing schema file is not an error. If the version is specified (not an empty string) then it will be installed as foo-version.def otherwise it will be installed as foo.def.

pod_strip(in out)

This macro takes the name of a file from which you want to take a copy of all the pod (Perl-style) documentation. It also takes the name of the file into which that pod should be placed. To do this it uses a tool named podselect which is part of the standard Perl core distribution.

lcfg_add_man(manfile section)

Takes the name of a man page and installs it into the correct manual location within the base directory LCFGMAN for the specified section.

lcfg_add_pod(podfile manfile section)

Takes a pod file and installs it into the LCFGPOD directory. It also uses the pod2man tool to convert it into a manual page and then calls the lcfg_add_man macro to install that generated page into the correct location. Note that it is not an error if the specified input pod file does not exist.

lcfg_add_comp_pod(compname)

This is just a convenience wrapper around the the lcfg_add_pod macro. It allows you to just specify the name of the component and the relevant pod file will be installed. For example, the LCFG foo component would have a file named foo.pod which would installed as "LCFGPOD/foo.pod" and also as the "lcfg-file" manual page. The manual section into which it is installed is controlled by LCFGMAN.

lcfg_add_perl_module(file modpath)

This macro can be used to install a Perl module into the correct location. You need to specify the file name and the Perl module name since it is not always possible to deduce one from the other. The location into which a module is installed is controlled by setting the CMake cache variable PERL_INSTALLDIRS to either "site" (which is the default) or "vendor" (which is normal for software packages such as RPM). It is essential to already have Perl installed at this point otherwise it is not possible to discover the correct installation locations.

lcfg_add_perl_tree(dirname)

This macro will find all Perl modules (files matching the "*.pm" glob) within the specified directory. It then deduces the Perl module from the path name relative to the base directory by converting the directory separator into the standard double-colon Perl module name separator and removing the suffix. This is typically what is required. Note that running this on the top-level project directory might work but it is not guaranteed. In that case, you are probably better off adding each module manually with the lcfg_add_perl_module macro. Or, even better, moving all your Perl modules into a separate directory.

lcfg_add_program(location binfile mansect [podstrip])

This macro will install an executable, of any type, into the specified location. If you specify the 4th argument as the string "podstrip" then it will use the pod_strip and lcfg_add_pod macros to strip out the pod from the file, convert it to a manpage and install both. The mansect variable controls the section into which the generated manual page is installed. Typically you will not call this macro but will use either lcfg_add_bin or lcfg_add_sbin which are more convenient, they are documented below.

lcfg_add_bin(binfile [podstrip])

This will install an executable into the LCFGBIN directory. If you specify the, optional, second argument as the string "podstrip" then the pod contained within the file will be stripped and converted into a manual page, the manual page would be installed into section 1 (General commands). This is a convenience wrapper around the lcfg_add_program macro.

lcfg_add_sbin(binfile [podstrip])

This will install an executable into the LCFGSBIN directory. If you specify the, optional, second argument as the string "podstrip" then the pod contained within the file will be stripped and converted into a manual page, the manual page would be installed into section 8 (System administration commands and daemons) This is a convenience wrapper around the lcfg_add_program macro.

lcfg_add_logrotate()

If a file named "logrotate" exists in the package source directory it will be installed into the directory LCFGDATA/LCFG_NAME. This is a template file used to generate the logrotate configuration for the component which should be used in preference to the template shipped along with the LCFG ngeneric component. Note that it is not an error if this file does not exist.

lcfg_add_template(tmpl1 [tmpl2] ...)

This will install the specified templates into the per-component LCFG_TMPLDIR directory.

lcfg_add_templates()

If you have a "templates" sub-directory for your project then this will install any files in that directory matching "*.tmpl" or "*.tt" into the per-component LCFG_TMPLDIR directory. For backwards compatibility it will also install a file with the name "template" if it is found in the top-level directory for the project. As usual, these template files can be named with a "*.cin" suffix so that they are pre-processed before packaging. This macro is automatically called by lcfg_add_component so you do not normally need to do so manually.

lcfg_add_nagios_module(modpath)

This macro takes the path to an LCFG nagios Perl module (e.g. nagios/foo.pm) and installs it into the correct location. Currently that is hardwired to LCFG/Monitoring/Nagios/Translators within the standard Perl module tree.

lcfg_add_nagios_support()

If you have a "nagios" sub-directory for your project then this macro will find all Perl modules matching "*.pm" and use lcfg_add_nagios_module to install them into the correct location. As usual, these nagios module files can be named with a "*.cin" suffix so that they are pre-processed before packaging. This macro is automatically called by lcfg_add_component so you do not normally need to do so manually.