subversion/bindings/swig/INSTALL

   1                                                                 -*-text-*-
   2
   3 STATUS OF THE SWIG BINDINGS
   4
   5 * Python
   6
   7   The Python bindings are fairly well developed, although there are some
   8   missing parts.
   9
  10   (N.B. As discussed below, they will not compile in Debug mode on Windows.)
  11
  12 * Perl
  13
  14   The Perl bindings are complete, with the exception of SVN::Wc, on which
  15   very little work has been done.
  16
  17 * Ruby
  18
  19   The Ruby bindings are a recent development, but are fully implemented.
  20   The Ruby bindings API may change incompatibly as development proceeds.
  21
  22   Completed modules:
  23   - Svn::Client
  24   - Svn::Core::Config
  25   - Svn::Delta
  26   - Svn::Fs
  27   - Svn::Ra
  28
  29   Not completed but enough modules:
  30   - Svn::Core::Diff
  31     Unsupported functions:
  32     - svn_diff_diff()
  33     - svn_diff_diff3()
  34     - svn_diff_diff4()
  35     - svn_diff_output()
  36     - svn_diff_file_diff4()
  37
  38   Completed modules but including no-unit-test functions:
  39   - Svn::Repos
  40     Untested functions:
  41     - svn_repos_parse_dumpstream2()
  42     - svn_repos_get_fs_build_parser2()
  43   - Svn::Wc
  44     Untested functions:
  45     - svn_wc_get_status_editor2()
  46     - svn_wc_status_set_repos_locks()
  47     - svn_wc_crawl_revisions2()
  48     - svn_wc_get_update_editor2()
  49     - svn_wc_get_switch_editor2()
  50     - svn_wc_get_diff_editor3()
  51     - svn_wc_diff3()
  52     - svn_wc_get_prop_diffs()
  53     - svn_wc_merge()
  54     - svn_wc_merge_props()
  55     - svn_wc_merge_prop_diffs()
  56     - svn_wc_get_pristine_copy_path()
  57     - svn_wc_cleanup2()
  58     - svn_wc_relocate9)
  59     - svn_wc_transmit_text_deltas()
  60     - svn_wc_transmit_prop_deltas()
  61     - svn_wc_add_lock()
  62     - svn_wc_remove_lock()
  63
  64 BUILDING SWIG BINDINGS FOR SVN ON UNIX
  65
  66
  67 Step 1:  Install a suitable version of SWIG (which is
  68          currently swig version 1.3.24 - 1.3.31).
  69
  70     * Perhaps your distribution packages a suitable version - if it does
  71       install it, and skip to the last bullet point in this section.
  72
  73     * Go to http://www.swig.org/, download the source tarball, and unpack.
  74
  75     * In the SWIG-1.3.xx directory, run ./configure.
  76
  77         If you plan to build the Python bindings, and have a system
  78         with more than one version of Python installed, you may need
  79         to pass
  80
  81              --with-python=/path/to/correct/python/binary
  82
  83         to the configure script.  You need Python 2.2 or above.
  84
  85         If you plan to build the Perl bindings, and have a system
  86         with more than one version of perl installed, you may need
  87         to pass
  88
  89              --with-perl5=/path/to/correct/perl/binary
  90
  91         to the configure script.  You need Perl 5.8.0 or above.
  92
  93     * Build and install.
  94
  95         Run 'make && make install'
  96
  97     * To verify you have SWIG installed correctly, run "swig -version"
  98       from the command line. SWIG should report that it is version 1.3.24
  99       or newer.
 100
 101 Step 2:  Build and Install Subversion.
 102
 103   See Subversion's own INSTALL file for details.
 104
 105   Make sure that Subversion's ./configure script sees your installed SWIG!
 106   It tries to detect SWIG near the very end of its output.
 107
 108   Also make sure that the configure script sees the paths to the perl and/or
 109   python executable you used to configure SWIG as above.  If it does not then
 110   you can specify the correct path by adding PYTHON=/path/to/python or
 111   PERL=/path/to/perl onto the command line for configure.  For example:
 112        ./configure PYTHON=/usr/bin/python2.2 PERL=/usr/bin/perl5.8.0
 113
 114   If Subversion's ./configure finds a SWIG that it's happy with, then
 115   it will build special glue libraries to link svn to the swig bindings:
 116     libsvn_swig_py.so (for Python)
 117     libsvn_swig_perl.so (for Perl)
 118
 119
 120 Step 3:  Install Specific Language Bindings
 121
 122 *  Python
 123
 124    1.  Run 'make swig-py' from the top of the Subversion source tree,
 125        to build the bindings.
 126
 127        (This will invoke SWIG on the *.i files, resulting in a collection
 128        of .c source files.  It will then compile and link those .c files into
 129        Python libraries.)
 130
 131    2.  Run 'make check-swig-py' from the top of the Subversion source
 132        tree, to test the bindings
 133
 134    3.  Run 'make install-swig-py' (as root, typically)
 135        from the top of the Subversion source tree.  This will copy
 136        your new Python libraries into the appropriate system location.
 137
 138        Note: If you don't have access to install to Python's site-packages
 139        directory, you can have the Python modules install to your home
 140        directory.  You can do this by running
 141        'make install-swig-py swig_pydir=~'.
 142
 143        Note: If you want to install to an alternate prefix (usually only
 144        if you are building packages), you can supply the prefix here.  An
 145        example of doing this for building rpms looks like
 146        'make install-swig-py DESTDIR=$RPM_BUILD_ROOT/usr'.
 147
 148    4.  Make sure that whatever directory the bindings got installed in
 149        is in your PYTHONPATH.  That directory depends on how you
 150        installed; a typical location is /usr/local/lib/svn-python/.
 151
 152        An nice way to do this is:
 153        $ echo /usr/local/lib/svn-python \
 154            > /usr/lib/python2.x/site-packages/subversion.pth
 155
 156
 157 *  Perl
 158
 159    Perl 5.8.0 is required.  You can specify the perl binary by passing
 160    PERL=/path/to/perl as part of the configure command in the top level
 161    of the Subversion source tree.  Make sure that the Perl version used
 162    is the same one that you configured SWIG to run against during the
 163    SWIG configure (see above).
 164
 165    1.  Run `make swig-pl' from the top of the Subversion source tree.
 166
 167    2.  Run `make check-swig-pl' from the top of the Subversion source
 168        tree, to test the bindings
 169
 170    3.  to install run `make install-swig-pl' from the top of the
 171        Subversion source tree.
 172
 173    If you need to pass extra parameters to Perl build process (Makefile.PL),
 174    then you need to do this process somewhat different:
 175
 176    1.  Run `make swig-pl-lib' from the top of the Subversion source tree.
 177
 178    2.  Run `make install-swig-pl-lib'
 179
 180    3.  cd subversion/bindings/swig/perl/native
 181
 182    4.  Run `perl Makefile.PL EXTRAOPTIONSHERE`
 183
 184    5.  Run `make install'
 185
 186    To install the Perl bindings in a location other than the system
 187    Perl directory, use the above instructions with the extra option
 188    PREFIX=/your/prefix/here.
 189
 190
 191 * Ruby
 192
 193    1. Run `make swig-rb' from the top of the Subversion source tree,
 194       to build the bindings.
 195
 196    2. Run `make check-swig-rb' from the top of the Subversion source
 197       tree, to test the bindings.
 198
 199    3. To install, run `make install-swig-rb' from the top of the
 200       Subversion source tree.
 201
 202    You can specify the ruby binary by passing RUBY=/path/to/ruby as part
 203    of the configure command in the top level of the Subversion source
 204    tree. Make sure that the Ruby version used is the same one that you
 205    configured SWIG to run against during the SWIG configure (see above).
 206
 207
 208 BUILDING SWIG BINDINGS FOR SVN ON WINDOWS
 209
 210
 211    1.  Install SWIG. Download the SWIG Windows zipfile (it's the same as the
 212        source tarball except that it also includes a copy of swig.exe) from
 213
 214            http://www.swig.org/
 215
 216        and extract it somewhere, like C:\Program Files.
 217
 218    2.  Install whatever languages you want to build runtimes for. Windows
 219        versions of Python and Perl are available from:
 220
 221            http://www.python.org/
 222            http://www.activestate.com/ActivePerl/
 223
 224        NOTE: Our Python SWIG bindings will currently NOT compile in Debug mode
 225              unless you have python24_d.lib (which binary distributions of
 226              Python do not contain).  Therefore, the Python bindings will only
 227              compile in Release mode.  (This is due to pyconfig.h using the
 228             _DEBUG flag too and setting a #pragma comment(lib) value.)
 229
 230        For Perl support, you also need to add the paths into Visual Studio.
 231
 232        In Visual C++ 6, go to Tools -> Options -> Directories.
 233
 234        In Visual C++ .NET, go to Tools -> Options -> Projects
 235        -> VC++ Directories.
 236
 237        Add the following paths:
 238
 239            Executable Directories:
 240
 241                For Perl, path to perl.exe
 242                (for example, C:\Program Files\Perl\bin)
 243
 244            Library Directories:
 245
 246                For Perl, path to perl##.lib
 247                (for example, C:\Program Files\Perl\lib\CORE)
 248
 249            Include Directories:
 250
 251                For Perl, path to perl.h
 252                (for example, C:\Program Files\Perl\lib\CORE)
 253
 254    3.  Create the Visual Studio project files via gen-make.py, adding in
 255        the --with-swig parameter to the installed location for SWIG.
 256        Example:
 257
 258         > gen-make.py -t vcproj --with-swig="C:\Program Files\SWIG-1.3.31"
 259
 260    4.  If you haven't already built Subversion, you should do so now.
 261        Instructions are in the main INSTALL file.
 262
 263    5.  Build the bindings. Open the Subversion workspace in Visual C++
 264        (subversion_msvc.dsw or subversion_vcnet.sln) and build one or more
 265        of the following projects:
 266
 267            __SWIG_PYTHON__
 268            __SWIG_PERL__
 269
 270    6. Install the bindings. The procedure varies depending on the language.
 271
 272       For Python, create two folders:
 273
 274           <PYTHON>\Lib\site-packages\svn
 275           <PYTHON>\Lib\site-packages\libsvn
 276
 277       Copy subversion\bindings\swig\python\svn\*.py into the svn folder.
 278       Copy subversion\bindings\swig\python\*.py and
 279       Release\subversion\bindings\swig\python\*.dll into the libsvn folder.
 280
 281       Optionally, you can run the following commands to compile the Python
 282       sources into bytecode:
 283
 284           python <PYTHON>\lib\compileall.py <PYTHON>\Lib\site-packages\svn
 285           python <PYTHON>\lib\compileall.py <PYTHON>\Lib\site-packages\libsvn
 286
 287       This can make the modules load faster for users without write access
 288       to the site-packages directory.
 289
 290       For Perl, the bindings have be copied into a more complicated directory
 291       structure inside the Perl library directory. Running the commands below
 292       from the subversion source directory will copy the files to the right
 293       places:
 294
 295         set PERL_LIBS="C:\Program Files\Perl\site\lib"
 296
 297         md %PERL_LIBS%\SVN %PERL_LIBS%\auto\SVN
 298         copy subversion\bindings\swig\perl\native\*.pm %PERL_LIBS%\SVN
 299
 300         md %PERL_LIBS%\auto\SVN\_Client
 301         copy Release\subversion\bindings\swig\perl\_Client.dll %PERL_LIBS%\auto\SVN\_Client
 302         copy Release\subversion\bindings\swig\perl\_Client.pdb %PERL_LIBS%\auto\SVN\_Client
 303
 304         md %PERL_LIBS%\auto\SVN\_Core
 305         copy Release\subversion\bindings\swig\perl\_Core.dll %PERL_LIBS%\auto\SVN\_Core
 306         copy Release\subversion\bindings\swig\perl\_Core.pdb %PERL_LIBS%\auto\SVN\_Core
 307
 308         md %PERL_LIBS%\auto\SVN\_Delta
 309         copy Release\subversion\bindings\swig\perl\_Delta.dll %PERL_LIBS%\auto\SVN\_Delta
 310         copy Release\subversion\bindings\swig\perl\_Delta.pdb %PERL_LIBS%\auto\SVN\_Delta
 311
 312         md %PERL_LIBS%\auto\SVN\_Fs
 313         copy Release\subversion\bindings\swig\perl\_Fs.dll %PERL_LIBS%\auto\SVN\_Fs
 314         copy Release\subversion\bindings\swig\perl\_Fs.pdb %PERL_LIBS%\auto\SVN\_Fs
 315
 316         md %PERL_LIBS%\auto\SVN\_Ra
 317         copy Release\subversion\bindings\swig\perl\_Ra.dll %PERL_LIBS%\auto\SVN\_Ra
 318         copy Release\subversion\bindings\swig\perl\_Ra.pdb %PERL_LIBS%\auto\SVN\_Ra
 319
 320         md %PERL_LIBS%\auto\SVN\_Repos
 321         copy Release\subversion\bindings\swig\perl\_Repos.dll %PERL_LIBS%\auto\SVN\_Repos
 322         copy Release\subversion\bindings\swig\perl\_Repos.pdb %PERL_LIBS%\auto\SVN\_Repos
 323
 324         md %PERL_LIBS%\auto\SVN\_Wc
 325         copy Release\subversion\bindings\swig\perl\_Wc.dll %PERL_LIBS%\auto\SVN\_Wc
 326         copy Release\subversion\bindings\swig\perl\_Wc.pdb %PERL_LIBS%\auto\SVN\_Wc
 327
 328 TESTING AND USING SWIG BINDINGS
 329
 330 *  Python
 331
 332    You can exercise the Python bindings test suite by running 'make
 333    check-swig-py' as described in the install section.
 334
 335    For examples of how to use the Python bindings, check out the
 336    sample/demo programs found in tools/examples/ in the Subversion
 337    source code tree.  Additionally, there are several third-party
 338    tools that make use of these bindings, including ViewVC
 339    (http://viewvc.tigris.org/) and Trac (http://trac.edgewall.org/).
 340
 341 *  Perl
 342
 343    The Perl bindings are using the standard module testing facilities
 344    to do regression tests. Simply run 'make check-swig-pl' as described in
 345    the install section.
 346
 347 * Ruby
 348
 349    To test the Ruby bindings, simply run `make check-swig-rb' as described
 350    in the install section.
 351
 352    For examples of how to use the Ruby bindings, take a look at the .rb files
 353    in the following directory:
 354      subversion/bindings/swig/test
 355