NAME

LCFG::Build::PkgSpec - Object-oriented interface to LCFG build metadata

VERSION

This documentation refers to LCFG::Build::PkgSpec version 0.3.0

SYNOPSIS

   my $spec = LCFG::Build::PkgSpec->new( name    => "foo",
                                         version => "0.0.1" );

   $spec->schema(2);

   $spec->save_metafile("./lcfg.yml");

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

   print "Package name is: " . $spec2->name . "\n";

   $spec2->update_major();

   $spec->save_metafile("./lcfg.yml");

DESCRIPTION

This class provides an object-oriented interface to the LCFG build tools metadata file. All simple fields are available through attribute accessors. Specific methods are also provided for querying and modifying the more complex data types (e.g. lists and hashes).

This class has methods for carrying out specific procedures related to tagging releases with the LCFG build tools. It also has methods for handling the old format LCFG build configuration files.

More information on the LCFG build tools is available from the website http://www.lcfg.org/doc/buildtools/

ATTRIBUTES

name: This is the name of the project or LCFG component. In the case of the component think of it as the "foo" part of "lcfg-foo". When an object is created this field MUST be specified, there is no default value.
base: This is only really meaningful in terms of LCFG components, in which case it is the "lcfg" part of "lcfg-foo" or the "dice" part of "dice-foo". This is optional and the default value is an empty string.
abstract: This is a short description of the project, it is optional and there is no default.
version: This is the version of the project, it is required and if not specified at object creation time it will default to '0.0.0'. Due to backwards compatibility reasons this version must be in 3 integer parts separated with the period character. Any attempt to set it otherwise will result in an error being thrown.
release: This is the release number for a project and is directly related to the release field used for RPMs and Debian packages. It is optional and defaults to 1. If used, the first character of the release field MUST be an integer, after that you can put in whatever you like.
schema: This is only really meaningful in terms of LCFG components. It is the schema number of the defaults file which specifies the details for the supported resources. It is optional and will default to 1.
group: This is the software group into which this project best fits, it is mainly provided for RPM specfile generation support (e.g. "Development/Libraries"). It is optional and has no default value.
vendor: This matches the "Vendor" field used in RPMs, it is optional and has no default value.
orgident: This is an identifier for your organisation which is based on the reversed form of your domain name, com.example or org.example for example. No validation is done to check if this is the reversal of a real domain name, you can use whatever you want, the default value is org.lcfg. This is used by the pkgident method as part of the process of generating MacOSX packages.
license: This is the short string used in RPMs to specify the license for the project. This field is optional and there is no default value.
date: This is used to show the date and time at which the project version was last altered. If not specified it will default to the current date and time in the format 'DD/MM/YY HH:MM:SS'.
author: This is the name (or list of names) of the project author(s). The default value is an empty list. You should note that calling this accessor with no arguments returns a list not a scalar value. See below for convenience methods provided for accessing and managing the information contained with the list.
platforms: This is the list of supported platforms for the project. The default value is an empty list. You should note that calling this accessor with no arguments returns a list not a scalar value. See below for convenience methods provided for accessing and managing the information contained with the list.
vcs: This is a reference to a hash containing details of the version control system used for the project. This is optional and defaults to an empty hash. See below for convenience methods provided for accessing and managing the information contained with the hash.

SUBROUTINES/METHODS

