SVN::Friendly - user friendly front end to Subversion bindings
Svn::Friendly presents the SWIG bindings for the Subversion API in a Perl friendly format.
It was developed because the raw SWIG bindings (available on CPAN via Alien::SVN) requires a deep reading of the SVN C API documentation and a lot of research, trial and error to figure out how the various C API constructs and data types show up in the Perl interface. This essentially meant that the Subversion Perl API was largely usable only to Perl programmers who also had a reading knowledge of C, familiarity with SWIG, and the time to spend doing the necessary research and testing.
For an in depth discussion of how SVN::Friendly makes the Perl bindings to subversion more user friendly ,see SVN::Friendly::Client.
Main modules corresponding to major subsystems in the subversion API:
SVN::Friendly::Client
Data and operations needed by a subversion client. A subversion client is responsible for extracting information from a repository, scheduling changes and synchronsizing working copies and repositories
SVN::Friendly::Config
Configuration information used by subversion clients and repositories.
SVN::Friendly::Repos
Data and operations for administering a subversion repository. This module may be used at present to create repositories and retrieve basic information about the repository: root, uuid, hook file names, and so on. This is only a small part of the repository features, so more work is needed.
Utility files that may be of interest
SVN::Friendly::Exceptions
stores exception class definitions used by SVN::Friendly and provides a helper method for those needing to override the default exception handling mechanism.
SVN::Friendly
SVN::Friendly::Dates
Stores routines for converting apache dates into a format usable by Perl routines.
For planned future developments, see "ROADMAP".
This distribution requires only two additional non-core packages.
Subversion's SWIG-Perl bindings.
Debian users can get thse recompiled via the package libsvn-perl. The stable version is currently 1.5 on lenny.
If you have a compiler on your system, you can also get them via CPAN. Download the Alien::SVN module. The CPAN version will work with the 1.6 API and below. Finally, if you want the latest bleeding edge bindings, you can visit the Apache Foundation, download sources, and compile your own. See http://subversion.apache.org/source-code.html
Exception::Lite
A light weight exception handling class with smart stack tracing and localization support. This module is used to generate exceptions. Exception::Lite depends only on core modules.
SVN::Friendly is composed so as to be backwards compatbile with subversion 1.1 and will continue to be so. All methods without a major_minor suffix use API method calls that are compatible with subversion 1.1 binaries.
To date, it is written to be forwards compatible up to subversion 1.7 and the intent is continue to add new releases as subversion does.
However, ...
You should not assume that downloading and installing SVN::Friendly will automatically make a computer with subversion 1.1 installed start acting like subversion 1.7, or vice versa.
The actual behavior of this distribution depends on three factors:
* the version of Alien::SVN you have installed
* the subversion release running on your computer
* the version of your working copy and repository
On a particular computer accessing a particular repository, the features available to you will be the least of the four releases listed above (Alien::SVN, system subversion, working copy version, and repository version).
SVN::Friendly depends on the SWIG-Perl bindings developed by the Subversion team. The Perl binding prepare Perl programs for linking to the subversion binaries at runtime. They also define the symbols available for use in a Perl program. Your program can only recognize functions and constants from the API against which Alien::SVN is compiled. If you try to use constants and methods from newer versions of Perl, strict and warnings will complain.
strict
warnings
At runtime, your Perl/Subversion application will link to the system subversion (the one you use on the command line) and use that to make function calls. This is true even with Alien::SVN which downloads the 1.6.12 bindings for the purpose of compiling the Perl bindings. If your runtime system is older than 1.6, you will only be able to use the portion of the SWIG bindings that are appropriate for your runtime version. Attempts to call functions belonging to later APIs will fail.
The version of the working copy and the repository can also interfere with a Perl program. If you check out files using subversion 1.4, you can't necessarily check them back in with subversion 1.3. This is because the working copy format changes from time to time. An earlier version of subversion can't be used to manipulate a working copy created with a later version.
As for repositories, subversion is fairly good about making sure that an old version of subversion can read a repository created by a newer version and vice-versa. However, some features of the newer repository will be invisible to older clients. For example, Checking data out of a 1.7 repository won't magically give subversion 1.3 access to changelists, patches, and other post 1.3 features.
The following caveats affect only methods ending in a major_minor version prefix. For details, see the individual modules.
some of the 1.4 functionality does not have complete SWIG bindings and will generate exceptions. For details, see individual modules.
methods for the 1.5 API and up have not been tested.
Additionally, this module was tested against Subversion bindings compiled for subversion 1.4. It may be that later releases of the SWIG bindings will have introduced bugs into the 1.4 API. There is however an ample test suite to check for that. If this module installs for you via CPAN, you shuld be fairly safe even if you are using SWIG bindings compiled against a later API.
Finally, in general, one should mention that no test suite is ever complete. There is always the possibility that an untried combination of parameters will trigger a fault.
If you detect any bugs, the maintainer would be grateful if you would report them via CPAN. Many thanks in advance.
See individual modules.
test against subversion 1.5/1.6 API
expand implementation and documentation of repository administration subsystem.
If anyone would like to be involved in testing or expanding the user friendly interface, please contact the maintainer.
Feedback on the documentation, bugs, usability, or additional features desired is welcome. Time and person-power permitting the most commonly requested features will be implemented.
Below is a review of subversion related resource on and off CPAN. This list was constructed in early February, 2011.
RFC: Automating SVN with Perl A a brief overview of the Subversion C API and its various subsystems followed by a discussion of the various subversion modules available as of Dec, 2009.
Version control with subversion, Chapter 9 - comprehensive guide to command line tools
Version control with Subversion, Chapter 8 - overview of the APIs and various topics of interest to developers.
Subversion C-API documentation
/subversion/trunk/subversion - Subversion source code
/subversion/trunk/subversion/bindings/swig - Subversion-SWIG bindings - definition files and source code for Perl and other languages
* Alien::SVN - the modules responsible for importing the SWIG-Perl bindings for subversion. This class would not be possible withut this module.
* SVN::TXN::Props - extracts revision properties and stores them in a hash for use in hook scripts
* SVN::Simple - a simplified Delta editor for rolling your own commit process.
* SVN::Agent - wrapper for command line client (svn)
* SVN::Class - wrapper for command line client (svn)
* SVN::Look - wrapper for command line tool: svnlook
* SVN::SVNLook - wrapper for command line tool: svnlook
* SVN::Hooks - a framework for managing hooks and defining hooks using reusable components.
* SVN::Notify - function that can be called from a hook script. The routine monitors subversion activity and sends emails to notify people of interesting events.
* SVN::Notify::Config - configures SVN::Notify
* SVN::Notify::Mirror - extension of SVN::Notify that uses svn export and rsync or ssh to push the latest versions of repository files onto a webserver or other resource using svn export
svn export
rsync
ssh
* SVN::Notify::Snapshot - exports a snapshot of a subversion repository
* SVN::Utils::ClientIP - get client's IP address in a subversion hook
* SVN::ACL - configure user access - writes directly to repository access configuration files without the assistance of either subversion command line tools or SWIG bindings
* SVN::Access - configure user access - writes directly to repository access configuration files without the assistance of either subversion command line tools or SWIG bindings
* SVN::Hook - a framework for install, enable, disable, and testing hook scripts.
* Git::SVNReplay - replays Git commits into a throwaway SVN repository using the command line client (svn). Useful for integrating a git repository contents with tools that only know how to speak to a subversion repository.
* SVN::Mirror - mirror remote repository to a local repository uses SWIG bindings.
* SVN::Push - push changes from one respository into another using SWIG bindings.
* SVN::Pusher - push changes from one respository into another using SWIG bindings.
* SVN::S4 - utilties for managing working copies, e.g. mapping project URLs to project directories. Uses SWIG bindings.
* SVN::OpenSVN - fetches a subversion respoistory dump from the open SVN project - uses neither SWIG nor command line tools.
* Dist::Zilla::Plugin::SvnObtain - gets files from a subversion repository before building a distribution using SWIG bindings
* SVN::Deploy - building/deploying releases from a repository using SWIG bindings.
* SVN::Churn - generate graph for repository churn using SWIG bindings.
* SVN::Log - retrieves and parses commit logs using SWIG bindings.
* SVN::Log::Index - builds an index on commit logs using SVN::Log.
* SVN::Log::Accounting - tabulates information from log files into reports using SVN::Log
* App::SVN::Bisect - interactive tool for finding which revision in a subversion repository contains a particular change using the log subcommand of the command line client (svn)
* SVN::Dump - parses dumpfile without use of SWIG bindings or command line tools.
* SVN::DumpReloc - parses dumpfile without use of SWIG bindings or command line tools.
* SVN::Dumpfile - parses dumpfile without use of SWIG bindings or command line tools.
* SVN::Dumpfilter - parses dumpfile without use of SWIG bindings or command line tools.
* Parse::SVNDiff - parses and formats SVN's binary diff output. What it uses to do this is not clear. The source code is not visible via CPAN.
* SVN::Web - a web interface to a subversion repository. Uses SWIG bindings.
* Catalyst::Model::SVN - Catalyst browser for subversion repositories. Uses SWIG bindings.
* Padre::Plugin::SVN - SVN access for the Padre editor. Uses command line client (svn).
Elizabeth Grace Frank-Backman
Copyright (c) 2008-2011 Elizabeth Grace Frank-Backman. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install SVN::Friendly::Dates, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SVN::Friendly::Dates
CPAN shell
perl -MCPAN -e shell install SVN::Friendly::Dates
For more information on module installation, please visit the detailed CPAN module installation guide.