path: root/subversion/bindings/swig/INSTALL

                                                                -*-text-*-

STATUS OF THE SWIG BINDINGS

* Python

  The Python bindings are fairly well developed, although there are some
  missing parts. We support both of Python 2.7 and Python 3.x; however,
  SWIG Python bindings for different versions of Python cannot be
  simultaneously installed in the same environment, because they need to
  install mutually incompatible C shared libraries under the same name.  The
  distribution tarballs are shipped with SWIG-generated C source files for
  Python 3.x.

  (N.B. As discussed below, they will not compile in Debug mode on Windows.)

* Perl

  The Perl bindings are complete, with the exception of SVN::Wc, on which
  very little work has been done.

* Ruby

  The Ruby bindings are a recent development, but are fully implemented.
  The Ruby bindings API may change incompatibly as development proceeds.

  Completed modules:
  - Svn::Client
  - Svn::Core::Config
  - Svn::Delta
  - Svn::Fs
  - Svn::Ra

  Not completed but enough modules:
  - Svn::Core::Diff
    Unsupported functions:
    - svn_diff_diff()
    - svn_diff_diff3()
    - svn_diff_diff4()
    - svn_diff_output()
    - svn_diff_file_diff4()

  Completed modules but including no-unit-test functions:
  - Svn::Repos
    Untested functions:
    - svn_repos_parse_dumpstream2()
    - svn_repos_get_fs_build_parser2()
  - Svn::Wc
    Untested functions:
    - svn_wc_get_status_editor2()
    - svn_wc_status_set_repos_locks()
    - svn_wc_crawl_revisions2()
    - svn_wc_get_update_editor2()
    - svn_wc_get_switch_editor2()
    - svn_wc_get_diff_editor3()
    - svn_wc_diff3()
    - svn_wc_get_prop_diffs()
    - svn_wc_merge()
    - svn_wc_merge_props()
    - svn_wc_merge_prop_diffs()
    - svn_wc_get_pristine_copy_path()
    - svn_wc_cleanup2()
    - svn_wc_relocate9)
    - svn_wc_transmit_text_deltas()
    - svn_wc_transmit_prop_deltas()
    - svn_wc_add_lock()
    - svn_wc_remove_lock()

BUILDING SWIG BINDINGS FOR SVN ON UNIX


