legacy/install.pod

   1 =pod
   2
   3 =head1 Installation 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 three 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 * Time::ParseDate (install "Time-modules" from PPM)
  32
  33 =item * Getopt::Long
  34
  35 =item * Cwd
  36
  37 =item * File::Path
  38
  39 =item * Pod::Usage
  40
  41 =item * Text::Wrap
  42
  43 =item * Win32::TieRegistry
  44
  45 =item * SVN::Client
  46
  47 =item * SVN::Core
  48
  49 =item * SVN::WC
  50
  51 =back
  52
  53 =head3 Installing DBI, DBD::SQLite, and Time-modules:
  54
  55 The easiest way to install these 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).
  56
  57 You should be able to type just C<install DBI>, C<install DBD::SQLite>, and C<install Time-modules> from the C<ppm> prompt. Alternatively, you can perform each install as a separate C<ppm> command, such as C<ppm install DBI>.
  58
  59    ppm> install DBI
  60    ====================
  61    Install 'DBI' version 1.42 in ActivePerl 5.8.3.809.
  62    ====================
  63    Downloaded 508164 bytes.
  64    Extracting 69/69: blib/arch/auto/DBI/Driver_xst.h
  65    Files found in blib\arch: installing files in blib\lib into architecture
  66    dependent library tree
  67    Successfully installed DBI version 1.42 in ActivePerl 5.8.3.809.
  68
  69    ppm> install DBD::SQLite
  70    ====================
  71    Install 'DBD-SQLite' version 0.31 in ActivePerl 5.8.3.809.
  72    ====================
  73    Downloaded 125388 bytes.
  74    Extracting 10/10: blib/arch/auto/DBD/SQLite/SQLite.lib
  75    Files found in blib\arch: installing files in blib\lib into architecture
  76    dependent library tree
  77    Successfully installed DBD-SQLite version 0.31 in ActivePerl 5.8.3.809.
  78
  79    ppm> quit
  80
  81 =head3 Installing SVN::Client and friends:
  82 Get L<http://vss2svn.tigris.org/files/documents/1735/20299/svn-1.1.3-perl-5.8.zip> or
  83 L<http://subversion.tigris.org/files/documents/15/21737/svn-win32-1.1.4_pl.zip>
  84
  85 The 1.1.3 package is laid out closer to the ActivePerl layout than the 1.1.4 layout.
  86
  87 For the 1.1.3 package:
  88
  89 =over 4
  90
  91 =item * Extract the package
  92
  93 =item * copy C<bin> to C<C:\Perl\bin> (or wherever ActiveState is installed)
  94
  95 =item * copy C<site> to C<C:\Perl\site>
  96
  97 =back
  98
  99 For the 1.1.4 package:
 100
 101 =over 4
 102
 103 =item * Extract the package
 104
 105 =item * copy C<svn-win32-1.1.4\perl\SVN\swigpl.dll> and  C<svn-win32-1.1.4\perl\SVN\libsvn_swig_perl-1.dll> to C<C:\Perl\bin> (or wherever ActiveState is installed)
 106
 107 =item * make a directory C<C:\Perl\site\lib\SVN>
 108
 109 =item * make a directory C<C:\Perl\site\lib\auto\SVN>
 110
 111 =item * copy C<svn-win32-1.1.4\perl\SVN\*.pm> to C<C:\Perl\site\lib\SVN>
 112
 113 =item * copy C<svn-win32-1.1.4\perl\SVN\_*.dll> to C<C:\Perl\site\lib\auto\SVN>
 114
 115 =back
 116
 117 =head3 Setting up your PATH
 118
 119 You should now be able to run C<vss2svn.pl>. The Visual SourceSafe C<ss.exe> 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>.
 120
 121   C:\vss2svn> ss help
 122   C:\vss2svn> perl -v
 123
 124 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.
 125
 126 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:
 127
 128 L<http://vss2svn.tigris.org/servlets/ProjectDocumentList?folderID=2788>
 129
 130 In addition, the --utf8 command-line argument (to explicitly convert all comments to UTF-8) requires Perl 5.8 or higher.
 131
 132 After installation, be sure to read the README.TXT file, especially the "Known Problems" section.