[svnbook commit] r2719 - trunk/src/en/book
cmpilato
noreply at red-bean.com
Tue Feb 27 01:51:20 CST 2007
Author: cmpilato
Date: Tue Feb 27 01:51:19 2007
New Revision: 2719
Modified:
trunk/src/en/book/ch08-embedding-svn.xml
Log:
* src/en/book/ch08-embedding-svn.xml
Commit up changes based on most of Ben's review of Ch 8.
Modified: trunk/src/en/book/ch08-embedding-svn.xml
==============================================================================
--- trunk/src/en/book/ch08-embedding-svn.xml (original)
+++ trunk/src/en/book/ch08-embedding-svn.xml Tue Feb 27 01:51:19 2007
@@ -8,8 +8,8 @@
for any software that wishes to embed or otherwise
programmatically control Subversion. Additionally, Subversion's
API is available not only to other C programs, but also to
- programs written in higher-level languages such as Python or
- Java.</para>
+ programs written in higher-level languages such as Python, Perl,
+ Java, or Ruby.</para>
<para>This chapter is for those who wish to interact with Subversion
through its public API or its various language bindings. If you
@@ -33,100 +33,99 @@
<para>Each of Subversion's core libraries can be said to exist in
one of three main layers—the Repository Layer, the
Repository Access (RA) Layer, or the Client Layer. We will
- examine these layers shortly, but first, see our brief inventory
- of Subversion's libraries in <xref
- linkend="svn.developer.layerlib.tbl-1"/>. For the sake of
- consistency, we will refer to the libraries by their
- extensionless Unix library names (libsvn_fs, libsvn_wc,
- mod_dav_svn, etc.).</para>
-
- <table id="svn.developer.layerlib.tbl-1">
- <title>Brief Inventory of the Subversion Libraries</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Library</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>libsvn_client</entry>
- <entry>Primary interface for client programs</entry>
- </row>
- <row>
- <entry>libsvn_delta</entry>
- <entry>Tree and byte-stream differencing routines</entry>
- </row>
- <row>
- <entry>libsvn_diff</entry>
- <entry>Contextual differencing and merging routines</entry>
- </row>
- <row>
- <entry>libsvn_fs</entry>
- <entry>Filesystem commons and module loader</entry>
- </row>
- <row>
- <entry>libsvn_fs_base</entry>
- <entry>The Berkeley DB filesystem back-end</entry>
- </row>
- <row>
- <entry>libsvn_fs_fs</entry>
- <entry>The native filesystem (FSFS) back-end</entry>
- </row>
- <row>
- <entry>libsvn_ra</entry>
- <entry>Repository Access commons and module loader</entry>
- </row>
- <row>
- <entry>libsvn_ra_dav</entry>
- <entry>The WebDAV Repository Access module</entry>
- </row>
- <row>
- <entry>libsvn_ra_local</entry>
- <entry>The local Repository Access module</entry>
- </row>
- <row>
- <entry>libsvn_ra_serf</entry>
- <entry>Another (experimental) WebDAV Repository Access
- module</entry>
- </row>
- <row>
- <entry>libsvn_ra_svn</entry>
- <entry>The custom protocol Repository Access module</entry>
- </row>
- <row>
- <entry>libsvn_repos</entry>
- <entry>Repository interface</entry>
- </row>
- <row>
- <entry>libsvn_subr</entry>
- <entry>Miscellaneous helpful subroutines</entry>
- </row>
- <row>
- <entry>libsvn_wc</entry>
- <entry>The working copy management library</entry>
- </row>
- <row>
- <entry>mod_authz_svn</entry>
- <entry>Apache authorization module for Subversion
- repositories access via WebDAV</entry>
- </row>
- <row>
- <entry>mod_dav_svn</entry>
- <entry>Apache module for mapping WebDAV operations to
- Subversion ones</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ examine these layers shortly, but first, let's briefly summarize
+ Subversion's various libraries. For the sake of consistency, we
+ will refer to the libraries by their extensionless Unix library
+ names (libsvn_fs, libsvn_wc, mod_dav_svn, etc.).</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>libsvn_client</term>
+ <listitem><para>Primary interface for client
+ programs</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_delta</term>
+ <listitem><para>Tree and byte-stream differencing
+ routines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_diff</term>
+ <listitem><para>Contextual differencing and merging
+ routines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_fs</term>
+ <listitem><para>Filesystem commons and module
+ loader</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_fs_base</term>
+ <listitem><para>The Berkeley DB filesystem
+ back-end</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_fs_fs</term>
+ <listitem><para>The native filesystem (FSFS)
+ back-end</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_ra</term>
+ <listitem><para>Repository Access commons and module
+ loader</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_ra_dav</term>
+ <listitem><para>The WebDAV Repository Access
+ module</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_ra_local</term>
+ <listitem><para>The local Repository Access
+ module</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_ra_serf</term>
+ <listitem><para>Another (experimental) WebDAV Repository
+ Access module</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_ra_svn</term>
+ <listitem><para>The custom protocol Repository Access
+ module</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_repos</term>
+ <listitem><para>Repository interface</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_subr</term>
+ <listitem><para>Miscellaneous helpful
+ subroutines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>libsvn_wc</term>
+ <listitem><para>The working copy management
+ library</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mod_authz_svn</term>
+ <listitem><para>Apache authorization module for Subversion
+ repositories access via WebDAV</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mod_dav_svn</term>
+ <listitem><para>Apache module for mapping WebDAV operations to
+ Subversion ones</para></listitem>
+ </varlistentry>
+ </variablelist>
<para>The fact that the word <quote>miscellaneous</quote> only
- appears once in <xref linkend="svn.developer.layerlib.tbl-1"/> is a good
- sign. The Subversion development team is serious about making
- sure that functionality lives in the right layer and libraries.
- Perhaps the greatest advantage of the modular design is its lack
- of complexity from a developer's point of view. As a developer,
+ appears once in the previous list is a good sign. The
+ Subversion development team is serious about making sure that
+ functionality lives in the right layer and libraries. Perhaps
+ the greatest advantage of the modular design is its lack of
+ complexity from a developer's point of view. As a developer,
you can quickly formulate that kind of <quote>big
picture</quote> that allows you to pinpoint the location of
certain pieces of functionality with relative ease.</para>
@@ -187,12 +186,12 @@
been considerable interest by the development community in
giving future releases of Subversion the ability to use other
back-end database systems, perhaps through a mechanism such as
- Open Database Connectivity (ODBC). In fact, Google did just
- this before launching the Projects service of Google Code,
- announcing in mid-2006 that members of its Open Source team
- had written a new proprietary Subversion filesystem plugin
- which used their Bigtable ultra-scalable database for its
- storage.</para>
+ Open Database Connectivity (ODBC). In fact, Google did
+ something similar to this before launching the Google Code
+ Project Hosting service, announcing in mid-2006 that members
+ of its Open Source team had written a new proprietary
+ Subversion filesystem plugin which used their ultra-scalable
+ Bigtable database for its storage.</para>
<para>The filesystem API exported by libsvn_fs contains the
kinds of functionality you would expect from any other
@@ -394,7 +393,7 @@
<para>If the Subversion Repository Layer is at <quote>the other
end of the line</quote>, the Repository Access (RA) Layer is
- the line itself. Charged with marshalling data between the
+ the line itself. Charged with marshaling data between the
client libraries and the repository, this layer includes the
libsvn_ra module loader library, the RA modules themselves
(which currently includes libsvn_ra_dav, libsvn_ra_local,
@@ -445,7 +444,7 @@
protocol—libsvn_ra_dav speaks HTTP/WebDAV (optionally
using SSL encryption) with an Apache HTTP Server that is
running the mod_dav_svn Subversion server module;
- libsvn_ra_svn speaks a proprietary network protocol with the
+ libsvn_ra_svn speaks a custom network protocol with the
<command>svnserve</command> program; and so on.</para>
<para>And for those who wish to access a Subversion repository
@@ -511,7 +510,11 @@
clunky wrappers around the included command-line
client—they have full access via the libsvn_client API
to same functionality, data, and callback mechanisms that the
- command-line client uses.</para>
+ command-line client uses. In fact, the Subversion source code
+ tree contains a small C program (which can be found at
+ <filename>tools/examples/minimal_client.c</filename> that
+ exemplifies how to wield the Subversion API to create a simple
+ client program</para>
<sidebar>
<title>Binding Directly—A Word About Correctness</title>
@@ -537,6 +540,20 @@
original data is potentially tainted more and more, much
like the result of making a copy of a copy (of a copy …)
of a favorite audio or video cassette.</para>
+
+ <para>But the most compelling argument for binding directly to
+ the APIs instead of wrapping other programs is that the
+ Subversion project makes compatibility promises regarding
+ its APIs. Across minor versions of those APIs (such as
+ between 1.3 and 1.4), no function's prototype will change.
+ In other words, you aren't forced to update your program's
+ source code simply because you've upgraded to a new version
+ of Subversion. Certain functions might be deprecated, but
+ they still work, and this gives you a buffer of time to
+ eventually embrace the newer APIs. These kinds of
+ compatibility promises do not exist for Subversion
+ command-line program output, which is subject to change from
+ release to release.</para>
</sidebar>
@@ -703,6 +720,20 @@
conventions, but they help to clarify the scope of a given
function or datatype.</para>
+ <para>Another good source of information about programming against
+ the Subversion APIs is the project's own hacking guidelines,
+ which can be found at <ulink
+ url="http://subversion.tigris.org/hacking.html" />. This
+ document contains useful information which, while aimed at
+ developers and would-be developers of Subversion itself, is
+ equally applicable to folks developing against Subversion as a
+ set of third-party libraries.
+ <footnote>
+ <para>After all, Subversion uses Subversion's APIs,
+ too.</para>
+ </footnote>
+ </para>
+
<!-- =============================================================== -->
<sect2 id="svn.developer.usingapi.apr">
<title>The Apache Portable Runtime Library</title>
More information about the svnbook-dev
mailing list