fullname: Returns the full name of the package, if the 'base' attribute is specified then this will be a combination of base and package name separated with a hyphen, e.g. 'lcfg-foo'. If no base is specified then this is just the package name, e.g. 'foo'.
deb_name: Returns a name for the package which is safe for use as a Debian package name. Debian package names must not contain the _ (underscore) character so those are replace with hyphens, also by convention the name is lower-cased. Any invalid characters (not in the set [a-zA-Z0-9-]) are simply removed.
deb_version: Returns a version for the package which is safe for use with Debian packages. Typically this will be identical to the standard version string. Debian package versions must only contain characters in the set [a-zA-Z0-9~.+-], any invalid characters are simply removed
deb_tarname: Returns the name of the debian source package tarfile which would be generated for this version of the package. This combines the full name and the version, for example, lcfg-foo_1.0.1-1.debian.tar.gz. Note that the LCFG build tools will only actually generate this file when a project contains a debian sub-directory.
deb_dscname: Returns the name of the debian source control (dsc) file which would be generated for this version of the package. This combines the full name and the version, for example, lcfg-foo_1.0.1-1.dsc. Note that the LCFG build tools will only actually generate this file when a project contains a debian sub-directory.
pkgident: This returns a string formed by the concatenation of the orgident and fullname values, joined with a period character, com.example.lcfg-client for example. This is used as the identifier name for MacOSX packages.
rpmspec_name: This returns the name of the RPM specfile for the project. This is just based on the full name with a .spec suffix (e.g. lcfg-foo.spec).
tarname: Returns the standard LCFG name of the tarfile which would be generated for this version of the package. This combines the full name and the version, for example, lcfg-foo_1.0.1.orig.tar.gz
new_from_metafile($file): Create a new object which represents the LCFG build metadata stored in the YAML file.
save_metafile($file): Save the object data into the LCFG metadata file.
new_from_cfgmk($file): Create from the old-style LCFG config.mk a new object which represents the LCFG build metadata.
perl_version: This returns the package version as a string in a style which is safe for use in Perl modules. If this is a development release the dev suffix is replaced with the value of the release. This is done because Perl versions are not permitted to contain non-numeric characters.
get_major: Get just the major (first) part of the package version.
get_minor: Get just the minor (middle) part of the package version.
get_micro: Get just the micro (last) part of the package version.
update_major: Increment by one the first (largest) part of the version. This will also reset the second and third parts of the version to 0 (zero) and the release field to 1. For example, version 1.2.3 would become 2.0.0 and the release field would go from 5 to 1.
update_minor: Increment by one the second (middle) part of the version. This will also reset the third part of the version to 0 (zero) and the release field to 1. For example, version 1.2.3 would become 1.3.0 and the release field would go from 5 to 1.
update_micro: Increment by one the third (smallest) part of the version field. This will also reset the release field to 1. For example, version 1.2.3 would become 1.2.4 and the release field would go from 5 to 1.
update_date: Update the date attribute to the current time, this is set to the format 'DD/MM/YY HH:MM::SS'. You should not normally need to call this method, it is called at the end of the update_micro, update_minor and update_major methods to show when the version update occurred.
update_release: This method updates the release field by incrementing the value. If it was not previously defined then it will be set to one.
dev_version: This method converts the version to the development format. If it is not already present an .dev string is appended to the version string along with the value of the release field. The release field is also incremented. For example, the first dev version for 1.2.3 would be 1.2.3.dev1 and the second would be 1.2.3.dev2.
has_platform: A method for checking if an author is already in the list of authors. Takes a subroutine, e.g. sub { m/foo/ }, with the $_ variable set to the item value.
add_author: A convenience method for adding new authors to the list of project authors. Note that this does not prevent an author being added multiple times.
has_platform: A method for checking if a platform is already in the list of supported platforms. Takes a subroutine, e.g. sub { m/foo/ }, with the $_ variable set to the item value.
add_platform: A convenience method for adding new platforms to the list of supported platforms for this project. Note that this does not prevent a platform being added multiple times.
exists_in_vcsinfo($key): A convenience method to see if a particular key exists in the version-control information.
ids_in_vcsinfo: A convenience method to get a list of all the keys in the version-control information.
get_vcsinfo($key): A convenience method to get the data associated with a particular key in the version-control information.
set_vcsinfo($key, $value): A convenience method to set the data associated with a particular key in the version-control information.
exists_in_buildinfo($key): A convenience method to see if a particular key exists in the build information.
ids_in_buildinfo: A convenience method to get a list of all the keys in the build information.
get_buildinfo($key): A convenience method to get the data associated with a particular key in the build information.
set_buildinfo($key, $value): A convenience method to set the data associated with a particular key in the build information.

DEPENDENCIES

This module is Moose powered. It also requires Data::Structure::Util, DateTime and if you want to parse and write LCFG metadata files you will need YAML::Syck.

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.

ScientificLinux5, ScientificLinux6

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

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

To install LCFG::Build::PkgSpec, copy and paste the appropriate command in to your terminal.

cpanm

cpanm LCFG::Build::PkgSpec

CPAN shell

perl -MCPAN -e shell
install LCFG::Build::PkgSpec

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)