install.pod

   1 =pod
   2
   3 =head1 Install and Usage Instructions for C<vss2svn.pl>
   4
   5 =head2 INSTALLATION
   6
   7 =head3 vss2svn.pl Script
   8
   9 There is no installation routine for the script itself; simply copy it to any folder such as C<C:\vss2svn>.
  10
  11 =head3 Perl Interpreter
  12
  13 In order to run this script, you must have a fairly recent version of Perl. Only Windows platforms are supported, since that is where the ss.exe executable is located. Actually, the SourceSafe client has indeed been ported to Unix and MacOS, and this script would probably run on those platforms with little modification, but such use is unsupported.
  14
  15 The latest build of ActiveState Perl 5.8 is highly recommended. It is available for free (both as a Windows Installer package and a .tar.gz archive) at:
  16
  17 L<http://www.activestate.com/Products/Download/Download.plex?id=ActivePerl>
  18
  19 If using the Windows Installer version, be sure to specify that you want the location of the Perl executable added to your PATH.
  20
  21 =head3 Required Perl Modules
  22
  23 This script depends on the following Perl modules. All but the first two are included as part of the base ActiveState Perl install.
  24
  25 =over 4
  26
  27 =item * DBI
  28
  29 =item * DBD::SQLite
  30
  31 =item * Getopt::Long
  32
  33 =item * Cwd
  34
  35 =item * File::Path
  36
  37 =back
  38
  39 =head3 Installing DBI and DBD::SQLite
  40
  41 The easiest way to install the C<DBI> and C<DBD::SQLite> modules is using ActiveState's C<ppm> (programmer's package manager) utility. ActivePerl must already be installed before running C<ppm>. From the Command Prompt, type C<ppm>, or, if using ActivePerl 5.6, C<ppm3>. (Older versions of ActivePerl probably use just C<ppm>, but the syntax may be a bit different).
  42
  43 You should be able to type just C<install DBI> and C<install DBD::SQLite> from the C<ppm> prompt.
  44
  45    ppm> install DBI
  46    ====================
  47    Install 'DBI' version 1.42 in ActivePerl 5.8.3.809.
  48    ====================
  49    Downloaded 508164 bytes.
  50    Extracting 69/69: blib/arch/auto/DBI/Driver_xst.h
  51    Files found in blib\arch: installing files in blib\lib into architecture
  52    dependent library tree
  53    Successfully installed DBI version 1.42 in ActivePerl 5.8.3.809.
  54
  55    ppm> install DBD::SQLite
  56    ====================
  57    Install 'DBD-SQLite' version 0.31 in ActivePerl 5.8.3.809.
  58    ====================
  59    Downloaded 125388 bytes.
  60    Extracting 10/10: blib/arch/auto/DBD/SQLite/SQLite.lib
  61    Files found in blib\arch: installing files in blib\lib into architecture
  62    dependent library tree
  63    Successfully installed DBD-SQLite version 0.31 in ActivePerl 5.8.3.809.
  64
  65    ppm> quit
  66
  67 =head3 Setting up your PATH
  68
  69 You should now be able to run C<vss2svn.pl>. The Visual SourceSafe C<ss.exe> command, the Subversion C<svn.exe> command, and C<perl> should all be in your PATH. To check for this, issue the following three commands from the Command Prompt in the directory where C<vss2svn.pl> is located. To open a Windows Command Prompt, choose C<Run> from the Start Menu (or press Windows Key + R) and type C<cmd>.
  70
  71   C:\vss2svn> ss help
  72   C:\vss2svn> svn --version
  73   C:\vss2svn> perl -v
  74
  75 All three should return with some status information about the version you have installed. If you get an error message instead, modify your PATH environment variable (from Control Panel, choose System, Advanced, Environment Variables or something similar; it doesn't matter whether you use the User or System PATH variable, as they will be merged). While you are there, ensure the C<SSDIR> environment variable points to the root of your VSS database (wherever the F<srcsafe.ini> file is located). After changing these settings, you must close and re-open your Command Prompt.
  76
  77 =head1 RUNNING THE SCRIPT
  78
  79 Once you have all of the above set up, type C<perl vss2svn.pl --help> at the Command Prompt. You should get usage information regarding the script's command-line arguments. Refer to this information to start your migration. Be sure to read all directions first!
  80
  81 If you are using ActivePerl 5.6, you may receive a C<DBD::SQLite> fatal error when the script is first run. In that case, try using our pre-built C<DBD::SQLite> binary files instead, available at:
  82
  83 L<http://vss2svn.tigris.org/servlets/ProjectDocumentList?folderID=2788>