NAME

    LCFG::Build::Utils - LCFG software building utilities

VERSION

    This documentation refers to LCFG::Build::Utils version 0.9.30

SYNOPSIS

    my $dir = q{.};

    my $spec = LCFG::Build::PkgSpec->new_from_metafile("$dir/lcfg.yml");

    LCFG::Build::Utils::find_and_translate( $spec, $dir );

    LCFG::Build::Utils::generate_cmake( $spec, $dir );

DESCRIPTION

This module provides a suite of utilities to help in building packages from LCFG projects, particularly LCFG components. The methods are mostly used by tools which implement the LCFG::Build::Tool base class (e.g. LCFG::Build::Tool::Pack) but typically they are designed to be generic enough to be used elsewhere.

SUBROUTINES/METHODS

translate_macro( $spec, $macro, $extra )

This is used by all other translator subroutines in this module to do the actual work of replacing macros with their values.

This takes a macro name and translates it using the information stored in the LCFG build metadata package specification. You can also provide a reference to an extra hash of keys and values to be searched. You should note that this subroutine takes a macro name and not the complete macro, i.e. it is FOO not @FOO@. An unknown macro will result in the subroutine returning undef. To help in this case a warning will be printed to STDERR.

For backwards compatibility, if the macro is not found in the package specification it will also look in the LCFG default package install locations list (see /usr/share/lcfgbuild/lcfg_config.yml for details). It is STRONGLY RECOMMENDED that you do NOT rely on this location list as it will inconvenience downstream users who want to repackage for different Operating Systems.

For backwards compatibility the macros are looked up in a mapping list which supports the old names. Any macros not beginning with the LCFG_ sub-string should be considered deprecated as they will be phased out in a future release. See /usr/share/lcfgbuild/mapping_config.yml for a full list of supported macro mappings.

translate_string( $spec, $string, $style, $extra )

This takes a string and finds all the macros embedded within and gets them translated. Two styles of macros are supported cmake which is like ${FOO} and the standard autoconf style which is @FOO@. Specifying anything other than cmake will result in autoconf style substitutions. You can provide a reference to an extra hash which will be passed through to translate_macro().

Note that an unknown macro will NOT be removed from the string, a warning is printed to STDERR when this occurs.

translate_file( $spec, $in, $out, $extra )

This takes the names for the input file and output file and, optionally, a reference to a hash of extra key/values to be passed through to translate_macro(). All macros in the file will be translated as described above, currently only autoconf-style macros are supported.

find_trans_files( $dir, @translate )

This takes the name of a directory in which to search and a list of files and file globs to match. A hash of the files found is returned. Note that the paths will all be relative to the specified directory and not absolute.

Unless you search for files with a .cin or .in suffix, which are treated specially, the keys and values will be the same. In the special cases the keys will be the path to the input files and the values will be the file names with the .in or .cin file extension removed.

If you specify a particular file name and it is missing a warning will be printed but this is not a fatal error.

find_and_translate( $spec, $dir, $remove )

This is a wrapper which combines find_trans_files() with the application of the translate_file() subroutine on each file discovered in the project directory. If you set the remove parameter to a true value then, if the input and output file names do not match, the input files will be removed after the translation has occurred. This can be useful if you want to generate a pristine tar file which does not contain *.cin files.

generate_cmake( $spec, $dir, $force )

This generates all the necessary CMake files for building an LCFG project. This will create a simple CMakeLists.txt file unless you need extra power in which case you can write your own and that will be used instead. You can set the force variable to a true value to overwrite any existing CMake file, if you wish. A second file is created, named lcfg.cmake, which contains all the necessary functions and macros for building an LCFG project.

$tarfile = generate_srctar( $tarname, $srcdir, $resultsdir )

Takes the name of a tarfile to generate and packages up everything in the specified source directory. The generated tar file will be placed into the results directory. If either of the the source or results directories are not specified then the current working directory will be used. This returns the full path to the generated tar file.

CONFIGURATION AND ENVIRONMENT

Some of the routines use template files, by default it is assumed that the standard template directory is /usr/local/share/lcfgbuild/templates on MacOSX and /usr/share/lcfgbuild/templates on all other platforms. You can override this using the LCFG_BUILD_TMPLDIR environment variable. If you have done a local (i.e. non-root) install of this module then this will almost certainly be necessary.

DEPENDENCIES

This module uses a number of other Perl modules. For generating compressed tar files you will need Archive::Tar and IO::Zlib. For generation of the CMake files you will need the Perl Template Toolkit. For macro translation you will need YAML::Syck. For finding the translation files you will need File::Find::Rule.

Although not a requirement for this module, in most cases if you want to build the resulting software you will need CMake, version 2.6.0 or greater, installed on your build machine.

PLATFORMS

This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.

Fedora12, Fedora13, ScientificLinux5, ScientificLinux6, MacOSX7

BUGS AND LIMITATIONS

There are no known bugs in this application. Please report any problems to bugs@lcfg.org, feedback and patches are also always very welcome.

AUTHOR

    Stephen Quinney <squinney@inf.ed.ac.uk>

LICENSE AND COPYRIGHT

    Copyright (C) 2008 University of Edinburgh. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.