| -*-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 |
| |
