view release on metacpan or  search on metacpan

src/subversion/doc/user/lj_article.txt  view on Meta::CPAN

Subversion's Design
-------------------

Subversion has a modular design; it's implemented as a collection of C
libraries.  Each layer has a well-defined purpose and interface.  In
general, code flow begins at the top of the diagram and flows
"downward" -- each layer provides an interface to the layer above it.

              <<insert diagram here:  svn.tiff>>


Let's take a short tour of these layers, starting at the bottom.


--> The Subversion filesystem.  

The Subversion Filesystem is *not* a kernel-level filesystem that one
would install in an operating system (like the Linux ext2 fs.)
Instead, it refers to the design of Subversion's repository.  The
repository is built on top of a database -- currently Berkeley DB --
and thus is a collection of .db files.  However, a library accesses
these files and exports a C API that simulates a filesystem --
specifically, a "versioned" filesystem.

This means that writing a program to access the repository is like
writing against other filesystem APIs: you can open files and
directories for reading and writing as usual.  The main difference is
that this particular filesystem never loses data when written to; old
versions of files and directories are always saved as historical
artifacts.

Whereas CVS's backend (RCS) stores revision numbers on a per-file
basis, Subversion numbers entire trees.  Each atomic 'commit' to the
repository creates a completely new filesystem tree, and is
individually labeled with a single, global revision number.  Files and
directories which have changed are rewritten (and older versions are
backed up and stored as differences against the latest version), while
unchanged entries are pointed to via a shared-storage mechanism.  This
is how the repository is able to version tree structures, not just
file contents.

Finally, it should be mentioned that using a database like Berkeley DB
immediately provides other nice features that Subversion needs: data
integrity, atomic writes, recoverability, and hot backups.  (See
www.sleepycat.com for more information.)


--> The network layer.

Subversion has the mark of Apache all over it.  At its very core, the
client uses the Apache Portable Runtime (APR) library.  (In fact, this
means that Subversion client should compile and run anywhere Apache
httpd does -- right now, this list includes all flavors of Unix,
Win32, BeOS, OS/2, Mac OS X, and possibly Netware.)

However, Subversion depends on more than just APR -- the Subversion
"server" is Apache httpd itself.

Why was Apache chosen?  Ultimately, the decision was about not
reinventing the wheel.  Apache is a time-tested, open-source server
process that ready for serious use, yet is still extensible.  It can
sustain a high network load.  It runs on many platforms and can
operate through firewalls.  It's able to use a number of different
authentication protocols.  It can do network pipelining and caching.
By using Apache as a server, Subversion gets all these features for
free.  Why start from scratch?

Subversion uses WebDAV as its network protocol.  DAV (Distributed
Authoring and Versioning) is a whole discussion in itself (see
www.webdav.org) -- but in short, it's an extension to HTTP that allows
reads/writes and "versioning" of files over the web.  The Subversion
project is hoping to ride a slowly rising tide of support for this
protocol: all of the latest file-browsers for Win32, MacOS, and GNOME
speak this protocol already.  Interoperability will (hopefully) become
more and more of a bonus over time.

For users who simply wish to access Subversion repositories on local
disk, the client can do this too; no network is required.  The
"Repository Access" layer (RA) is an abstract API implemented by both
the DAV and local-access RA libraries.  This is a specific benefit of
writing a "librarized" version control system; it's a big win over
CVS, which has two very different, difficult-to-maintain codepaths for
local vs. network repository-access.  Feel like writing a new network
protocol for Subversion?  Just write a new library that implements the
RA API!


--> The client libraries.

On the client side, the Subversion "working copy" library maintains
administrative information within special SVN/ subdirectories, similar
in purpose to the CVS/ administrative directories found in CVS working
copies.

A glance inside the typical SVN/ directory turns up a bit more than
usual, however.  The `entries' file contains XML which describes the
current state of the working copy directory (and which basically
serves the purposes of CVS's Entries, Root, and Repository files
combined).  But other items present (and not found in CVS/) include
storage locations for the versioned "properties" (the metadata
mentioned in 'Subversion Features' above) and private caches of
pristine versions of each file.  This latter feature provides the
ability to report local modifications -- and do reversions --
*without* network access.  Authentication data is also stored within
SVN/, rather than in a single .cvspass-like file.

The Subversion "client" library has the broadest responsibility; its
job is to mingle the functionality of the working-copy library with
that of the repository-access library, and then to provide a
highest-level API to any application that wishes to perform general
version control actions.

For example: the C routine `svn_client_checkout()' takes a URL as an
argument.  It passes this URL to the repository-access library and
opens an authenticated session with a particular repository.  It then
asks the repository for a certain tree, and sends this tree into the
working-copy library, which then writes a full working copy to disk
(SVN/ directories and all.)

The client library is designed to be used by any application.  While
the Subversion source code includes a standard command-line client, it