NAME

    LCFG::Build::VCS::SVN - LCFG build tools for subversion version-control

VERSION

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

SYNOPSIS

    my $dir = ".";

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

    my $vcs = LCFG::Build::VCS::SVN->new( module  => $spec->fullname,
                                          workdir => $dir );

    $vcs->genchangelog();

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

DESCRIPTION

This is part of 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.

This module implements the interface specified by LCFG::Build::VCS. It provides support for LCFG projects which use the subversion version-control system. Facilities are available 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.

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 svn 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 name of the svn executable, by default this is svn.

quiet

This is a boolean value which controls the quietness of the subversion commands. By default it is false and commands, such as svn, will print some 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

The following class methods are available:

new

Creates a new instance of the class.

auto_detect($dir)

This method returns a boolean value which indicates whether or not the specified directory is part of a checked out working copy of a subversion repository.

The following instance methods are available:

get_info($key)

This method can be used to query any information (for example URL or Repository Root) which is available in the output of the subversion info command. The key has had the whitespace stripped, for example, "Last Changed Author" becomes "LastChangedAuthor". If you request information for a key which is not present this method will die.

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()

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. For subversion the svn2cl(1) command is used.

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. Tags are generated using the gen_tag() method, see below for details.

gen_tag($version)

Tags are generated from the name and version details 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.

run_cmd(@args)

A method used to handle the running of commands for the particular version-control system. Although we could have used the proper perl API for subversion it was a lot quicker to just wrap the command line tools. This method honours the dry-run setting and when a dry-run has been requested will print out the command and not execute.

For example:

       $vcs->run_cmd( 'update', $workingcopydir );

run_infocmd(@args)

This is similar to run_cmd( ) except that it will always run the command. This is for executing commands which just gather information and do not modify the repository or working copy.

       $vcs->run_infocmd( 'ls', '-R', $repos_url );

export( $version, $dir )

This will export a particular tagged version of the module. You need to specify the target "build" directory into which the exported tree will be put. The exported tree will be named like "modulename-version". For example:

  my $vcs = LCFG::Build::VCS::SVN->new(module => "lcfg-foo");
  $vcs->export( "1.2.3", "/tmp" );

Would give you an exported tree of code for the lcfg-foo module tagged as lcfg_foo_1_2_3 and it would be put into /tmp/lcfg-foo-1.2.3/

Returns the name of the directory into which the tree was exported.

export_devel( $version, $dir )

This is similar to the export method. It takes the current working copy tree for a module and exports it directly to another tree based in the specified target "build" directory.

  my $vcs = LCFG::Build::VCS::SVN->new(module => "lcfg-foo");
  $vcs->export_devel( "1.2.3_dev", "/tmp" );

Would give you an exported tree of code for the lcfg-foo module directory and it would be put into /tmp/lcfg-foo-1.2.3_dev/

Returns the name of the directory into which the tree was exported.

import_project( $dir, $version, $message )

Imports a project source tree into the version-control system. You need to specify the version for the initial tag. Optionally you can specify a message which will be used.

logfile()

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

DEPENDENCIES

This module is Moose powered and it depends on LCFG::Build::VCS. You will need a working svn executable somewhere on your system and a subversion repository for this module to be in anyway useful.

SEE ALSO

LCFG::Build::PkgSpec, 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-2013 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.

cpanm LCFG::Build::VCS

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