contrib/apr/README

   1 Apache Portable Runtime Library (APR)
   2 -------------------------------------
   3
   4    The Apache Portable Runtime Library provides a predictable and
   5    consistent interface to underlying platform-specific
   6    implementations, with an API to which software developers may code
   7    and be assured of predictable if not identical behavior regardless
   8    of the platform on which their software is built, relieving them of
   9    the need to code special-case conditions to work around or take
  10    advantage of platform-specific deficiencies or features.
  11
  12    APR and its companion libraries are implemented entirely in C
  13    and provide a common programming interface across a wide variety
  14    of operating system platforms without sacrificing performance.
  15    Currently supported platforms include:
  16
  17      UNIX variants
  18      Windows
  19      Netware
  20      Mac OS X
  21      OS/2
  22
  23    To give a brief overview, the primary core
  24    subsystems of APR 1.3 include the following:
  25
  26      Atomic operations
  27      Dynamic Shared Object loading
  28      File I/O
  29      Locks (mutexes, condition variables, etc)
  30      Memory management (high performance allocators)
  31      Memory-mapped files
  32      Multicast Sockets
  33      Network I/O
  34      Shared memory
  35      Thread and Process management
  36      Various data structures (tables, hashes, priority queues, etc)
  37
  38    For a more complete list, please refer to the following URLs:
  39
  40      http://apr.apache.org/docs/apr/modules.html
  41
  42    Users of APR 0.9 should be aware that migrating to the APR 1.x
  43    programming interfaces may require some adjustments; APR 1.x is
  44    neither source nor binary compatible with earlier APR 0.9 releases.
  45    Users of APR 1.x can expect consistent interfaces and binary backwards
  46    compatibility throughout the entire APR 1.x release cycle, as defined
  47    in our versioning rules:
  48
  49      http://apr.apache.org/versioning.html
  50
  51    APR is already used extensively by the Apache HTTP Server
  52    version 2 and the Subversion revision control system, to
  53    name but a few.  We list all known projects using APR at
  54    http://apr.apache.org/projects.html -- so please let us know
  55    if you find our libraries useful in your own projects!
  56
  57
  58 Using a Subversion Checkout on Unix
  59 ===================================
  60
  61 If you are building APR from SVN, you need to perform a prerequisite
  62 step.  You must have autoconf, libtool and python installed for this
  63 to work.  The prerequisite is simply;
  64
  65   ./buildconf
  66
  67 If you are building APR from a distribution tarball, buildconf is
  68 already run for you, and you do not need autoconf, libtool or python
  69 installed or to run buildconf unless you have patched APR's buildconf
  70 inputs (such as configure.in, build.conf, virtually any file within
  71 the build/ tree, or you add or remove source files).
  72
  73 Remember when updating from svn that you must rerun ./buildconf again
  74 to effect any changes made to the build schema in your fresh update.
  75
  76
  77 Configuring and Building APR on Unix
  78 ====================================
  79
  80 Simply;
  81
  82    ./configure --prefix=/desired/path/of/apr
  83    make
  84    make test
  85    make install
  86
  87 Configure has additional options, ./configure --help will offer you
  88 those choices.  You may also add CC=compiler CFLAGS="compiler flags"
  89 etc. prior to the ./configure statement (on the same line).  Please
  90 be warned, some flags must be passed as part of the CC command,
  91 itself, in order for autoconf to make the right determinations. Eg.;
  92
  93   CC="gcc -m64" ./configure --prefix=/desired/path/of/apr
  94
  95 will inform APR that you are compiling to a 64 bit CPU, and autoconf
  96 must consider that when setting up all of APR's internal and external
  97 type declarations.
  98
  99 For more verbose output from testall, you may wish to invoke testall
 100 with the flag;
 101
 102    cd test
 103    ./testall -v
 104
 105
 106 Building APR RPM files on Linux
 107 ===============================
 108
 109 Run the following to create SRPMs:
 110
 111 rpmbuild -ts apr-<version>.tar.bz2
 112 rpmbuild -ts apr-util-<version>.tar.bz2
 113
 114 Run the following to create RPMs (or build from the SRPMs):
 115
 116 rpmbuild -tb apr-<version>.tar.bz2
 117 rpmbuild -tb apr-util-<version>.tar.bz2
 118
 119 Resolve dependencies as appropriate.
 120
 121
 122 Configuring and Building APR on Windows
 123 =======================================
 124
 125 Using Visual Studio, you can build and run the test validation of APR.
 126 The Makefile.win make file has a bunch of documentation about it's
 127 options, but a trivial build is simply;
 128
 129   nmake -f Makefile.win
 130   nmake -f Makefile.win PREFIX=c:\desired\path\of\apr install
 131
 132 Note you must manually modify the include\apr.hw file before you
 133 build to change default options, see the #define APR_HAS_... or the
 134 #define APR_HAVE_... statements.  Be careful, many of these aren't
 135 appropriate to be modified.  The most common change is
 136
 137 #define APR_HAVE_IPV6           1
 138
 139 rather than 0 if this build of APR will be used strictly on machines
 140 with the IPv6 adapter support installed.
 141
 142 It's trivial to include the apr.dsp (for a static library) or the
 143 libapr.dsp (for a dynamic library) in your own build project, or you
 144 can load apr.dsw in Visual Studio 2002 (.NET) or later, which will
 145 convert these for you into apr.sln and associated .vcproj files.
 146
 147 When using APR as a dynamic library, nothing special is required,
 148 simply link to libapr.lib.  To use it as a static library, simply
 149 define APR_DECLARE_STATIC before you include any apr header files
 150 in your source, and link to apr.lib instead.
 151
 152
 153 Generating Test Coverage information with gcc
 154 =============================================
 155
 156 If you want to generate test coverage data, use the following steps:
 157
 158   ./buildconf
 159   CFLAGS="-fprofile-arcs -ftest-coverage" ./configure
 160   make
 161   cd test
 162   make
 163   ./testall
 164   cd ..
 165   make gcov
 166
 167