/ 
LCFG-Build-VCS-0.3.9
River stage one • 2 direct dependents • 2 total dependents
/ LCFG::Build::VCS

NAME

LCFG::Build::VCS - LCFG version-control infrastructure

VERSION

This documentation refers to LCFG::Build::VCS version 0.3.9

SYNOPSIS

my $vcs = LCFG::Build::VCS::CVS->new();

$vcs->genchangelog();

if ( $vcs->checkcommitted() ) {
  $vcs->tagversion();
}

DESCRIPTION

This is a suite of tools designed to provide a standardised interface to version-control systems so that the LCFG build tools can deal with project version-control in a high-level abstract fashion. Typically they provide support for procedures such as importing and exporting projects, doing tagged releases, generating the project changelog from the version-control log and checking all changes are committed.

This is an interface, you should not attempt to create objects directly using this module. You will need to implement a sub-class, for example LCFG::Build::VCS::CVS. This interface requires certain attributes and methods be specified within any implementing sub-class, see below for details. For complete details you should read the documentation associated with the specific sub-class.

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

ATTRIBUTES

module

The name of the software package in this repository. This is required and there is no default value.

workdir

The directory in which the version-control system commands should be carried out. This is required and if none is specified then it will default to '.', the current working directory. This must be an absolute path but if you pass in a relative path coercion will automatically occur based on the current working directory.

binpath

The path to the version-control tool. This is required and it is expected that any module which implements this interface will set a suitable default command name.

quiet

This is a boolean value which controls the quietness of the version-control system commands. By default it is false and commands, such as CVS, will print lots of extra stuff to the screen.

dryrun

This is a boolean value which controls whether the commands will actually have a real effect or just print out what would be done. By default it is false.

logname

The name of the logfile to which information should be directed when doing version updates. This is also the name of the logfile to be used if you utilise the automatic changelog generation option. The default file name is 'ChangeLog'.

SUBROUTINES/METHODS

This module provides a few fully-implemented methods which are likely to be useful for all sub-classes which implement the interface.

gen_tag($version)

Generate a tag based on the package name and the specified version. Tags are generated from the module name attribute and the version information passed in by replacing any hyphens or dots with underscores and joining the two fields with an underscore. For example, lcfg-foo and 1.0.1 would become lcfg_foo_1_0_1. If no version is specified then just the module name will be used.

update_changelog($version)

This will add a standard-format release tag entry to the top of the change log file.

mirror_file( $sourcedir, $targetdir, $reldir, $basename )

This will copy a file from the source directory to the target directory. The relative path of the file (within the source directory) must be split into the relative directory path and filename. Effort is made to preserve the mode and, in the case of files, atime and mtime. This is used by various modules in the export_devel() method to mirror the project directory into a build directory.

logfile()

This is a convenience method which returns the full path to the logfile based on the workdir and logname attributes.

As well as the methods above, any class which implements this interface MUST provide methods for:

checkcommitted()

Test to see if there are any uncommitted files in the project directory. Note this test does not spot files which have not been added to the version-control system. In scalar context the subroutine returns 1 if all files are committed and 0 (zero) otherwise. In list context the subroutine will return this code along with a list of any files which require committing.

genchangelog($version)

This method will generate a changelog (the name of which is controlled by the logname attribute) from the log kept within the version-control system.

store_version($version)

This method can be used to store the version string (e.g. 1.2.3) into a file named lcfg-build-id.txt in the top-level directory for the project. This is useful if you need to have eacy access to the version string in build scripts.

tagversion($version)

This method is used to tag a set of files for a project at a particular version. It will also update the changelog appropriately. The tag name is generated using the gen_tag() method, see below for full details.

run_cmd(@args)

A method used to handle the running of commands for the particular version-control system. This is required for systems like CVS where shell commands have to be executed. Not all modules will need to implement this method as they may well use a proper Perl module API (e.g. subversion).

export( $version, $dir )

Exports the source code for the project tagged at the specified release. The second argument specifies the directory into which the exported project directory will be placed.

export_devel( $version, $dir )

Exports the current development version of the source code for the project (i.e. your working copy). The second argument specifies the directory into which the exported project directory will be placed.

import_project( $dir, $version, $message )

Imports a project source tree into the version-control system.

checkout_project( $version, $dir )

Does a check-out from the version-control system of the project tagged at the specified version. Unlike the export() method this checked-out copy will include the files necessary for the version-control system (e.g. CVS or .svn directories).

DEPENDENCIES

This module is Moose powered. It also requires DateTime and IPC::Run.

SEE ALSO

LCFG::Build::PkgSpec, LCFG::Build::VCS::CVS, LCFG::Build::VCS::None, LCFG::Build::Tools

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, FedoraCore6, 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-2019 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.