NAME

LCFG::Build::Skeleton - LCFG software package generator

VERSION

This documentation refers to LCFG::Build::Skeleton version 0.0.4

SYNOPSIS

my $skel = LCFG::Build::Skeleton->new_with_options();

$skel->query_user();

$skel->create_package();

DESCRIPTION

This module handles the creation of the skeleton of an LCFG software project. Typically, it prompts the user to answer a set of standard questions and then generates the necessary files from a set of templates. These generated files include the necessary metadata, build files and, for LCFG components, example code. It can also add the new project into the revision-control system of choice.

ATTRIBUTES

If using the new_with_options() method then any of the attributes can be set from the commandline (or, more precisely, via the @ARGV list). An attribute named foo is accessible as the commandline option --foo. If it is a boolean value then the module will also support the --no-foo form to turn off a feature (e.g. --no-gencmake).

name

The name of the project. Note that in the case of an LCFG component this should be foo NOT lcfg-foo.

abstract

A short description of the project. If this is an LCFG component the default value suggested to the user is "The LCFG $name component".

author_name

The name of the author (i.e you!). The default is the string stored in the gecos field of the passwd entry.

author_email

The email address for the author. The default is built from the current username and domain name.

lcfg_component

This controls whether the generated project is an LCFG component. This is a yes/no answer and it defaults to "yes" (it is handled in the same way as a boolean value on the command line).

lang

The language which will be used, this is either "perl" or "shell". This only really has an affect if you are creating an LCFG component.

rcs

Which revision-control system you intend to use for the project. Currently only "CVS" and "None" are supported. You will need the relevant LCFG::Build::VCS helper module installed for this to work.

platforms

The comma-separate list of platforms which are supported by this code (e.g. ScientificLinux5).

license

The license under which the source code can be distributed. This defaults to "GPLv2".

restart

This controls whether, if this is an LCFG component, should it be restarted after package upgrade if the component is already running. This is a yes/no answer and it defaults to "yes" (it is handled in the same way as a boolean value on the command line).

gencmake

This controls whether the LCFG CMake infrastructure will be used to build the project. This is a yes/no answer and it defaults to "yes" (it is handled in the same way as a boolean value on the command line).

genchangelog

This controls whether or not to generate the project changelog from the revision-control commit logs. This is a yes/no answer and it defaults to "no" (it is handled in the same way as a boolean value on the command line).

checkcommitted

This controls whether the revision-control tools should check that all files are committed before making a new release. This is a yes/no answer and it defaults to "yes" (it is handled in the same way as a boolean value on the command line).

interactive

This controls whether the query_user() method will actually interact with the user or just store the values taken from the defaults file and any commandline options. This is a boolean value which defaults to false (zero).

force

This controls whether an existing project directory will be removed if the name matches that required for the new skeleton project. This is a boolean value which defaults to false (zero).

configfile

This is the configuration file which is used to store the defaults between calls to the lcfg-skeleton tool. Normally you should not need to modify this and it defaults to ~/.lcfg/skeleton/defaults.yml.

tmpldir

This is the directory into which local versions of templates should be placed. Normally you should not need to modify this and it defaults to ~/.lcfg/skeleton/templates/. For reference, the standard templates are normally stored in /usr/share/lcfgbuild/templates.

SUBROUTINES/METHODS

new(%hash_of_options)

Creates a new object of the LCFG::Build::Skeleton class. Values for any attribute can be specified in the hash of options.

new_with_options(%hash_of_options)

Creates a new object of the LCFG::Build::Skeleton class and if any attribute values were specified on the command line those will be set in the returned instance. Values for any attribute can be specified in the hash of options.

query_user()

This prompts the user to answer a set of standard questions (except when the interactive option is set to false) and stores the answer in the object attributes. If an invalid value is given the user will be prompted again. For convenience, the answers are also stored in a file and used as the defaults in the next run of the command. The default value is shown in the prompt between square-brackets and just pressing return is enough to accept the default.

create_package()

This uses the skeleton object attribute values to generate the skeleton tree of files for the new project. If a project directory of the desired name already exists you will need to move it aside, choose a different project name or set the force attribute to true.

store_answers()

This is primarily intended for internal usage. It will store the values of the answers given be the user (except the project name and abstract) so that they can be used as defaults in future calls to the lcfg-skeleton command. The default values are stored in the file name specified in the configfile attribute, that defaults to ~/lcfg/skeleton/defaults.yml

get_config_from_file($filename)

This is primarily intended for internal usage. This retrieves the configuration data from the specified file, which must be in YAML format, and returns it as a reference to a hash.

CONFIGURATION AND ENVIRONMENT

The default values for the answers are stored in the file referred to in the configfile attribute. This is normally ~/.lcfg/skeleton/defaults.yml but that can be overridden by the user. If the file does not exist it will be created when this tool is first run.

It is possible to override any of the standard templates used to generate the skeleton project by placing your own version into the directory referred to in the tmpldir attribute. This is normally ~/.lcfg/skeleton/templates/ but that can be overridden by the user. For reference, the standard templates are normally stored in /usr/share/lcfgbuild/templates.

DEPENDENCIES

This module is Moose powered and uses MooseX::Getopt to provide a new_with_options() method for creating new instances from the options specified in @ARGV (typically via the commandline). The YAML::Syck module is used to parse the file which holds the default values for the answers. You will also need the List::MoreUtils and UNIVERSAL::require modules.

The Perl Template Toolkit is required to generate the files for the skeleton project.

The following LCFG Build Tools modules are also required: LCFG::Build::PkgSpec(3), LCFG::Build::VCS(3) and VCS helper modules.

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.

FedoraCore5, Fedora6, ScientificLinux5

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

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