====================================== INSTALLING AND USING SUBVERSION A Guide for Newcomers ====================================== ******************************************************************** *** *** *** Note: this is PRE-ALPHA code. Don't use it on real data, *** *** except for Subversion itself, and that only because hordes *** *** of selfless volunteers are standing by ready to help you *** *** if you get yourself in a pickle. *** *** *** ******************************************************************** I. THEORY AND DOCUMENTATION A. DESIGN A design spec was written in June 2000, and is a bit out of date. But it still gives a good theoretical introduction to the inner workings of the repository, and to Subversion's various layers. Look in doc/programmer/design/, or look at one of the versions posted on the Subversion website. B. WEBDAV Greg Stein has written an introduction Subversion's network protocol, which is an extended dialect of HTTP. The document is 'www/webdav-usage.html', and is also posted on the website. C. USER MANUAL We've started documenting some of the behavior of the client; it's only a small beginning, but it may help. Look at doc/user/manual/ for this project. II. PARTICIPATING Read the HACKING file! It describes Subversion coding and log message standards, as well as how to join discussion lists. Talk on IRC with developers: irc.openprojects.net, channel #svn. Read the FAQ: http://subversion.tigris.org/project_faq.html III. INSTALLATION A. BOOTSTRAPPING FROM A TARBALL In order to get the very latest Subversion source code, you need to check it out of a Subversion repository, and therefore you first need a Subversion client. Download the most recent distribution tarball from: http://subversion.tigris.org/servlets/ProjectDownloadList Unpack it, and use the standard GNU procedure to compile: $ ./configure --enable-maintainer-mode --disable-shared $ make (The first switch to ./configure turns on debugging, and the second switch builds a statically-linked client binary.) After compiling, you will have a large 'svn' binary sitting in the tree. Use it to check out a real Subversion working copy: $ subversion/clients/cmdline/svn checkout \ http://svn.collab.net/repos/svn/trunk -d svn A svn/dist.sh A svn/buildcheck.sh A svn/HACKING ... B. BUILDING THE LATEST SOURCE You can discard the directory created by the tarball; you're about to build the latest, greatest Subversion client. First off, if you have any Subversion libraries lying around from previous 'make installs', clean them up first! # rm -f /usr/local/lib/libsvn* # rm -f /usr/local/lib/libapr* # rm -f /usr/local/lib/libexpat* # rm -f /usr/local/lib/libneon* Start the process by running "autogen.sh": $ chmod +x autogen.sh # if not already executable $ ./autogen.sh This script will make sure you have all the necessary components available to build Subversion. If any are missing, you will be told where to get them from. (See the 'requirements' section further down.) After all components are in place, follow the usual procedure: $ ./configure --enable-maintainer-mode --disable-shared $ make $ make check (optional) # make install The flags to `configure' are highly recommended for developers, as they build a statically-linked binary. If you don't use those flags, then you must reverse the order of the "make check" and "make install" steps, because the shared libraries must be installed before "make check" will work. Additionally, with shared library builds, the destination library directory must be listed in either /etc/ld.so.conf or $LD_LIBRARY_PATH (for linux systems), so that Subversion will be able to dynamically load repository access plugins. If you try to do a checkout and see an error like: svn_error: #21068 : Unrecognized URL scheme: http://svn.collab.net/repos/svn/trunk It probably means that the dynamic loader/linker can't find all of the libsvn_* libraries. Note that if you commonly build with the -jN option to make, the make step above may fail, because we don't ensure that third party libraries in our source tree will finish building before subversion itself. If you want to use -jN, use the following instead: $ ./configure --enable-maintainer-mode --disable-shared $ make -jN external-all $ make -jN local-all $ make check # make install C. BUILD REQUIREMENTS 1. Berkeley DB Berkeley DB is needed to build a Subversion server, or to access a repository on local disk. If you are only interested in building a Subversion client that speaks to a remote (networked) repository, you don't need it. You'll need Berkeley DB 4.0.14 installed on your system. You can get it from http://www.sleepycat.com/. If you already have another version of Berkeley DB installed and don't want to downgrade, you can unpack the Berkeley 4.0.14 distribution into a subdir named `db' in the top-level of the Subversion source tree. Then Subversion will ignore the system DB and use the one it found in its own source tree. Alternatively, you can add this flag --with-berkeley-db=/usr/local/BerkeleyDB.4.0 to your `configure' switches, and the build process will use the named Berkeley. You may need to use a different path, of course. 2. Python 2.0 If you want to run "make check", install Python 2.0 or higher on your system, as the majority of the test suite is written in Python. Get it from http://www.python.org/. IV. QUICKSTART GUIDE A. REPOSITORIES 1. REPOSITORY ACCESS The Subversion client has an abstract interface for accessing a repository. Two "Repository Access" (RA) implementations currently exist as libraries: libsvn_ra_dav: accesses a networked repository using WebDAV. libsvn_ra_local: accesses a local repository using Berkeley DB. You can see which methods are available to your 'svn' client like so: $ svn --version Subversion Client, version 0.6.0 compiled Nov 27 2001, 21:15:44 Copyright (C) 2000-2001 CollabNet. Subversion is open source software, see http://subversion.tigris.org/ The following repository access (RA) modules are available: * ra_dav : Module for accessing a repository via WebDAV protocol. - handles 'http' schema * ra_local : Module for accessing a repository on local disk. - handles 'file' schema If you don't see ra_local, it probably means that Berkeley DB wasn't found when compiling your client binary. If you don't see ra_dav, then something is very wrong; most likely your dynamic loader/linker can't find libsvn_ra_dav.so (see section I.B above.) 2. CREATING A REPOSITORY A Subversion repository is an ordinary directory that mainly contains Berkeley DB .db files. You can only create a repository if you have Berkeley DB available on your system and it was found during the compile. If this is true, you should have a utility called 'svnadmin' installed. 'svnadmin' does many things, but its most important feature is creating an empty repository: % svnadmin create /usr/local/svn/repos1 After the repository is created, you can initially import data into it, using libsvn_ra_local (invoked by using a 'file' URL): % svn import file:///usr/local/svn/repos1 some/local/dir/ The above example imports the contents of some/local/dir/ right into the root of the repository. If you want to put these contents into a newly-created repository subdirectory, use *three* args to import. (Try 'svn help import' for details). Also, watch out for 'ownership' pitfalls. Notice who has the rights to modify the .db files in the repository. Repository commit access is ultimately determined by whomever has the rights to modify the .db files. 3. CREATING A SUBVERSION SERVER Subversion uses Apache 2.0 as its network server. Apache's mod_dav speaks to a special mod_dav_svn module, which uses Berkeley DB to talk to a repository. Apache's own authentication system allows remote users to access the repository with Subversion clients. However: make sure that Apache has the right to edit the .db files itself, or you'll get all sorts of Apache errors. Often people create a special 'svn' user who owns the repository, and folks put a line into httpd.conf that tells Apache to run as that special user. Compiling Apache and mod_dav_svn is a separate project; please see section V at the end of this document for a HOWTO. B. EXAMPLE WALKTHOUGH Here are some simple examples of how one might use the svn client. In general, things are designed to be similar to CVS. But many things are different. *PLEASE* read the 'SVN for CVS Users' document (in docs/, or on the website) to understand the broader concepts of what's going on! # Checkout a working copy. This can either be a file: or # http: url, depending on which RA modules are available. $ svn co file:///usr/local/svn/repos1 -d wc A wc/foo A wc/bar A wc/baz A wc/baz/gloo A wc/baz/bloo $ cp -R wc wc2 # back up this working copy $ cd wc $ echo "new text" >> bar # change bar's text $ svn propset color green foo # add a metadata property to foo $ svn rm baz # schedule baz directory for deletion $ touch newfile $ svn add newfile # schedule newfile for addition $ svn status # See what's locally modified M ./bar _M ./foo A ./newfile D ./baz D ./baz/gloo D ./baz/bloo $ svn commit -m "Made many changes" # Commit the changes Sending bar Sending foo Adding newfile Deleting baz Commit succeeded. $ cd ../wc2 # change to the back-up working copy $ svn update # get changes from repository U ./bar _U ./foo A ./newfile D ./baz V. BUILDING A SUBVERSION SERVER 1. Checkout the "httpd-2.0" cvs module from apache.org. Put it whereever you wish; it's an independent project. cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login (password 'anoncvs') cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co httpd-2.0 2. cd httpd-2.0/srclib/, and checkout the "apr" and "apr-util" modules into this directory: cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr-util 3. At the top of the httpd-2.0 tree: ./buildconf ./configure --enable-dav --enable-so --prefix=/usr/local/apache2 The first arg says to build mod_dav. The second arg says to enable (and build everything) as shared libs. The third arg is where you will ultimately install apache. Note: if you build Subversion with --enable-maintainer-mode, then do the same for Apache. mod_dav_svn uses Apache's maintainer-mode stuff from its headers, so you want to ensure that Apache is built with the same assumption. Just add --enable-maintainer-mode to the configure line above. Note: if you have multiple db versions installed on your system, Apache might link to a different one than Subversion, causing failures when accessing the repository through Apache. To prevent this from happening, you have to tell Apache where to find the version of db subversion uses. Right before configure: export LDFLAGS=-L/usr/local/BerkeleyDB.4.0/lib export CPPFLAGS=-I/usr/local/BerkeleyDB.4.0/include Add --with-dbm=db4 to the configure line. This note assumes you have installed Berkeley DB 4.0.14 at its default locations. For more info about the db requirement, see section III.C.1. All instructions below assume you configured Apache to install under /usr/local/apache2/; substitute appropriately if you chose some other location. 4. make depend && make && make install 5. Go back into your subversion working copy and run ./autogen.sh if you need to. Then run ./configure --with-apxs=/usr/local/apache2/bin/apxs This argument tells subversion to build mod_dav_svn, and where to find the required information to do so. Note: do *not* configure subversion with "--disable-shared"! mod_dav_svn *must* be built as a shared library, and it will look for other libsvn_*.so libraries on your system. Note: it *is* possible to build mod_dav_svn as a static library and link it directly into Apache. Possible, but painful. Stick with the shared library for now; if you can't, then ask. 6. rm /usr/local/lib/libsvn* If you have old subversion libraries sitting on your system, libtool will link them instead of the `fresh' ones in your tree. Remove them before building subversion. 7. make clean && make && make install After the make install, the Subversion shared libraries are in /usr/local/lib/. libmod_dav_svn.so should be installed in /usr/local/apache2/modules/. 8. Add this to the *bottom* of /usr/local/apache2/conf/httpd.conf: DAV svn SVNPath /absolute/path/to/repository NOTE: Make sure that the user 'nobody' (or whatever UID the httpd process runs as) has permission to read and write the Berkeley DB files! This is a very common problem. 9. Now fire up apache 2.0: /usr/local/apache2/bin/apachectl stop /usr/local/apache2/bin/apachectl start Check /usr/local/apache2/logs/error_log to make sure it started up okay. 10. Finally, try doing a network checkout from the repository: svn co http://localhost/svn/repos -d wc The most common reason this might fail is permission problems reading the repository db files. If the checkout fails, chmod 777 and try again. You can see all of mod_dav_svn's complaints in the Apache error logfile, /usr/local/apache2/logs/error_log. For more information about tracing problems, see "Debugging the server" in the HACKING file.