Step 1: [Optional] Install a suitable version of SWIG

    * SWIG installation is optional.  You do not need to install SWIG
      if you are using a Subversion distribution tarball because it already
      contains the source files generated by SWIG.  You will need a suitable
      version of SWIG if you are using a working copy of Subversion's sources
      checked out from the repository; if you want to generate the SWIG
      language bindings C source files by yourself; or if you want to build
      Python 2.x bindings (since the SWIG-generated C source files in the
      distribution tarballs target Python 3.x).

    * We currently support SWIG versions 2.0.0 and later, with the
      following notes:
      - SWIG 1.3.24 and later 1.3.x may work, but we do not test these
        versions on our latest source code.
      - For Python 2 bindings, SWIG 4.0.0 or later is not supported.
      - For Python 3 bindings, SWIG 3.0.10 or later is required.
      - Note that SWIG 3.0.9 has some trouble with Python support.
        (See https://sourceforge.net/p/swig/news/2016/06/swig-3010-released/)
      - For Perl 5.16 and later, SWIG 2.0.8 or later is required.
      - For Ruby bindings, SWIG 3.0.8 is not supported.

    * Perhaps your distribution packages a suitable version of SWIG.
      If so, install it and skip to the last bullet point of this
      section.

    * Go to http://www.swig.org/, download the source tarball, and unpack.

    * In the swig-x.y.z, directory, run ./configure (where x.y.z is
      SWIG version, e.g., 3.0.12).

        If you plan to build the Python bindings, and have a system
        with more than one version of Python installed, you may need
        to pass

             --with-python=/path/to/correct/python/binary

        to the configure script.  You need Python 2.7 or above.

        If you plan to build the Perl bindings, and have a system
        with more than one version of perl installed, you may need
        to pass

             --with-perl5=/path/to/correct/perl/binary

        to the configure script.  You need Perl 5.8.0 or above.

    * Build and install.

        Run 'make && make install'

    * To verify you have SWIG installed correctly, run "swig -version"
      from the command line.  SWIG should report that it is one of the
      suitable versions mentioned above.


Step 1a: Install py3c library if building Python SWIG bindings.

    * Check your distribution packages first for a suitable version, and
      if found install from there.

    * To install from source, download the latest release from
      https://github.com/encukou/py3c.

    * This is a header-only library, so no configuring or compiling is
      necessary, simply 'make install'.


Step 2:  Build and Install Subversion.

  See Subversion's own INSTALL file for details.

  If you are using a Subversion distribution tarball and want to rebuild
  the SWIG language bindings C source files with your installed SWIG, 
  you need to execute autogen.sh, because the bundled configure script 
  and makefiles don't support it.

  If you don't use SWIG bindings C source files already generated,
  make sure that Subversion's ./configure script sees your installed SWIG!
  It tries to detect SWIG near the very end of its output.
  You can find it by running 'grep "^SWIG=" config.log'.

  Also make sure that the configure script sees the paths to the perl,
  ruby, and/or python executable you used to configure SWIG as above.
  If it does not then you can specify the correct path by specifying
  --with-swig-python=/path/to/python, --with-swig-perl=/path/to/perl,
  and/or --with-swig-ruby=/path/to/ruby to the command line for configure.
  For example:
       ./configure --with-swig-python=/usr/bin/python3.7 \
           --with-swig-perl=/usr/bin/perl5.28.2 \
           --with-swig-ruby=/usr/bin/ruby2.7

  If Subversion's ./configure finds a SWIG that it's happy with, then
  it will build special glue libraries to link svn to the swig bindings:
    libsvn_swig_py-1.so (for Python)
    libsvn_swig_perl-1.so (for Perl)
    libsvn_swig_ruby-1.so (for Ruby)

Step 3:  Install Specific Language Bindings

*  Python

   1.  (Optional) If you want to build Python bindings for a version of
       Python than other than that the prebuilt bindings C sources target
       (e.g., if you use the Subversion distribution tarball but want to build
       Python 2 bindings), run 'make clean-swig-py' from the top of the
       Subversion build tree, to ensure not to use incompatible version of
       bindings source files.

   2.  Run 'make swig-py' from the top of the Subversion build tree,
       to build the bindings.

       (This will invoke SWIG on the *.i files, resulting in a collection
       of .c source files.  It will then compile and link those .c files into
       Python libraries.)

   3.  Run 'make check-swig-py' from the top of the Subversion build
       tree, to test the bindings

   4.  Run 'make install-swig-py' (as root, typically)
       from the top of the Subversion build tree.  This will copy
       your new Python libraries into the appropriate system location.

       Note: If you don't have access to install to Python's site-packages
       directory, you can have the Python modules install to your home
       directory.  You can do this by running
       'make install-swig-py swig_pydir=~'.

       Note: If you want to install to an alternate prefix (usually only
       if you are building packages), you can supply the prefix here.  An
       example of doing this for building rpms looks like
       'make install-swig-py DESTDIR=$RPM_BUILD_ROOT/usr'.

   5.  Make sure that whatever directory the bindings got installed in
       is in your Python search path.  That directory depends on how you
       installed; a typical location is /usr/local/lib/svn-python/.

       There are several ways to do this. See Python's documentation for
       'sys.path' and 'PYTHONPATH'. A nice way to do this is:
       $ echo /usr/local/lib/svn-python \
           > /usr/lib/python3.x/site-packages/subversion.pth

       You may also need to update your operating system's dynamic linker
       configuration to enable Python to load these new libraries. On some
       systems this is done by running 'ldconfig'.


*  Perl

   Perl 5.8.0 is required.  You can specify the perl binary by passing
   --with-swig-perl=/path/to/perl as an option to the configure command
   in the top level of the Subversion source tree.  Make sure that the
   Perl version used is the same one that you configured SWIG to run
   against during the SWIG configure (see above).

   1.  Run `make swig-pl' from the top of the Subversion build tree.

   2.  Run `make check-swig-pl' from the top of the Subversion build
       tree, to test the bindings

   3.  to install run `make install-swig-pl' from the top of the
       Subversion build tree.

   If you need to pass extra parameters to Perl build process (Makefile.PL),
   then you need to do this process somewhat different:

   1.  Run `make swig-pl-lib' from the top of the Subversion build tree.

   2.  Run `make install-swig-pl-lib'

   3.  cd subversion/bindings/swig/perl/native

   4.  Run `perl Makefile.PL EXTRAOPTIONSHERE`

   5.  Run `make install'

   To install the Perl bindings in a location other than the system
   Perl directory, use the above instructions with the extra option
   PREFIX=/your/prefix/here.


* Ruby

   1. Run `make swig-rb' from the top of the Subversion build tree,
      to build the bindings.

   2. Run `make check-swig-rb' from the top of the Subversion build
      tree, to test the bindings.

   3. To install, run `make install-swig-rb' from the top of the
      Subversion build tree.

   You can specify the ruby binary by passing --with-swig-ruby=/path/to/ruby
   as an option to the configure command in the top level of the
   Subversion source tree. Make sure that the Ruby version used is
   the same one that you configured SWIG to run against during the
   SWIG configure (see above).


BUILDING SWIG BINDINGS FOR SVN ON WINDOWS


   1.  Install SWIG. Download the SWIG Windows zipfile (it's the same as the
       source tarball except that it also includes a copy of swig.exe) from

           http://www.swig.org/

       and extract it somewhere, like C:\Program Files.

   2.  Install whatever languages you want to build runtimes for. Windows
       versions of Python and Perl are available from:

           http://www.python.org/
           http://www.activestate.com/ActivePerl/

       If you plan to build python bindings, you will also need to download and
       extract the py3c library from https://github.com/encukou/py3c/releases.

       NOTE: Our Python SWIG bindings will currently NOT compile in Debug mode
             unless you have python24_d.lib (which binary distributions of
             Python do not contain).  Therefore, the Python bindings will only
             compile in Release mode.  (This is due to pyconfig.h using the
            _DEBUG flag too and setting a #pragma comment(lib) value.)

       Our project generator detects Perl, Ruby and Python installs and will
       generate the swig projects for these languages if both swig and the
       language is found.

   3.  Create the Visual Studio project files via gen-make.py, adding in
       the --with-swig parameter to the installed location for SWIG.
       Example:

        > gen-make.py <other options> --with-swig="C:\Program Files\SWIG-2.0.2"

       If you are building python bindings, point to the py3c directory as well:

        > gen-make.py <other options> --with-swig="C:\Program Files\SWIG-2.0.2" \
                                      --with-py3c="C:\SVN\py3c"

   4.  If you haven't already built Subversion, you should do so now.
       Instructions are in the main INSTALL file.

   5.  Build the bindings. Open the Subversion workspace in Visual C++
       (subversion_msvc.dsw or subversion_vcnet.sln) and build one or more
       of the following projects:

           __SWIG_PYTHON__
           __SWIG_PERL__
           __SWIG_RUBY__

   6. Install the bindings. The procedure varies depending on the language.

      For Python, create two folders:

          <PYTHON>\Lib\site-packages\svn
          <PYTHON>\Lib\site-packages\libsvn

      Copy subversion\bindings\swig\python\svn\*.py into the svn folder.
      Copy subversion\bindings\swig\python\*.py and
      Release\subversion\bindings\swig\python\*.pyd and
      Release\subversion\bindings\swig\python\libsvn_swig_py\libsvn_swig_py-1.dll
      into the libsvn folder.

      Optionally, you can run the following commands to compile the Python
      sources into bytecode:

          python <PYTHON>\lib\compileall.py <PYTHON>\Lib\site-packages\svn
          python <PYTHON>\lib\compileall.py <PYTHON>\Lib\site-packages\libsvn

      This can make the modules load faster for users without write access
      to the site-packages directory.

      For Perl, the bindings have be copied into a more complicated directory
      structure inside the Perl library directory. Running the commands below
      from the subversion source directory will copy the files to the right
      places:

        set PERL_LIBS="C:\Program Files\Perl\site\lib"

        md %PERL_LIBS%\SVN %PERL_LIBS%\auto\SVN
        copy subversion\bindings\swig\perl\native\*.pm %PERL_LIBS%\SVN

        md %PERL_LIBS%\auto\SVN\_Client
        copy Release\subversion\bindings\swig\perl\_Client.dll %PERL_LIBS%\auto\SVN\_Client
        copy Release\subversion\bindings\swig\perl\_Client.pdb %PERL_LIBS%\auto\SVN\_Client

        md %PERL_LIBS%\auto\SVN\_Core
        copy Release\subversion\bindings\swig\perl\_Core.dll %PERL_LIBS%\auto\SVN\_Core
        copy Release\subversion\bindings\swig\perl\_Core.pdb %PERL_LIBS%\auto\SVN\_Core

        md %PERL_LIBS%\auto\SVN\_Delta
        copy Release\subversion\bindings\swig\perl\_Delta.dll %PERL_LIBS%\auto\SVN\_Delta
        copy Release\subversion\bindings\swig\perl\_Delta.pdb %PERL_LIBS%\auto\SVN\_Delta

        md %PERL_LIBS%\auto\SVN\_Fs
        copy Release\subversion\bindings\swig\perl\_Fs.dll %PERL_LIBS%\auto\SVN\_Fs
        copy Release\subversion\bindings\swig\perl\_Fs.pdb %PERL_LIBS%\auto\SVN\_Fs

        md %PERL_LIBS%\auto\SVN\_Ra
        copy Release\subversion\bindings\swig\perl\_Ra.dll %PERL_LIBS%\auto\SVN\_Ra
        copy Release\subversion\bindings\swig\perl\_Ra.pdb %PERL_LIBS%\auto\SVN\_Ra

        md %PERL_LIBS%\auto\SVN\_Repos
        copy Release\subversion\bindings\swig\perl\_Repos.dll %PERL_LIBS%\auto\SVN\_Repos
        copy Release\subversion\bindings\swig\perl\_Repos.pdb %PERL_LIBS%\auto\SVN\_Repos

        md %PERL_LIBS%\auto\SVN\_Wc
        copy Release\subversion\bindings\swig\perl\_Wc.dll %PERL_LIBS%\auto\SVN\_Wc
        copy Release\subversion\bindings\swig\perl\_Wc.pdb %PERL_LIBS%\auto\SVN\_Wc


TESTING SWIG BINDINGS

*  Python

   You can exercise the Python bindings test suite by running 'make
   check-swig-py' as described in the install section.

*  Perl

   The Perl bindings are using the standard module testing facilities
   to do regression tests. Simply run 'make check-swig-pl' as described in
   the install section.

*  Ruby

   To test the Ruby bindings, simply run `make check-swig-rb' as described
   in the install section.


USING SWIG BINDINGS

*  Python

   1. Ensure Python's module search path includes the 'lib/svn-python'
      subdirectory of the Subversion installation directory.  For example,
      include that directory in the 'PYTHONPATH' environment variable or
      insert it into 'sys.path' at run time.

   2. Import the required modules into your Python program.  For example:

        import svn.client, svn.repos

   3. The APIs available within each module are broadly the same as the
      corresponding C APIs except:

        * you may omit the module prefix (for example, 'svn_client_')
        * pool arguments are optional
        * using Python exceptions instead of returning svn_error_t
        * returning a tuple of outputs instead of return-by-pointer
        * do not pass a baton along with a callback function

      See python/README for more details on these differences.

   For examples of how to use the Python bindings, check out the
   sample/demo programs found in tools/examples/ in the Subversion
   source code tree.  Additionally, there are several third-party
   tools that make use of these bindings, including ViewVC
   (http://www.viewvc.org/) and Trac (https://trac.edgewall.org/).

*  Perl

   ### TODO

*  Ruby

   For examples of how to use the Ruby bindings, take a look at the .rb files
   in the following directory:
     subversion/bindings/swig/test