Developing applications against the Subversion library APIs
is fairly straightforward. All of the public header files live
in the subversion/include directory of the
source tree. These headers are copied into your system
locations when you build and install Subversion itself from
source. These headers represent the entirety of the functions
and types meant to be accessible by users of the Subversion
libraries.
The first thing you might notice is that Subversion's
datatypes and functions are namespace protected. Every public
Subversion symbol name begins with svn_,
followed by a short code for the library in which the symbol is
defined (such as wc,
client, fs, etc.),
followed by a single underscore (_) and
then the rest of the symbol name. Semi-public functions (used
among source files of a given library but not by code outside
that library, and found inside the library directories
themselves) differ from this naming scheme in that instead of a
single underscore after the library code, they use a double
underscore (__). Functions that are private
to a given source file have no special prefixing, and are declared
static. Of course, a compiler isn't
interested in these naming conventions, but they help to clarify
the scope of a given function or datatype.
The Apache Portable Runtime Library
Along with Subversion's own datatypes, you will see many
references to datatypes that begin with
apr_—symbols from the Apache
Portable Runtime (APR) library. APR is Apache's portability
library, originally carved out of its server code as an
attempt to separate the OS-specific bits from the
OS-independent portions of the code. The result was a library
that provides a generic API for performing operations that
differ mildly—or wildly—from OS to OS. While the
Apache HTTP Server was obviously the first user of the APR
library, the Subversion developers immediately recognized the
value of using APR as well. This means that there are
practically no OS-specific code portions in Subversion itself.
Also, it means that the Subversion client compiles and runs
anywhere that the server does. Currently this list includes
all flavors of Unix, Win32, BeOS, OS/2, and Mac OS X.
In addition to providing consistent implementations of
system calls that differ across operating systems,
[43]
APR gives Subversion immediate access to many custom
datatypes, such as dynamic arrays and hash tables. Subversion
uses these types extensively throughout the codebase. But
perhaps the most pervasive APR datatype, found in nearly every
Subversion API prototype, is the
apr_pool_t—the APR memory pool.
Subversion uses pools internally for all its memory allocation
needs (unless an external library requires a different memory
management schema for data passed through its API),
[44]
and while a person coding against the Subversion APIs is
not required to do the same, they are required to provide
pools to the API functions that need them. This means that
users of the Subversion API must also link against APR, must
call apr_initialize() to initialize the
APR subsystem, and then must acquire a pool for use with
Subversion API calls. See
the section called “Programming with Memory Pools”
for more information.
[an error occurred while processing this directive]
