Ok, I've reworked this patch as requested and thrown in a few more small
changes:
- Neon is still listed as a required library, but it is identified as
a temporary situation
- The directory information that used to be in README is now in HACKING
- What remained in README was sectioned up and modified slightly
- The participation and quickstart sections have been moved from
INSTALL (and USING) into README
- USING has been eliminated
- The "Theory and documentation" section in INSTALL has been moved to
HACKING, since it seemed to belong there
- Added a LastChangedDate keyword to README and HACKING
Here is the patch once again, both in the message and included as an
attachment.
Log:
Reworked some of the top level documents for better consistency in the
information they contain. Also removed extraneous trailing spaces.
* INSTALL
Moved the usage information in this file to README, put the theory in
HACKING, and improved the documentation on the build requirements.
* README
Moved the description of the directory structure to HACKING and added
in the usage material from INSTALL. Added LastChangedDate keyword to
top.
* HACKING
Moved material from README and INSTALL into here. Added LastChangedDate
keyword to top.
Index: ./INSTALL
===================================================================
--- ./INSTALL
+++ ./.svn/tmp/INSTALL.63400.00001.tmp Tue Jan 29 23:11:00 2002
@@ -1,10 +1,11 @@
+
======================================
- INSTALLING AND USING SUBVERSION
- A Guide for Newcomers
+ INSTALLING SUBVERSION
+ A Quick Guide
======================================
$LastChangedDate$
-
+
********************************************************************
*** ***
*** Note: this is PRE-ALPHA code. Don't use it on real data, ***
@@ -14,44 +15,173 @@
*** ***
********************************************************************
-I. THEORY AND DOCUMENTATION
+I. BUILD REQUIREMENTS
+
+ Subversion depends on a number of third party tools and libraries.
+ If you are bootstrapping from a tarball or an RPM then you will
+ already have everything you require to get a Subversion client. So
+ long as you don't plan to build a new client from the latest source
+ or to build a Subversion server, you can go directly to section
+ II.A.
+
+ Otherwise, you need to read the following so that you can determine
+ what other tools and libraries will be required so that Subversion
+ can be built with the set of features you want.
+
+ The './configure' script will tell you if you are missing the
+ correct version of any of the required libraries or tools, so if
+ you are in a real hurry to get building, you can skip straight to
+ section II. If you want to gather the pieces you will need before
+ starting out, however, you should read the following.
+
+ Note: Because previous builds of Subversion may have installed older
+ versions of these libraries, you may want to run some of the cleanup
+ commands described in section II.B before installing the following.
+
+ 1. Apache Portable Runtime
+
+ Whenever you want to build any part of Subversion, you need the
+ Apache Portable Runtime (APR) library. At the time of this writing,
+ there were no official release versions of APR available.
+
+ If you want Subversion to build the APR library from source code
+ as part of the Subversion build process, you can put the APR source
+ code into the "./apr" directory. The Subversion tarball has a copy
+ of the APR library source code stored in its own "./apr" directory
+ which you could copy or link to. To be safe, however, you should
+ check out the latest version from the Apache CVS repository, since
+ the latest Subversion may well rely on the latest changes to APR.
+
+ You can get the latest version of APR with the following two
+ commands. If you run them from the directory where you've checked
+ out Subversion, then the APR source code will be in "./apr",
+ where Subversion wants it:
+
+ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
+ (password 'anoncvs')
+
+ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr
+
+ If you already have the APR library compiled and do not wish to
+ regenerate it from source code, then Subversion needs to be
+ able to find it.
+
+ There are a couple of options for Subversion to find where the
+ APR library is. By default, it will use your operating system's
+ standard mechanism for discovering libaries (LD_LIBRARY_PATH,
+ /etc/ld.so.conf, etc). This can cause problems if another version
+ has been previously installed.
+
+ If you want to specify the location of the APR library, you can
+ use the "--with-apr=" option of "./configure". If the library and
+ include files don't share a common parent, you can specify them
+ separately using the "--with-apr-libs=" and "--with-apr-includes="
+ options to "./configure".
- A. DESIGN
+ For example, if you wanted to use the APR libraries you had built
+ with the Apache HTTP 2.0 server, you could run:
- 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.
+ ./configure --with-apr=/usr/local/apache2 ...
-
- 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.
+ 2. autoconf 2.50 or newer
-
- C. USER MANUAL
+ This is required only if you plan to build from the latest source
+ (See section II.B). Generally only developers would be doing this,
+ but at this stage in Subversion's development chances are you'll
+ want to do this as well.
- 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.
-
+ 3. libtool 1.4 or newer
-II. PARTICIPATING
+ This is required only if you plan to build from the latest source
+ (See section II.B), which you probably want to do. See above.
- 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.
+ 4. bison or yacc
- Read the FAQ: http://subversion.tigris.org/project_faq.html
+ This is required only if you plan to build from the latest source
+ (See section II.B), which you probably want to do. See above.
+ The reason one of these programs is required is that it will
+ generate the code which parses complex date formats, so that
+ Subversion can work with dates like "yesterday" and "last month"
+ and "four hours ago". Note that most modern Unices come with one
+ or the other of these programs, and only one is required.
-III. INSTALLATION
+ 5. Neon library 0.18.2
+
+ The Neon library allows a Subversion client to interact with remote
+ repositories over the Internet. Although in theory you could have
+ the client interact only with local repositories, currently the
+ build system requires Neon to be present. Hopefully, this will be
+ fixed in the future.
+
+ The Neon library source code can be installed in "./neon" if you
+ want Subversion to build it. The source code is included with the
+ latest Subversion tarball, and it can also be obtained from:
+
+ http://www.webdav.org/neon/neon-0.18.2.tar.gz
+
+ Unpack the archive using tar/gunzip and rename the resulting
+ directory from "./neon-0.18.2/" to "./neon/".
+
+ Without source code, a previously compiled library can be picked up
+ from the standard locations. If you want to specify a nonstandard
+ location, you need to use the LDFLAGS environmental variable when
+ you run "./configure". You may also have to specify where the
+ neon-config script (which identifies various features of the Neon
+ library) is kept by giving the "--with-neon=" option to
+ "./configure". Note that the script should be kept in a "bin"
+ subdirectory beneath whereever "--with-neon" is pointed.
+
+
+ 6. Berkeley DB 4.0.14
+
+ 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.
+
+
+ 7. Apache Web Server 2.0 or newer
+
+ The Apache HTTP server is required if you wish to offer your
+ Subversion repository over the Internet. Building Subversion, the
+ Apache server, and the modules that Apache needs to communicate
+ with Subversion are complicated enough that there is a whole
+ section at the end of this document that describes how it is
+ done. See section III for details.
+
+
+ 8. Python 2.0
+
+ If you want to run "make check" or build from the latest source
+ as described in section II.B, install Python 2.0 or higher on
+ your system. The majority of the test suite is written in
+ Python, as is part of Subversion's build system. Get it from
+ http://www.python.org/.
+
+
+
+II. INSTALLATION OF SUBVERSION
A. BOOTSTRAPPING FROM A TARBALL OR RPM
@@ -59,7 +189,7 @@
to check it out of a Subversion repository, and therefore you
first need a Subversion client.
-
+
1. BOOSTRAPPING FROM TARBALL
Download the most recent distribution tarball from:
@@ -85,7 +215,7 @@
A svn/HACKING
...
-
+
2. BOOTSTRAPPING FROM RPM
If you are using Linux (or any OS that can use RPM) then another
@@ -122,7 +252,7 @@
just checked out, see the packages/rpm/README file for a
one-line build procedure.
-
+
B. BUILDING THE LATEST SOURCE
You can discard the directory created by the tarball; you're
@@ -143,14 +273,14 @@
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.)
+ told where to get them from. (See the 'Build Requirements' in
+ section I.)
After all components are in place, follow the usual procedure:
$ ./configure --enable-maintainer-mode --disable-shared
$ make
- $ make check (optional)
+ $ make check (optional)
# make install
The flags to `configure' are highly recommended for developers,
@@ -183,190 +313,23 @@
$ 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.8.0
- compiled Jan 26 2002, 16:43:58
-
- Copyright (C) 2000-2002 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 (DeltaV) 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
+III. BUILDING A SUBVERSION SERVER
A. SETUP APACHE
-
+
(Following the BOOTSTRAPPING FROM RPM procedures above will install and
build the latest Subversion server for Linux RedHat 7.1, 7.2, and PPC
Linux systems *IF* the apache-devel-2.0.31 or greater package is already
installed when the SUBVERSION RPM is built.)
-
+
1. OBTAINING AND INSTALLING APACHE 2.0
-
+
Checkout the "httpd-2.0" cvs module from apache.org. If you have
questions about the Apache 2.0 build, please consult the HTTPD
- install documentation: http://httpd.apache.org/docs-2.0/install.html
- Place this module wherever you wish; it's an independent project.
+ install documentation: http://httpd.apache.org/docs-2.0/install.html
+ Place this module wherever you wish; it's an independent project.
$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
(password 'anoncvs')
@@ -404,19 +367,19 @@
line. Make sure this is the same db as the one Subversion uses.
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.
+ see section I.6.
All instructions below assume you configured Apache to install
under /usr/local/apache2/; substitute appropriately if you
chose some other location.
Compile and install apache:
-
+
$ make depend && make && make install
-
+
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
@@ -442,9 +405,9 @@
/usr/local/lib/. libmod_dav_svn.so should be installed in
/usr/local/apache2/modules/.
-
+
2. CONFIGURING APACHE FOR SUBVERSION
-
+
Add this to the *bottom* of /usr/local/apache2/conf/httpd.conf:
<Location /svn/repos>
@@ -456,7 +419,7 @@
you want limited access, read or write, you add these lines to
the Location block:
- AuthType Basic
+ AuthType Basic
AuthName "Subversion repository"
AuthUserFile /my/svn/user/passwd/file
@@ -487,9 +450,9 @@
These are only a few simple examples. For a complete tutorial
on Apache access contol, please consider taking a look at the
- tutorials found under the "Security" on the following page:
+ tutorials found under the "Security" on the following page:
http://httpd.apache.org/docs-2.0/misc/tutorials.html
-
+
In order for 'svn cp' to work (which is actually implemented as a
DAV COPY command), mod_dav needs to be able to be able to determine
the hostname of the server. A standard way of doing this is to use
@@ -505,14 +468,14 @@
NOTE: If you are unfamiliar with an Apache directive, or not exactly
sure about what it does, don't hesitate to look it up in the
documentation: http://httpd.apache.org/docs-2.0/mod/directives.html.
-
+
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.
-
+
3. RUNNING AND TESTING
-
+
Fire up apache 2.0:
$ /usr/local/apache2/bin/apachectl stop
@@ -533,3 +496,4 @@
error logfile, /usr/local/apache2/logs/error_log. For more
information about tracing problems, see "Debugging the server"
in the HACKING file.
+
Index: ./README
===================================================================
--- ./README
+++ ./README Tue Jan 29 22:51:13 2002
@@ -1,59 +1,175 @@
+
Subversion, a version control system.
=====================================
-This code is still under development. For an overview, visit
+$LastChangedDate$
+
+I. A FEW POINTERS
+
+ This code is still under development. For an overview, visit
+
+ http://subversion.tigris.org/
+
+ Once you have a Subversion client you can get the latest version
+ of the code with the command:
+
+ svn co http://svn.collab.net/repos/svn/trunk -d subversion
+
+
+
+II. DOCUMENTATION
+
+ If you like what you see, then run "make ps" inside the doc/ directory
+ and read any PostScript files that result.
+
+ See COPYING for copyright information.
+ See HACKING for development information.
+ See INSTALL for installation information.
+
+
+
+III. PARTICIPATING IN THE SUBVERSION COMMUNITY
+
+ First, 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
+
+
+
+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.8.0
+ compiled Jan 26 2002, 16:43:58
+
+ Copyright (C) 2000-2002 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 (DeltaV) 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 II at the end of the INSTALL 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
- http://subversion.tigris.org/
-If you like what you see, then run "make ps" inside the doc/ directory
-and read any PostScript files that result.
-See COPYING for copyright information.
-See HACKING for development information.
-See INSTALL for installation information.
-
-A rough guide to the source tree:
-
- doc/
- User and Developer documentation.
- www/
- Subversion web pages (live content at http://subversion.tigris.org/).
- tools/
- Stuff that works with Subversion, but that Subversion doesn't depend on.
- packages/
- Stuff to help packaging systems, like rpm and dpkg.
- subversion/
- Source code to subversion itself (as opposed to external libraries).
- subversion/include/
- Public header files for users of subversion libraries.
- subversion/libsvn_fs/
- The versioning "filesystem" API.
- subversion/libsvn_repos/
- Repository functionality built around the `libsvn_fs' core.
- subversion/libsvn_delta/
- Common code for tree deltas, text deltas, and property deltas.
- subversion/libsvn_wc/
- Common code for working copies.
- subversion/libsvn_ra/
- Common code for repository access.
- subversion/libsvn_client/
- Common code for client operations.
- subversion/clients/cmdline/
- The command line client.
- subversion/tests/
- Automated test suite.
- expat-lite/
- Expat library from James Clark. There is a private copy in the
- Subversion repository because we have some local changes to
- it. See expat-lite/CHANGES.svn and expat-lite/CHANGES for
- information on those changes.
- apr/
- Apache Portable Runtime library.
- *Note*: This is not in the same repository as Subversion. Read
- autogen.sh for instructions on how to get it if you don't
- already have it.
- neon/
- Neon library from Joe Orton.
- *Note*: This is not in the same repository as Subversion. Read
- autogen.sh for instructions on how to get it if you don't
- already have it.
Index: ./HACKING
===================================================================
--- ./HACKING
+++ ./HACKING Tue Jan 29 22:53:55 2002
@@ -7,11 +7,14 @@
HACKER'S GUIDE TO SUBVERSION
============================
+$LastChangedDate$
TABLE OF CONTENTS
* Participating in the community
+ * Theory and documentation
* What to read
+ * Directory layout
* Coding style
* Document everything
* Using page breaks
@@ -68,6 +71,39 @@
+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.
+
+
+ D. SYSTEM NOTES
+
+ A lot of the design ideas for particular aspects of the system
+ have been documented in individual files in the notes directory.
+
+
+
What to read
============
@@ -103,12 +139,62 @@
in APR (look in apr/include/):
* memory pools: apr_pools.h
-
+
* filesystem access: apr_file_io.h
* hashes and arrays: apr_hash.h, apr_tables.h
+
+Directory layout
+================
+
+A rough guide to the source tree:
+
+ doc/
+ User and Developer documentation.
+ www/
+ Subversion web pages (live content at http://subversion.tigris.org/).
+ tools/
+ Stuff that works with Subversion, but that Subversion doesn't depend on.
+ packages/
+ Stuff to help packaging systems, like rpm and dpkg.
+ subversion/
+ Source code to subversion itself (as opposed to external libraries).
+ subversion/include/
+ Public header files for users of subversion libraries.
+ subversion/libsvn_fs/
+ The versioning "filesystem" API.
+ subversion/libsvn_repos/
+ Repository functionality built around the `libsvn_fs' core.
+ subversion/libsvn_delta/
+ Common code for tree deltas, text deltas, and property deltas.
+ subversion/libsvn_wc/
+ Common code for working copies.
+ subversion/libsvn_ra/
+ Common code for repository access.
+ subversion/libsvn_client/
+ Common code for client operations.
+ subversion/clients/cmdline/
+ The command line client.
+ subversion/tests/
+ Automated test suite.
+ expat-lite/
+ Expat library from James Clark. There is a private copy in the
+ Subversion repository because we have some local changes to
+ it. See expat-lite/CHANGES.svn and expat-lite/CHANGES for
+ information on those changes.
+ apr/
+ Apache Portable Runtime library.
+ *Note*: This is not in the same repository as Subversion. Read
+ INSTALL for instructions on how to get it if you don't
+ already have it.
+ neon/
+ Neon library from Joe Orton.
+ *Note*: This is not in the same repository as Subversion. Read
+ INSTALL for instructions on how to get it if you don't
+ already have it.
+
Coding Style
@@ -223,7 +309,7 @@
* Put this comment at the bottom of new source files to make Emacs
automatically load svn-dev.el:
- /*
+ /*
* local variables:
* eval: (load-file "../svn-dev.el")
* end:
@@ -368,7 +454,7 @@
"_fast". A better entry would be:
* twirl.c (twirling_baton_fast, twirling_baton_slow): removed these
- obsolete structures.
+ obsolete structures.
(handle_parser_warning): pass data directly to callees, instead of
storing in twirling_baton_*.
@@ -406,7 +492,7 @@
it right:
(consume_count): If `count' is unreasonable, return 0 and don't
- advance input pointer.
+ advance input pointer.
And then, in `consume_count' in `cplus-dem.c':
@@ -538,124 +624,124 @@
To: dev@subversion.tigris.org
Date: Thu, 24 May 2001 07:20:55 -0700
Message-ID: <20010524072055.F5402@lyra.org>
-
+
On Thu, May 24, 2001 at 01:40:17PM -0000, gstein@tigris.org wrote:
- > User: gstein
+ > User: gstein
> Date: 01/05/24 06:40:17
- >
+ >
> Modified: ac-helpers .cvsignore svn-apache.m4
> Added: . Makefile.in
> Log:
> Switch over to the new non-recursive build system.
>...
-
+
Okay... this is it. We're now on the build system.
-
+
"It works on my machine."
-
+
I suspect there may be some tweaks to make on differents OSs. I'd be
interested to hear if Ben can really build with normal BSD make. It
should be possible.
-
+
The code supports building, installation, checking, and
dependencies. It does *NOT* yet deal with the doc/ subdirectory. That
is next; I figured this could be rolled out and get the kinks worked
out while I do the doc/ stuff. Oh, it doesn't build Neon or APR yet
either. I also saw a problem where libsvn_fs wasn't getting built
before linking one of the test proggies (see below).
-
+
Basic operation: same as before.
-
+
$ ./autogen.sh
$ ./configure OPTIONS
$ make
$ make check
$ make install
-
+
There are some "make check" scripts that need to be fixed up. That'll
happen RSN. Some of them create their own log, rather than spewing to
stdout (where the top-level make will place the output into
[TOP]/tests.log).
-
+
The old Makefile.am files are still around, but I'll be tossing those
along with a bunch of tweaks to all the .cvsignore files. There are a
few other cleanups, too. But that can happen as a step two.
-
+
[ $ cvs rm -f `find . -name Makefile.rm`
-
+
See the mistake in that line? I didn't when I typed it. The find
returned nothing, so cvs rm -f proceeded to delete my entire
tree. And the -f made sure to delete all my source files, too. Good
fugging thing that I had my mods in some Emacs buffers, or I'd be
bitching.
-
+
I am *so* glad that Ben coded SVN to *not* delete locally modified
files *and* that we have an "undel" command. I had to go and tweak a
bazillion Entries files to undo the delete...
]
-
+
The top-level make has a number of shortcuts in it (well, actually in
build-outputs.mk):
-
+
$ make subversion/libsvn_fs/libsvn_fs.la
-
+
or
-
+
$ make libsvn_fs
-
+
The two are the same. So... when your test proggie fails to link
because libsvn_fs isn't around, just run "make libsvn_fs" to build it
immediately, then go back to the regular "make".
-
+
Note that the system still conditionally builds the FS stuff based
on whether DB (See 'Building on Unix' below) is available, and
mod_dav_svn if Apache is available.
-
+
Handy hint: if you don't like dependencies, then you can do:
-
+
$ ./autogen.sh -s
-
+
That will skip the dependency generation that goes into
build-outputs.mk. It makes the script run quite a bit faster (48 secs
vs 2 secs on my poor little Pentium 120).
-
+
Note that if you change build.conf, you can simply run:
-
+
$ ./gen-make.py build.conf
-
+
to regen build-outputs.mk. You don't have to go back through the whole
autogen.sh / configure process.
-
+
You should also note that autogen.sh and configure run much faster now
that we don't have the automake crap. Oh, and our makefiles never
re-run configure on you out of the blue (gawd, I hated when automake
did that to me).
-
+
Obviously, there are going to be some tweaky things going on. I also
think that the "shadow" builds or whatever they're called (different
source and build dirs) are totally broken. Something tweaky will have
to happen there. But, thankfully, we only have one Makefile to deal
with.
-
+
Note that I arrange things so that we have one generated file
(build-outputs.mk), and one autoconf-generated file (Makefile from
.in). I also tried to shove as much logic/rules into
Makefile.in. Keeping build-outputs.mk devoid of rules (thus, implying
gen-make.py devoid of rules in its output generation) manes that
tweaking rules in Makefile.in is much more approachable to people.
-
+
I think that is about it. Send problems to the dev@ list and/or feel
free to dig in and fix them yourself. My next steps are mostly
cleanup. After that, I'm going to toss out our use of libtool and rely
on APR's libtool setup (no need for us to replicate what APR already
did).
-
+
Cheers,
-g
-
- --
+
+ --
Greg Stein, http://www.lyra.org/
-
+
And here is some advice for those changing or testing the
configuration/build system:
@@ -670,14 +756,14 @@
*before* you try building with your changes. If you don't do this,
your changes may appear to work fine, when in fact they would fail if
run on a truly pristine system.
-
+
This script demonstrates what I mean by "clean out". This is
`/usr/local/cleanup.sh' on my system. It cleans out the Subversion
libs (and the installed httpd-2.0 libs, since I'm often reinstalling
that too):
-
+
#!/bin/sh
-
+
# Take care of libs
cd /usr/local/lib
rm -f APRVARS
@@ -685,20 +771,20 @@
rm -f libexpat*
rm -f libneon*
rm -f libsvn*
-
+
# Take care of headers
cd /usr/local/include
rm -f apr*
rm -f svn*
rm -f neon/*
-
+
# Take care of headers
cd /usr/local/apache2/lib
rm -f *
-
+
When someone reports a configuration bug and you're trying to
reproduce it, run this first. :-)
-
+
The voice of experience,
-Karl
@@ -743,13 +829,13 @@
option, you have to make sure that your linker knows where the
Berkeley DB libs are:
-kfogel says:
+kfogel says:
After you install Berkeley, say in /usr/local/BerkeleyDB.3.3, you
may need to modify /etc/ld.so.conf or /etc/rc.conf (those seem to
be Linux and FreeBSD, respectively; Your Mileage May Vary), and run
`ldconfig' or whatever your system wants.
-
+
The problem is that configure tries to build, link, and run a small
program against Berkeley DB. If the system loader doesn't yet know
how to do that, configure will claim it can't find Berkeley DB.
@@ -793,7 +879,7 @@
You may want to remote mount the working copy on multiple machines,
and build for different machines from the same working copy.
-
+
You may want to build multiple configurations from the same working
copy.
@@ -888,7 +974,7 @@
your distribution. Unpack it on a clean machine, make sure it
works, and upload it to
- http://subversion.tigris.org/servlets/ProjectDownloadList
+ http://subversion.tigris.org/servlets/ProjectDownloadList
If you're making a new distribution in a hurry because the
previous one is known to have problems, it's fine to upload
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Oct 21 14:37:01 2006