1 ======================================
4 ======================================
6 $LastChangedDate: 2020-02-17 03:49:42 +0000 (Mon, 17 Feb 2020) $
13 B. Dependency Overview
14 C. Dependencies in Detail
18 A. Building from a Tarball
19 B. Building the Latest Source under Unix
20 C. Building under Unix in Different Directories
21 D. Installing from a Zip or Installer File under Windows
22 E. Building the Latest Source under Windows
24 III. BUILDING A SUBVERSION SERVER
25 A. Setting Up Apache Httpd
26 B. Making and Installing the Subversion Apache Server Module
27 C. Configuring Apache Httpd for Subversion
28 D. Running and Testing
29 E. Alternative: 'svnserve' and ra_svn
31 IV. PLATFORM-SPECIFIC ISSUES
35 V. PROGRAMMING LANGUAGE BINDINGS (PYTHON, PERL, RUBY, JAVA)
44 This document is written for people who intend to build
45 Subversion from source code. Normally, the only people who do
46 this are Subversion developers and package maintainers.
48 If neither of these labels fits you, we recommend you find an
49 appropriate binary package of Subversion and install that.
50 While the Subversion project doesn't officially release binary
51 packages, a number of volunteers have made such packages
52 available for different operating systems. Most Linux and BSD
53 distributions already have Subversion packages ready to go via
54 standard packaging channels, and other volunteers have built
55 'installers' for both Windows and OS X. Visit this page for
58 https://subversion.apache.org/packages.html
60 For those of you who still wish to build from source, Subversion
61 follows the Unix convention of "./configure && make", but it has
62 a number of dependencies.
65 B. Dependency Overview
67 You'll need the following build tools to compile Subversion:
69 * autoconf 2.59 or later (Unix only)
70 * libtool 1.4 or later (Unix only)
71 * a reasonable C compiler (gcc, Visual Studio, etc.)
74 Subversion also depends on the following third-party libraries:
76 * libapr and libapr-util (REQUIRED for client and server)
78 The Apache Portable Runtime (APR) library provides an
79 abstraction of operating-system level services such as file
80 and network I/O, memory management, and so on. It also
81 provides convenience routines for things like hashtables,
82 checksums, and argument processing. While it was originally
83 developed for the Apache HTTP server, APR is a standalone
84 library used by Subversion and other products. It is a
85 critical dependency for all of Subversion; it's the layer
86 that allows Subversion clients and servers to run on
87 different operating systems.
89 * SQLite (REQUIRED for client and server)
91 Subversion uses SQLite to manage some internal databases.
93 * libz (REQUIRED for client and server)
95 Subversion uses zlib for compressing binary differences.
96 These diff streams are used everywhere -- over the network,
97 in the repository, and in the client's working copy.
99 * utf8proc (REQUIRED for client and server)
101 Subversion uses utf8proc for UTF-8 support, including Unicode
104 * Apache Serf (OPTIONAL for client)
106 The Apache Serf library allows the Subversion client to send HTTP
107 requests. This is necessary if you want your client to access
108 a repository served by the Apache HTTP server. There is an
109 alternate 'svnserve' server as well, though, and clients
110 automatically know how to speak the svnserve protocol.
111 Thus it's not strictly necessary for your client to be able
112 to speak HTTP... though we still recommend that your client
113 be built to speak both HTTP and svnserve protocols.
115 * OpenSSL (OPTIONAL for client and server)
117 OpenSSL enables your client to access SSL-encrypted https://
118 URLs (using Apache Serf) in addition to unencrypted http:// URLs.
119 To use SSL with Subversion's WebDAV server, Apache needs to be
120 compiled with OpenSSL as well.
122 * Netwide Assembler (OPTIONAL for client and server)
124 The Netwide Assembler (NASM) is used to build the (optional)
125 assembler modules of OpenSSL. As of OpenSSL 1.1.0 NASM is the
126 only supported assembler.
128 * Berkeley DB (DEPRECATED and OPTIONAL for client and server)
130 When you create a repository, you have the option of
131 specifying a storage 'back-end' implementation. Currently,
132 there are two options. The newer and recommended one, known
133 as FSFS, does not require Berkeley DB. FSFS stores data in a
134 flat filesystem. The older implementation, known as BDB, has
135 been deprecated and is not recommended for new repositories,
136 but is still available. BDB stores data in a Berkeley DB
137 database. This back-end will only be available if the BDB
138 libraries are discovered at compile time.
140 * libsasl (OPTIONAL for client and server)
142 If the Cyrus SASL library is detected at compile time, then
143 the svn client (and svnserve server) will be able to utilize
144 SASL to do various forms of authentication when speaking the
147 * Python, Perl, Java, Ruby (OPTIONAL)
149 Subversion is mostly a collection of C libraries with
150 well-defined APIs, with a small collection of programs that
151 use the APIs. If you want to build Subversion API bindings
152 for other languages, you need to have those languages
153 available at build time.
155 * py3c (OPTIONAL, but REQUIRED for Python bindings)
157 The Python 3 Compatibility Layer for C Extensions is required
158 to build the Python language bindings.
160 * KDE Framework 5, libsecret, GNOME Keyring (OPTIONAL for client)
162 Subversion contains optional support for storing passwords in
163 KWallet via KDE Framework 5 libraries (preferred) or kdelibs4,
164 and GNOME Keyring via libsecret (preferred) or GNOME APIs.
166 * libmagic (OPTIONAL)
168 If the libmagic library is detected at compile time,
169 it will be used to determine mime-types of binary files
170 which are added to version control. Note that mime-types
171 configured via auto-props or the mime-types-file option
176 C. Dependencies in Detail
178 Subversion depends on a number of third party tools and libraries.
179 Some of them are only required to run a Subversion server; others
180 are necessary just for a Subversion client. This section explains
181 what other tools and libraries will be required so that Subversion
182 can be built with the set of features you want.
184 On Unix systems, the './configure' script will tell you if you are
185 missing the correct version of any of the required libraries or
186 tools, so if you are in a real hurry to get building, you can skip
187 straight to section II. If you want to gather the pieces you will
188 need before starting out, however, you should read the following.
190 If you're just installing a Subversion client, the Subversion
191 team has created a script that downloads the minimal prerequisite
192 libraries (Apache Portable Runtime, Sqlite, and Zlib). The script,
193 'get-deps.sh', is available in the same directory as this file.
194 When run, it will place 'apr', 'apr-util', 'serf', 'zlib', and
195 'sqlite-amalgamation' directories directly into your unpacked Subversion
196 distribution. With the exception of sqlite-amalgamation, they will
197 still need to be configured, built and installed explicitly, and
198 Subversion's own configure script may need to be told where to find
199 them, if they were not installed in standard system locations.
201 Note: there are optional dependencies (such as OpenSSL, swig, and httpd)
202 which get-deps.sh does not download.
204 Note: Because previous builds of Subversion may have installed older
205 versions of these libraries, you may want to run some of the cleanup
206 commands described in section II.B before installing the following.
209 1. Apache Portable Runtime 1.5 or newer (REQUIRED)
211 Whenever you want to build any part of Subversion, you need the
212 Apache Portable Runtime (APR) and the APR Utility (APR-util)
215 If you do not have a pre-installed APR and APR-util, you will need
216 to get these yourself:
218 https://apr.apache.org/download.cgi
220 On Unix systems, if you already have the APR libraries compiled and do
221 not wish to regenerate them from source code, then Subversion needs to
222 be able to find them.
224 There are a couple of options to "./configure" that tell it where
225 to look for the APR and APR-util libraries. By default it will try
226 to locate the libraries using apr-config and apu-config scripts.
227 These scripts provide all the relevant information for the APR and
228 APR-util installations.
230 If you want to specify the location of the APR library, you can use
231 the "--with-apr=" option of "./configure". It should be able to find
232 the apr-config script in the standard location under that directory
233 (e.g. ${prefix}/bin).
235 Similarly, you can specify the location of APR-util using the
236 "--with-apr-util=" option to "./configure". It will look for the
237 apu-config script relative to that directory.
239 For example, if you want to use the APR libraries you built
240 with the Apache httpd server, you could run:
242 $ ./configure --with-apr=/usr/local/apache2 \
243 --with-apr-util=/usr/local/apache2 ...
245 Be sure to use a native Windows SVN client (as opposed to
246 Cygwin's version) so that the .dsp files get carriage-returns at
247 the ends of their lines. Otherwise Visual Studio will complain
248 that it doesn't recognize the .dsp files.
250 If you use APR libraries checked out from svn in an Unix
251 environment, you need to run the 'buildconf' script in each
252 library's directory, to regenerate the configure scripts and
253 other files required for compiling the libraries:
255 $ cd apr; ./buildconf; ./configure ...; make; make install; cd ..
257 $ cd apr-util; ./buildconf; ./configure ...; make; make install; cd ..
259 Configure build and install both libraries before running Subversion's
265 Subversion requires SQLite version 3.8.2 or above. You can meet this
266 dependency several ways:
267 * Use an SQLite amalgamation file.
268 * Specify an SQLite installation to use.
269 * Let Subversion find an installed SQLite.
271 To use an SQLite-provided amalgamation, just drop sqlite3.c into
272 Subversion's sqlite-amalgamation/ directory, or point to it with the
273 --with-sqlite configure option. This file also ships with the Subversion
274 dependencies distribution, or you can download it from SQLite:
276 https://www.sqlite.org/download.html
281 Subversion's binary-differencing engine depends on zlib for
282 compression. Most Unix systems have libz pre-installed, but if
283 you need it, you can get it from
288 4. utf8proc (REQUIRED)
290 Subversion uses utf8proc for UTF-8 support. Configure will
291 attempt to locate utf8proc by default using pkg-config and known
294 If it is installed in a non-standard location, then use:
296 --with-utf8proc=/path/to/libutf8proc
298 Alternatively, a copy of utf8proc comes bundled with the
299 Subversion sources. If configure should use the bundled copy,
302 --with-utf8proc=internal
305 5. autoconf 2.59 or newer (Unix only)
307 This is required only if you plan to build from the latest source
308 (see section II.B). Generally only developers would be doing this.
311 6. libtool 1.4 or newer (Unix only)
313 This is required only if you plan to build from the latest source
316 Note: Some systems (Solaris, for example) require libtool 1.4.3 or
317 newer. The autogen.sh script knows about that.
320 7. Apache Serf library 1.3.4 or newer (OPTIONAL)
322 If you want your client to be able to speak to an Apache
323 server (via a http:// or https:// URL), you must link against
324 Apache Serf. Though optional, we strongly recommend this.
326 In order to use ra_serf, you must install serf, and run Subversion's
327 ./configure with the argument --with-serf. If serf is installed in a
328 non-standard place, you should use
330 --with-serf=/path/to/serf/install
334 Apache Serf can be obtained via your system's package distribution
335 system or directly from https://serf.apache.org/.
337 For more information on Apache Serf and Subversion's ra_serf, see the
338 file subversion/libsvn_ra_serf/README.
341 8. OpenSSL (OPTIONAL)
343 ### needs some updates. I think Apache Serf automagically handles
344 ### finding OpenSSL, but we may need more docco here. and w.r.t
347 The Apache Serf library has support for SSL encryption by relying on the
350 a. Using OpenSSL on the client through Apache Serf
352 On Unix systems, to build Apache Serf with OpenSSL, you need OpenSSL
353 installed on your system, and you must add "--with-ssl" as a
354 "./configure" parameter. If your OpenSSL installation is hard
355 for Apache Serf to find, you may need to use
356 "--with-libs=/path/to/lib" in addition. In particular, on Red Hat
357 (but not Fedora Core) it is necessary to specify
358 "--with-libs=/usr/kerberos" for OpenSSL to be found. You can also
359 specify a path to the zlib library using "--with-libs".
361 Under Windows, you can specify the paths to these libraries by
362 passing the options --with-zlib and --with-openssl to gen-make.py.
364 b. Using OpenSSL on the Apache server
366 You can also add support for these features to an Apache httpd
367 server to be used for Subversion using the same support libraries.
368 The Subversion build system will not provide them, however. You
369 add them by specifying parameters to the "./configure" script of
370 the Apache Server instead.
372 For getting SSL on your server, you would add the "--enable-ssl"
373 or "--with-ssl=/path/to/lib" option to Apache's "./configure"
374 script. Apache enables zlib support by default, but you can
375 specify a nonstandard location for the library with the
376 "--with-z=/path/to/dir" option. Consult the Apache documentation
377 for more details, and for other modules you may wish to install
378 to enhance your Subversion server.
380 If you don't already have it, you can get a copy of OpenSSL,
381 including instructions for building and packaging on both Unix
382 systems and Windows, at:
384 https://www.openssl.org/
387 9. Berkeley DB 4.X (DEPRECATED and OPTIONAL)
389 You need the Berkeley DB libraries only if you are building a
390 Subversion server that supports the older BDB repository storage
391 back-end, or a Subversion client that can access local BDB
392 repositories via the file:// URI scheme.
394 The BDB back-end has been deprecated and is not recommended for
395 new repositories. BDB may be removed in Subversion 2.0. We
396 recommend the newer FSFS back-end for all new repositories.
397 FSFS does not require the Berkeley DB libraries.
399 If in doubt, the 'svnadmin info' command, added in Subversion
400 1.9, can identify whether an existing repository uses BDB or
403 The current recommended version of Berkeley DB is 4.4.20 or
404 newer, which brings auto-recovery functionality to the Berkeley
405 DB database environment.
407 If you must use an older version of Berkeley DB, we *strongly*
408 recommend using 4.3 or 4.2 over the 4.1 or 4.0 versions. Not
409 only are these significantly faster and more stable, but they
410 also enable Subversion repositories to automatically clean up
411 database journal files to save disk space.
413 You'll need Berkeley DB installed on your system. You can
416 http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/overview/index.html
418 If you have Berkeley DB installed in a place not searched by default
419 for includes and libraries, add something like this:
421 --with-berkeley-db=db.h:/usr/local/include/db4.7:/usr/local/lib/db4.7:db-4.7
423 to your `configure' switches, and the build process will use the
424 Berkeley DB header and library in the named directories. You may
425 need to use a different path, of course. Note that in order for
426 the detection to succeed, the dynamic linker must be able to find
427 the libraries at configure time.
429 If you are on the Windows platform and want to build Subversion,
430 a precompiled version of the Berkeley DB library is available for
431 download at the Subversion web site "Documents & files" area:
433 http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=688
435 Look in the "Releases > Windows > Windows BDB" section.
438 10. Cyrus SASL library (OPTIONAL)
440 If the Simple Authentication and Security Layer (SASL) library
441 is detected on your system, then the Subversion client and
442 svnserve server can utilize its abilities for various forms of
443 authentication. To learn more about SASL or to get the source
446 http://freshmeat.net/projects/cyrussasl/
449 11. Apache Web Server 2.2.X or newer (OPTIONAL)
451 (https://httpd.apache.org/download.cgi)
453 The Apache httpd server is one of two methods to make your Subversion
454 repository available over a network - the other is a custom server
455 program called svnserve, which requires no extra software packages.
456 Building Subversion, the Apache server, and the modules that Apache
457 needs to communicate with Subversion are complicated enough that there
458 is a whole section at the end of this document that describes how it
459 is done: See section III for details.
462 12. Python 3.x or newer (https://www.python.org/) (OPTIONAL)
464 Subversion does not require Python for its basic operation.
465 However, Python is required for building and testing Subversion
466 and for using Subversion's SWIG Python bindings or hook scripts
469 The majority of Subversion's test suite is written in Python, as
470 is part of Subversion's build system.
472 In more detail, Python is required to do any of the following:
474 * Use the SWIG Python bindings.
475 * Use the ctypes Python bindings.
476 * Use hook scripts coded in Python.
477 * Build Subversion from a tarball on Unix-like systems and run
478 Subversion's test suite as described in section II.B.
479 * Build Subversion on Windows as described in section II.E.
480 * Build Subversion from a working copy checked out from
481 Subversion's own repository (whether or not running the test
483 * Build the SWIG Python bindings.
484 * Build the ctypes Python bindings.
485 * Testing as described in section III.D.
487 The Python bindings are used by:
489 * Third-party programs (e.g., ViewVC)
490 * Scripts distributed with Subversion itself in the tools/
492 * Any in-house scripts you may have.
494 Python is NOT required to do any of the following:
496 * Use the core command-line binaries (svn, svnadmin, svnsync,
498 * Use Subversion's C libraries.
499 * Use any of Subversion's other language bindings.
500 * Build Subversion from a tarball on Unix-like systems without
501 running Subversion's test suite
503 Although this section calls for Python 3.x, Subversion still
504 technically works with Python 2.7. However, Support for Python
505 2.7 is being phased out. As of 1 January 2020, Python 2.7 has
506 reached end of life. All users are strongly encouraged to move
510 13. Perl 5.8 or newer (Windows only) (OPTIONAL)
512 To build Subversion under any of the MS Windows platforms, you
513 will also need Perl 5.8 or newer to run apr-util's w32locatedb.pl
517 14. pkg-config (Unix only, OPTIONAL)
519 Subversion uses pkg-config to find appropriate options used
523 15. D-Bus (Unix only, OPTIONAL)
525 D-Bus is a message bus system. D-Bus is required for support for KWallet
526 and GNOME Keyring. pkg-config is needed to find D-Bus headers and library.
529 16. Qt 5 or Qt 4 (Unix only, OPTIONAL)
531 Qt is a cross-platform application framework. QtCore, QtDBus and QtGui
532 modules are required for support for KWallet. pkg-config is needed
533 to find Qt headers and libraries.
536 17. KDE 5 Framework libraries or KDELibs 4 (Unix only, OPTIONAL)
538 Subversion contains optional support for storing passwords in KWallet.
539 Subversion will look for KF5Wallet, KF5CoreAddons, KF5I18n APIs by default,
540 and needs kf5-config to find them. The KDELibs 4 api is also supported.
541 KDELibs contains core KDE libraries. Subversion uses libkdecore and libkdeui
542 libraries when support for KWallet is enabled. kde4-config is used to get
543 some necessary options. pkg-config, D-Bus and Qt 4 are also required.
545 If you want to build support for KWallet, then pass the '--with-kwallet'
546 option to `configure`. If KDE is installed in a non-standard prefix, then
549 --with-kwallet=/path/to/KDE/prefix
552 18. GLib 2 (Unix only, OPTIONAL)
554 GLib is a general-purpose utility library. GLib is required for support
555 for GNOME Keyring. pkg-config is needed to find GLib headers and library.
558 19. GNOME Keyring (Unix only, OPTIONAL)
560 Subversion contains optional support for storing passwords in GNOME Keyring.
561 pkg-config is needed to find GNOME Keyring headers and library. D-Bus and
562 GLib are also required. If you want to build support for GNOME Keyring,
563 then pass the '--with-gnome-keyring' option to `configure`.
566 20. Ctypesgen (OPTIONAL)
568 Ctypesgen is Python wrapper generator for ctypes. It is used to generate
569 a part of Subversion Ctypes Python bindings (CSVN). If you want to build
570 CSVN, then pass the '--with-ctypesgen' option to `configure`. If ctypesgen.py
571 is installed in a non-standard place, then use:
573 --with-ctypesgen=/path/to/ctypesgen.py
575 For more information on CSVN, see subversion/bindings/ctypes-python/README.
578 21. libmagic (OPTIONAL)
580 Subversion's configure script attempts to find libmagic automatically.
581 If it is installed in a non-standard location, then use:
583 --with-libmagic=/path/to/libmagic/prefix
585 The files include/magic.h and lib/libmagic.so.1.0 (or similar)
586 are expected beneath this prefix directory. If they cannot be
587 found Subversion will be compiled without support for libmagic.
589 If libmagic is installed but support for it should not be compiled
594 If configure should fail when libmagic is not present, but only
595 the default locations should be searched, then use:
602 Subversion uses LZ4 compression libary version r129 or above. Configure
603 will attempt to locate the system library by default using pkg-config
606 If it is installed in a non-standard location, then use:
608 --with-lz4=/path/to/liblz4
610 If configure should use the version bundled with the sources, use:
616 Subversion uses the Python 3 Compatibility Layer for C
617 Extensions (py3c) library when building the Python language
620 As py3c is a header-only library, it is needed only to build the
621 bindings, not to use them.
623 Configure will attempt to locate py3c by default using
624 pkg-config and known paths.
626 If it is installed in a non-standard location, then use:
628 --with-py3c=/path/to/py3c/prefix
630 The library can be downloaded from GitHub:
632 https://github.com/encukou/py3c
634 On Unix systems, you can also use the provided get-deps.sh
635 script to download py3c and several other dependencies; see the
636 top of section I.C for more about get-deps.sh.
641 The primary documentation for Subversion is the free book
642 "Version Control with Subversion", a.k.a. "The Subversion Book",
643 obtainable from http://svnbook.red-bean.com/.
645 Various additional documentation exists in the doc/ subdirectory of
646 the Subversion source. See the file doc/README for more information.
653 A. Building from a Tarball
654 ------------------------------
656 1. Building from a Tarball
658 Download the most recent distribution tarball from:
660 https://subversion.apache.org/download/
662 Unpack it, and use the standard GNU procedure to compile:
668 You can also run the full test suite by running 'make check'. Even
669 in successful runs, some tests will report XFAIL; that is normal.
670 Failed runs are indicated by FAIL or XPASS results, or a non-zero exit
671 code from "make check".
674 B. Building the Latest Source under Unix
675 -------------------------------------
677 These instructions assume you have already installed Subversion
678 and checked out a working copy of Subversion's own code --
679 either the latest /trunk code, or some branch or tag. You also
680 need to have already installed whatever prerequisites that
681 version of Subversion requires (if you haven't, the ./configure
682 step should complain).
684 You can discard the directory created by the tarball; you're
685 about to build the latest, greatest Subversion client. This is
686 the procedure Subversion developers use.
688 First off, if you have any Subversion libraries lying around
689 from previous 'make installs', clean them up first!
691 # rm -f /usr/local/lib/libsvn*
692 # rm -f /usr/local/lib/libapr*
693 # rm -f /usr/local/lib/libserf*
695 Start the process by running "autogen.sh":
699 This script will make sure you have all the necessary components
700 available to build Subversion. If any are missing, you will be
701 told where to get them from. (See the 'Dependency Overview' in
704 Note: if the command "autoconf" on your machine does not run
705 autoconf 2.59 or later, but you do have a new enough autoconf
706 available, then you can specify the correct one with the
707 AUTOCONF variable. (The AUTOHEADER variable is similar.) This
708 may be required on Debian GNU/Linux, where "autoconf" is
709 actually a Perl script that attempts to guess which version is
710 required -- because of the interaction between Subversion's and
711 APR's configuration systems, the Perl script may get it wrong.
712 So for example, you might need to do:
714 $ AUTOCONF=autoconf2.59 sh ./autogen.sh
716 Once you've prepared the working copy by running autogen.sh,
717 just follow the usual configuration and build procedure:
723 (Optionally, you might want to pass --enable-maintainer-mode to
724 the ./configure script. This enables debugging symbols in your
725 binaries (among other things) and most Subversion developers use it.)
727 Since the resulting binary depends on shared libraries, the
728 destination library directory must be identified in your
729 operating system's library search path. That is in either
730 /etc/ld.so.conf or $LD_LIBRARY_PATH for Linux systems and in
731 /etc/rc.conf for FreeBSD, followed by a run of the 'ldconfig'
732 program. Check your system documentation for details. By
733 identifying the destination directory, Subversion will be able
734 to dynamically load repository access plugins. If you try to do
735 a checkout and see an error like:
737 subversion/libsvn_ra/ra_loader.c:209: (apr_err=170000)
738 svn: Unrecognized URL scheme 'https://svn.apache.org/repos/asf/subversion/trunk'
740 It probably means that the dynamic loader/linker can't find all
741 of the libsvn_* libraries.
744 C. Building under Unix in Different Directories
745 --------------------------------------------
747 It is possible to configure and build Subversion on Unix in a
748 directory other than the working copy. For example
750 $ svn co https://svn.apache.org/repos/asf/subversion/trunk svn
752 $ # get SQLite amalgamation if required
753 $ chmod +x autogen.sh
757 $ ../svn/configure [...with options as appropriate...]
760 puts the Subversion working copy in the directory svn and builds
761 it in a separate, parallel directory obj.
763 Why would you want to do this? Well there are a number of
766 * You may prefer to avoid "polluting" the working copy with
767 files generated during the build.
769 * You may want to put the build directory and the working
770 copy on different physical disks to improve performance.
772 * You may want to separate source and object code and only
775 * You may want to remote mount the working copy on multiple
776 machines, and build for different machines from the same
779 * You may want to build multiple configurations from the
782 The last reason above is possibly the most useful. For instance
783 you can have separate debug and optimized builds each using the
784 same working copy. Or you may want a client-only build and a
785 client-server build. Using multiple build directories you can
786 rebuild any or all configurations after an edit without the need
787 to either clean and reconfigure, or identify and copy changes
788 into another working copy.
791 D. Installing from a Zip or Installer File under Windows
792 -----------------------------------------------------
794 Of all the ways of getting a Subversion client, this is the
795 easiest. Download a Zip or self-extracting installer via:
797 https://subversion.apache.org/packages.html#windows
799 For a Zip file extract the DLLs and EXEs to a directory of your
800 choice. Included in the download are among other tools the SVN
801 client, the SVNADMIN administration tool and the SVNLOOK reporting
804 You may want to add the bin directory in the Subversion folder to your
805 PATH environment variable so as to not have to use the full path when
806 running Subversion commands.
808 To test the installation, open a DOS box (run either "cmd" or
809 "command" from the Start menu's "Run..." menu option), change to
810 the directory you installed the executables into, and run:
812 C:\test>svn co https://svn.apache.org/repos/asf/subversion/trunk svn
814 This will get the latest Subversion sources and put them into the
817 If using a self-extracting .exe file, just run it instead of
818 unzipping it, to install Subversion.
820 E. Building the Latest Source under Windows
821 ----------------------------------------
825 * Microsoft Visual Studio. Any recent (2005+) version containing the
826 Visual C++ component will work (E.g. Professional, Express, Community
827 Edition). Make sure you enable C++ support during setup.
828 * Python 2.7 or higher, downloaded from https://www.python.org/ which is
829 used to generate the project files.
830 * Perl 5.8 or higher from https://www.perl.org/get.html
831 * Awk (from https://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe) is
832 needed to compile Apache. Note that this is the actual awk program,
833 not an installer - just rename it to awk.exe and it is ready to use.
834 * Apache apr, apr-util, and optionally apr-iconv libraries, version
835 1.5 or later (1.2 for apr-iconv). If you are building from a Subversion
836 checkout and have not downloaded Apache 2, then get these 3 libraries
837 from https://www.apache.org/dist/apr/.
838 * SQLite 3.8.2 or higher from https://www.sqlite.org/download.html
839 (3.8.11.1 or higher recommended)
840 * ZLib 1.2 or higher is required and can be obtained from
842 * Either a Subversion client binary from
843 https://subversion.apache.org/packages.html to do the initial checkout
844 of the Subversion source or the zip file source distribution.
848 * [Optional] Apache Httpd 2 source, downloaded from
849 https://httpd.apache.org/download.cgi, these instructions assume
850 version 2.0.58. This is only needed for building the Subversion
851 server Apache modules. ### FIXME Apache 2.2 or greater required.
852 * [Optional] Berkeley DB for backend support of the server components
854 http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index-082944.html
855 (Version 4.4.20 or in specific cases some higher version recommended)
856 For more information see Section I.C.7.
857 * [Optional] Openssl can be obtained from https://www.openssl.org/source/
858 * [Optional] NASM can be obtained from http://www.nasm.us/
859 * [Optional] A modified version of GNU libintl, called
860 svn-win32-libintl.zip, can be used for displaying localized
861 messages. Available at:
862 http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=2627
863 * [Optional] GNU gettext for generating message catalog (.mo)
864 files from message translations. You can get the latest
865 binaries from http://gnuwin32.sourceforge.net/. You'll need the
866 binaries (gettext-0.14.1-bin.zip) and dependencies
867 (gettext-0.14.1-dep.zip).
871 The Apache Serf library supports secure connections with OpenSSL
872 and on-the-wire compression with zlib. If you want to use the
873 secure connections feature, you should pass the option
874 "--with-openssl" to the gen-make.py script. See Section I.C.6 for
879 This section describes how to unpack the files to make a build tree.
881 * Make a directory SVN and cd into it.
882 * Either checkout Subversion:
884 svn co https://svn.apache.org/repos/asf/subversion/trunk src-trunk
886 or unpack the zip file distribution and rename the directory to
889 * Install Visual Studio Environment. You either have to tell the
890 installer to register environment variables or run VCVARS32.BAT
891 before building anything. If you are using a newer Visual Studio,
892 use the 'Visual Studio 20xx Command Prompt' on the Start menu.
893 * Install Python and add it to your path
894 * Install Perl (it should add itself to the path)
895 ### Subversion doesn't need perl. Only some dependencies need it
896 (OpenSSL and some apr scripts)
897 * Copy AWK (awk95.exe) to awk.exe (e.g. SVN\awk\awk.exe) and add
898 the directory containing it (e.g. SVN\awk) to the path.
899 ### Subversion doesn't need awk. Only some dependencies need it
901 * [Optional] Install NASM and add it to your path
902 ### Subversion doesn't need NASM. Only some dependencies need it
904 * [Optional] If you checked out Subversion from the repository and want
905 to build Subversion with http/https access support then install the
906 Apache Serf sources into SVN\src-trunk\serf.
907 * [Optional] If you want BDB backend support, extract the Berkeley DB
908 files into SVN\src-trunk\db4-win32. It's a good idea to add
909 SVN\src-trunk\db4-win32\bin to your PATH, so that Subversion can find
910 the Berkeley DB DLLs.
912 [NOTE: This binary package of Berkeley DB is provided for
913 convenience only. Please don't address questions about
914 Berkeley DB that aren't directly related to using Subversion
915 to the project mailing list.]
917 If you build Berkeley DB from the source, you will have to copy
918 the file db-x.x.x\build_win32\db.h to
919 SVN\src-trunk\db4-win32\include, and all the import libraries to
920 SVN\src-trunk\db4-win32\lib. Again, the DLLs should be somewhere in
922 ### Just use --with-serf instead of the hardcoded path
924 * [Optional] If you want to build the server modules, extract Apache
925 source into SVN\httpd-2.x.x.
926 * If you are building from a checkout of Subversion, and you are NOT
927 building Apache, then you will need the APR libraries. Depending
928 on how you got your version of APR, either:
929 - Extract the APR, APR-util and APR-iconv source distributions into
930 SVN\apr, SVN\apr-util, and SVN\apr-iconv respectively.
932 - Extract the apr, apr-util and apr-iconv directories from the
933 srclib folder in the Apache httpd source into SVN\apr,
934 SVN\apr-util, and SVN\apr-iconv respectively.
935 ### Just use --with-apr, etc. instead of the hardcoded paths
936 * Extract the ZLib sources into SVN\zlib if you are not using the zlib
937 included in the dependencies zip file.
938 ### Just use --with-zlib instead of the hardcoded path
939 * [Optional] If you want secure connection (https) client support extract
940 OpenSSL into SVN\openssl
941 ### And pass the path to both serf and gen-make.py
942 * [Optional] If you want localized message support, extract
943 svn-win32-libintl.zip into SVN\svn-win32-libintl and extract
944 gettext-x.x.x-bin.zip and gettext-x.x.x-dep.zip into
945 SVN\gettext-x.x.x-bin.
946 Add SVN\gettext-x.x.x-bin\bin to your path.
947 * Download the SQLite amalgamation from
948 https://www.sqlite.org/download.html
949 and extract it into SVN\sqlite-amalgamation.
950 See I.C.12 for alternatives to using the amalgamation package.
952 E.4 Building the Binaries
954 To build the binaries either follow these instructions.
956 Start in the SVN directory you created.
958 Set up the environment (commands should be one line even if wrapped here).
962 C:>set BUILD_ROOT=C:\SVN
963 C:>set PYTHONDIR=C:\Python27
964 C:>set AWKDIR=C:\SVN\Awk
965 C:>set ASMDIR=C:\SVN\asm
966 C:>set SDKINC="C:\Program Files\Microsoft SDK\include"
967 C:>set SDKLIB="C:\Program Files\Microsoft SDK\lib"
968 C:>set GETTEXTBIN=C:\SVN\gettext-0.14.1-bin\bin
969 C:>PATH=%PATH%;%BUILD_ROOT%\src-%DIR%\db4-win32;%ASMDIR%;
970 %PYTHONDIR%;%AWKDIR%;%GETTEXTBIN%
971 C:>set INCLUDE=%SDKINC%;%INCLUDE%
972 C:>set LIB=%SDKLIB%;%LIB%
977 C:>perl Configure VC-WIN32
978 [*] C:>call ms\do_masm
979 C:>nmake -f ms\ntdll.mak
984 *Note: Use "call ms\do_nasm" if you have nasm instead of MASM, or
985 "call ms\do_ms" if you don't have an assembler.
986 Also if you are using OpenSSL >= 1.0.0 masm is no longer
987 supported. You will have to use do_nasm or do_ms in this case.
992 C:>perl Configure VC-WIN32
999 This step is only required for building the server dso modules.
1001 ### FIXME Apache 2.2 or greater required. Old build instructions for VC6.
1003 C:>set APACHEDIR=C:\Program Files\Apache Group\Apache2
1004 C:>msdev httpd-2.0.58\apache.dsw /MAKE "BuildBin - Win32 Release"
1008 If you downloaded APR / APR-UTIL / APR_ICONV by source, you will have to
1009 build these libraries first.
1010 Building these libraries on Windows is straight forward and in most cases
1011 as simple as issuing these two commands:
1013 C:>nmake -f Makefile.win
1014 C:>nmake -f Makefile.win install
1016 Please refer to the build instructions provided by the library source
1017 for actual build instructions.
1021 If you downloaded the zlib source, you will have to build ZLib first.
1022 Building ZLib using Visual Studio should be quite simple. Just open the
1023 appropriate solution and build the project zlibstat using the IDE.
1025 Please refer to the build instructions provided by the library source
1026 for actual build instructions.
1028 Note that you'd make sure to define ZLIB_WINAPI in the ZLib config
1029 header and move the lib-file into the zlib root-directory.
1033 ### Section about Apache Serf might be required/useful to add.
1034 ### scons is required too and Apache Serf needs to be configured prior to
1035 ### be able to build Subversion using:
1036 ### scons APR=[PATH_TO_APR] APU=[PATH_TO_APU] OPENSSL=[PATH_TO_OPENSSL]
1037 ### ZLIB=[PATH_TO_ZLIB] PREFIX=[PATH_TO_SERF_DEST]
1045 * If you don't want to build mod_dav_svn, omit the --with-httpd
1046 option. The zip file source distribution contains apr, apr-util and
1047 apr-iconv in the default build location. If you have downloaded the
1048 apr files yourself you will have to tell the generator where to find
1049 the APR libraries; the options are --with-apr, --with-apr-util and
1051 * If you would like a debug build substitute Debug for Release in
1052 the msbuild command.
1053 * There have been rumors that Subversion on Win32 can be built
1054 using the latest cygwin, you probably don't want the zip file source
1055 distribution though. ymmv.
1056 * You will also have to distribute the C runtime dll with the binaries.
1057 Also, since Apache/APR do not provide .vcproj files, you will need to
1058 convert the Apache/APR .dsp files to .vcproj files with Visual Studio
1059 before building -- just open the Apache .dsw file and answer 'Yes To
1060 All' when the conversion dialog pops up, or you can open the individual
1061 .dsp files and convert them one at a time.
1062 The Apache/APR projects required by Subversion are:
1063 apr-util\libaprutil.dsp, apr\libapr.dsp,
1064 apr-iconv\libapriconv.dsp, apr-util\xml\expat\lib\xml.dsp,
1065 apr-iconv\ccs\libapriconv_ccs_modules.dsp, and
1066 apr-iconv\ces\libapriconv_ces_modules.dsp.
1067 * If the server dso modules are being built and tested Apache must not
1068 be running or the copy of the dso modules will fail.
1072 If Apache 2 has been built and the server modules are required then
1073 gen-make.py will already have been run. If the source is from the zip
1074 file, Apache 2 has not been built so gen-make.py must be run:
1076 C:>python gen-make.py --vsnet-version=20xx --with-berkeley-db=db4-win32
1077 --with-openssl=..\openssl --with-zlib=..\zlib
1078 --with-libintl=..\svn-win32-libintl
1080 Then build subversion:
1082 C:>msbuild subversion_vcnet.sln /t:__MORE__ /p:Configuration=Release
1085 The binaries have now been built.
1087 E.5 Packaging the binaries
1089 You now need to copy the binaries ready to make the release zip
1090 file. You also need to do this to run the tests as the new binaries
1091 need to be in your path. You can use the build/win32/make_dist.py
1092 script in the Subversion source directory to do that.
1094 [TBD: Describe how to do this. Note dependencies on zip, jar, doxygen.]
1096 E.6 Testing the Binaries
1097 [TBD: It's been a long, long while since it was necessary to move
1098 binaries around for testing. win-tests.py does that automagically.
1099 Fix this section accordingly, and probably reorder, putting
1100 the packaging at the end.]
1102 The build process creates the binary test programs but it does not
1103 copy the client tests into the release test area.
1106 C:>mkdir Release\subversion\tests\cmdline
1107 C:>xcopy /S /Y subversion\tests\cmdline Release\subversion\tests\cmdline
1109 If the server dso modules have been built then copy the dso files and
1110 dlls into the Apache modules directory.
1112 C:>copy Release\subversion\mod_dav_svn\mod_dav_svn.so "%APACHEDIR%"\modules
1113 C:>copy Release\subversion\mod_authz_svn\mod_authz_svn.so
1114 "%APACHEDIR%"\modules
1115 C:>copy svn-win32-%VER%\bin\intl.dll "%APACHEDIR%\bin"
1116 C:>copy svn-win32-%VER%\bin\iconv.dll "%APACHEDIR%\bin"
1117 C:>copy svn-win32-%VER%\bin\libdb42.dll "%APACHEDIR%\bin"
1120 Put the svn-win32-trunk\bin directory at the start of your path so
1121 you run the newly built binaries and not another version you might
1124 Then run the client tests:
1126 C:>PATH=%BUILD_ROOT%\svn-win32-%VER%\bin;%PATH%
1128 C:>python win-tests.py -c -r -v
1130 If the server dso modules were built configure Apache to use the
1131 mod_dav_svn and mod_authz_svn modules by making sure these lines appear
1132 uncommented in httpd.conf:
1134 LoadModule dav_module modules/mod_dav.so
1135 LoadModule dav_fs_module modules/mod_dav_fs.so
1136 LoadModule dav_svn_module modules/mod_dav_svn.so
1137 LoadModule authz_svn_module modules/mod_authz_svn.so
1139 And further down the file add location directives to point to the
1140 test repositories. Change the paths to the SVN directory you created
1141 (paths should be on one line even if wrapped here):
1143 <Location /svn-test-work/repositories>
1145 SVNParentPath C:/SVN/src-trunk/Release/subversion/tests/cmdline/
1146 svn-test-work/repositories
1149 <Location /svn-test-work/local_tmp/repos>
1151 SVNPath c:/SVN/src-trunk/Release/subversion/tests/cmdline/
1152 svn-test-work/local_tmp/repos
1155 Then restart Apache and run the tests:
1157 C:>python win-tests.py -c -r -v -u http://localhost
1160 III. BUILDING A SUBVERSION SERVER
1161 ============================
1163 Subversion has two servers you can choose from: svnserve and
1164 Apache. svnserve is a small, lightweight server program that is
1165 automatically compiled when you build Subversion's source. Apache
1166 is a more heavyweight HTTP server, but tends to have more features.
1168 This section primarily focuses on how to build Apache and the
1169 accompanying mod_dav_svn server module for it. If you plan to use
1170 svnserve instead, jump right to section E for a quick explanation.
1173 A. Setting Up Apache Httpd
1174 -----------------------
1176 1. Obtaining and Installing Apache Httpd 2
1178 Subversion tries to compile against the latest released version
1179 of Apache httpd 2.2+. The easiest thing for you to do is download
1180 a source tarball of the latest release and unpack that.
1182 If you have questions about the Apache httpd 2.2 build, please consult
1183 the httpd install documentation:
1185 https://httpd.apache.org/docs-2.2/install.html
1187 At the top of the httpd tree:
1190 $ ./configure --enable-dav --enable-so --enable-maintainer-mode
1192 The first arg says to build mod_dav.
1194 The second arg says to enable shared module support which is needed
1195 for a typical compile of mod_dav_svn (see below).
1197 The third arg says to include debugging information. If you
1198 built Subversion with --enable-maintainer-mode, then you should
1199 do the same for Apache; there can be problems if one was
1200 compiled with debugging and the other without.
1202 Note: if you have multiple db versions installed on your system,
1203 Apache might link to a different one than Subversion, causing
1204 failures when accessing the repository through Apache. To prevent
1205 this from happening, you have to tell Apache which db version to
1206 use and where to find db. Add --with-dbm=db4 and
1207 --with-berkeley-db=/usr/local/BerkeleyDB.4.2 to the configure
1208 line. Make sure this is the same db as the one Subversion uses.
1209 This note assumes you have installed Berkeley DB 4.2.52
1210 at its default locations. For more info about the db requirement,
1213 You may also want to include other modules in your build. Add
1214 --enable-ssl to turn on SSL support, and --enable-deflate to turn on
1215 compression support, for example. Consult the Apache documentation
1218 All instructions below assume you configured Apache to install
1219 in its default location, /usr/local/apache2/; substitute
1220 appropriately if you chose some other location.
1222 Compile and install apache:
1224 $ make && make install
1227 B. Making and Installing the Subversion Apache Server Module
1228 ---------------------------------------------------------
1230 Go back into your subversion working copy and run ./autogen.sh if
1231 you need to. Then, assuming Apache httpd 2.2 is installed in the
1232 standard location, run:
1236 Note: do *not* configure subversion with "--disable-shared"!
1237 mod_dav_svn *must* be built as a shared library, and it will
1238 look for other libsvn_*.so libraries on your system.
1240 If you see a warning message that the build of mod_dav_svn is
1241 being skipped, this may be because you have Apache httpd 2.x
1242 installed in a non-standard location. You can use the
1243 "--with-apxs=" option to locate the apxs script:
1245 $ ./configure --with-apxs=/usr/local/apache2/bin/apxs
1247 Note: it *is* possible to build mod_dav_svn as a static library
1248 and link it directly into Apache. Possible, but painful. Stick
1249 with the shared library for now; if you can't, then ask.
1251 $ rm /usr/local/lib/libsvn*
1253 If you have old subversion libraries sitting on your system,
1254 libtool will link them instead of the `fresh' ones in your tree.
1255 Remove them before building subversion.
1257 $ make clean && make && make install
1259 After the make install, the Subversion shared libraries are in
1260 /usr/local/lib/. mod_dav_svn.so should be installed in
1261 /usr/local/libexec/ (or elsewhere, such as /usr/local/apache2/modules/,
1262 if you passed --with-apache-libexecdir to configure).
1265 Section II.E explains how to build the server on Windows.
1268 C. Configuring Apache Httpd for Subversion
1269 ---------------------------------------
1271 The following section is an abbreviated version of the
1272 information in the Subversion Book
1273 (http://svnbook.red-bean.com). Please read chapter 6 for more
1276 The following assumes you have already created a repository.
1277 For documentation on how to do that, see README.
1279 The following also assumes that you have modified
1280 /usr/local/apache2/conf/httpd.conf to reflect your setup.
1281 At a minimum you should look at the User, Group and ServerName
1282 directives. Full details on setting up apache can be found at:
1283 https://httpd.apache.org/docs-2.2/
1285 First, your httpd.conf needs to load the mod_dav_svn module.
1286 If you pass --enable-mod-activation to Subversion's configure,
1287 'make install' target should automatically add this line for you.
1288 In any case, if Apache HTTPD gives you an error like "Unknown
1289 DAV provider: svn", then you may want to verify that this line
1290 exists in your httpd.conf:
1292 LoadModule dav_svn_module modules/mod_dav_svn.so
1294 NOTE: if you built mod_dav as a dynamic module as well, make sure
1295 the above line appears after the one that loads mod_dav.so.
1297 Next, add this to the *bottom* of your httpd.conf:
1299 <Location /svn/repos>
1301 SVNPath /absolute/path/to/repository
1304 This will give anyone unrestricted access to the repository. If
1305 you want limited access, read or write, you add these lines to
1309 AuthName "Subversion repository"
1310 AuthUserFile /my/svn/user/passwd/file
1314 a) For a read/write restricted repository:
1318 b) For a write restricted repository:
1320 <LimitExcept GET PROPFIND OPTIONS REPORT>
1324 c) For separate restricted read and write access:
1326 AuthGroupFile /my/svn/group/file
1328 <LimitExcept GET PROPFIND OPTIONS REPORT>
1329 Require group svn_committers
1332 <Limit GET PROPFIND OPTIONS REPORT>
1333 Require group svn_committers
1334 Require group svn_readers
1337 ### FIXME Tutorials section refers to old 2.0 docs
1338 These are only a few simple examples. For a complete tutorial
1339 on Apache access control, please consider taking a look at the
1340 tutorials found under "Security" on the following page:
1341 https://httpd.apache.org/docs-2.0/misc/tutorials.html
1343 In order for 'svn cp' to work (which is actually implemented as a
1344 DAV COPY command), mod_dav needs to be able to determine the
1345 hostname of the server. A standard way of doing this is to use
1346 Apache's ServerName directive to set the server's hostname. Edit
1347 your /usr/local/apache2/conf/httpd.conf to include:
1349 ServerName svn.myserver.org
1351 If you are using virtual hosting through Apache's NameVirtualHost
1352 directive, you may need to use the ServerAlias directive to specify
1353 additional names that your server is known by.
1355 If you have configured mod_deflate to be in the server, you can enable
1356 compression support for your repository by adding the following line
1357 to your Location block:
1359 SetOutputFilter DEFLATE
1362 NOTE: If you are unfamiliar with an Apache directive, or not exactly
1363 sure about what it does, don't hesitate to look it up in the
1364 documentation: https://httpd.apache.org/docs-2.2/mod/directives.html.
1366 NOTE: Make sure that the user 'nobody' (or whatever UID the
1367 httpd process runs as) has permission to read and write the
1368 Berkeley DB files! This is a very common problem.
1371 D. Running and Testing
1376 $ /usr/local/apache2/bin/apachectl stop
1377 $ /usr/local/apache2/bin/apachectl start
1379 Check /usr/local/apache2/logs/error_log to make sure it started
1382 Try doing a network checkout from the repository:
1384 $ svn co http://localhost/svn/repos wc
1386 The most common reason this might fail is permission problems
1387 reading the repository db files. If the checkout fails, make
1388 sure that the httpd process has permission to read and write to
1389 the repository. You can see all of mod_dav_svn's complaints in
1390 the Apache error logfile, /usr/local/apache2/logs/error_log.
1392 To run the regression test suite for networked Subversion, see
1393 the instructions in subversion/tests/cmdline/README.
1394 For advice about tracing problems, see "Debugging the server" in
1395 https://subversion.apache.org/docs/community-guide/.
1398 E. Alternative: 'svnserve' and ra_svn
1399 -----------------------------------
1401 An alternative network layer is libsvn_ra_svn (on the client
1402 side) and the 'svnserve' process on the server. This is a
1403 simple network layer that speaks a custom protocol over plain
1404 TCP (documented in libsvn_ra_svn/protocol):
1406 $ svnserve -d # becomes a background daemon
1407 $ svn checkout svn://localhost/usr/local/svn/repository
1409 You can use the "-r" option to svnserve to set a logical root
1410 for repositories, and the "-R" option to restrict connections to
1411 read-only access. ("Read-only" is a logical term here; svnserve
1412 still needs write access to the database in this mode, but will
1413 not allow commits or revprop changes.)
1415 'svnserve' has built-in CRAM-MD5 authentication (so you can use
1416 non-system accounts), and can also be tunneled over SSH (so you
1417 can use existing system accounts). It's also capable of using
1418 Cyrus SASL if libsasl2 is detected at ./configure time. Please
1419 read chapter 6 in the Subversion Book
1420 (http://svnbook.red-bean.com) for details on these features.
1424 IV. PLATFORM-SPECIFIC ISSUES
1425 ========================
1430 There is an error in the Windows XP TCP/IP stack which causes
1431 corruption in certain cases. This problem is exposed only
1434 The root of the matter is caused by duplicating file handles
1435 between parent and child processes. The httpd Apache group
1436 explains this a lot better:
1438 https://www.apache.org/dist/httpd/binaries/win32/#xpbug
1440 And there's an item about this in the Subversion FAQ:
1442 https://subversion.apache.org/faq.html#windows-xp-server
1444 The only known workaround for now is to update to Windows XP
1451 [TBD: Describe BDB 4.0.x problem]
1455 V. PROGRAMMING LANGUAGE BINDINGS (PYTHON, PERL, RUBY, JAVA)
1456 ========================================================
1458 For Python, Perl and Ruby bindings, see the file
1460 ./subversion/bindings/swig/INSTALL
1462 For Java bindings, see the file
1464 ./subversion/bindings/javahl/README