DOCSEARCHbyAlgolia
Submit Docs

Apache Portable Runtime (APR)

repository·trunk·Indexed 19 days ago

https://github.com/apache/apr

A library providing a consistent, predictable C interface to platform-specific implementations for UNIX variants, Windows, Mac OS X, and OS/2. It includes core subsystems for memory management, file I/O, network I/O, and thread/process management. Version 2.0+ integrates utility services such as hashing, UUID, and XML parsing. The project supports CMake-based builds for Windows and standard autoconf workflows for Unix.

Tokens
2K
Snippets
5
Records
12
Agent score
68%

What's inside Apache Portable Runtime

  1. What is the Apache Portable Runtime Library (APR)?

    trunk

    The Apache Portable Runtime Library (APR) provides a consistent, predictable C interface to platform-specific implementations. It allows developers to write code that works across various operating systems without handling platform-specific edge cases or deficiencies.

    Supported Platforms:

    • UNIX variants
    • Windows
    • Mac OS X
    • OS/2

    Core Subsystems (APR 1.3+):

    • Atomic operations
    • Dynamic Shared Object loading
    • File I/O
    • Locks (mutexes, condition variables, etc.)
    • Memory management (high performance allocators)
    • Memory-mapped files
    • Multicast Sockets
    • Network I/O
    • Shared memory
    • Thread and Process management
    • Various data structures (tables, hashes, priority queues, etc.)

    Utility Services (APR 2.0+): APR 2.0 integrates several utilities that were previously in apr-util, including:

    • Hashing and UUID services
    • SQL DBD and flat-database DBM client interfaces
    • Typesafe function Hooks abstraction
    • MemCache interface
    • Date parsing, URI parsing, and XML parsing (expat based)
    • Thread Pools, Queues, and Resource Lists

  2. Build APR from a Subversion (SVN) Checkout on Unix

    trunk

    If you are building APR from an SVN checkout rather than a distribution tarball, you must first run the build configuration script.

    Prerequisites:

    • autoconf
    • libtool
    • python

    Steps:

    1. Run ./buildconf to generate the configuration files.
    2. If you update your SVN checkout, you must rerun ./buildconf to apply any changes made to the build schema.
    ./buildconf

  3. Build APR on Microsoft Windows using CMake

    trunk

    To build APR on Windows, use CMake to generate build files in a clean directory (out-of-source build). Ensure your compiler and linker are in your PATH (e.g., by using the 'Visual Studio Command Prompt').

    Follow these steps:

    1. Create and enter a clean directory for the build.
    2. Run cmake with your preferred generator, installation prefix, and any required feature flags.
    3. Execute the build and installation using your chosen backend (e.g., nmake install).

    Note: Avoid building in the source tree, as existing generated files in the source directory can cause build failures.

    # 1. Create a build directory
mkdir build
cd build

# 2. Configure the project
cmake -G "Ninja" \
     -DCMAKE_INSTALL_PREFIX=d:/path/to/aprinst \
     d:/path/to/aprsource

# 3. Build and install
ninja install

  4. Generate Test Coverage with gcc

    trunk

    To generate test coverage data using gcc, follow this sequence of commands:

    ./buildconf
CFLAGS="--coverage -fprofile-abs-path" LDFLAGS="--coverage" ./configure
make
cd test
make
./testall
cd ..
make gcov

  5. Prerequisites for building APR on Windows

    trunk

    Before building, ensure the following tools are available in your PATH:

    • CMake: Version 3.5 or later.
    • Compiler/Linker: A C compiler and linker (e.g., via Visual Studio) and related build tools.

    Optional support libraries for additional features:

    • Expat
    • Iconv
    • Libxml2
    • SQLite3
    • OpenSSL

  6. Configure and Build APR on Unix

    trunk

    To build APR on a Unix-like system, use the standard ./configure, make, and make install workflow.

    Standard Build Sequence:

    ./configure --prefix=/desired/path/of/apr
make
make test
make install

    Advanced Configuration:

    • Use ./configure --help to see all available options.
    • You can pass compiler flags like CC or CFLAGS directly before the configure command.
    • Important: Some flags must be passed as part of the CC command itself so autoconf can correctly determine internal and external type declarations (e.g., for 64-bit compilation).

    Example (64-bit compilation):

    CC="gcc -m64" ./configure --prefix=/desired/path/of/apr

    Verbose Testing: To see more detailed output during tests, run:

    cd test
./testall -v

  7. Build APR on Windows using CMake

    trunk

    On Windows, APR uses CMake for the build process. You can build using the command line or Visual Studio.

    Command Line Build (using Ninja):

    cmake -B out/build -G Ninja -DCMAKE_INSTALL_PREFIX=out/install
cmake --build out/build
cmake --install out/build

    Visual Studio Build:

    1. Ensure the "C++ CMake tools for Windows" component is installed in Visual Studio.
    2. Use the Open Folder command in Visual Studio to open the APR source directory.
    3. Use the Build command to compile the project.

    For more detailed CMake options, refer to README.cmake in the repository.

  8. Enable Database Providers in APR

    trunk

    APR includes interfaces for several database drivers, but they are not built by default to avoid licensing incompatibilities. To enable support for specific providers, use the --with-{provider} option during configuration.

    Available Providers:

    • MySQL (copy-left licensed)
    • gdbm DBD (copy-left licensed)
    • Berkeley DB DBM
    • Proprietary drivers (e.g., Oracle) must also be explicitly enabled.

    Note: Always review the license requirements of all components when distributing apr-util in combination with database client drivers.

  9. Configure APR feature flags via CMake

    trunk

    When configuring APR with CMake, you can enable or disable specific features using -D flags.

    Important XML Constraint: You must specify exactly one of APU_USE_EXPAT or APU_USE_LIBXML2.

    XML Implementation

    • APU_USE_EXPAT: Use Expat as the underlying XML implementation (Default: ON).
    • APU_USE_LIBXML2: Use libxml2 as the underlying XML implementation (Default: OFF).

    Database Drivers (DBD)

    • APU_HAVE_ODBC: Build ODBC DBD driver (Default: ON).
    • APU_HAVE_SQLITE3: Build SQLite3 DBD driver (Default: OFF).
    • APU_HAVE_PGSQL: Build PostgreSQL DBD driver (Default: OFF).

    Security and Networking

    • APU_HAVE_CRYPTO: Build crypt support using OpenSSL (Default: OFF).
    • APR_HAVE_IPV6: Enable IPv6 support (Default: ON).

    Build and Installation Options

    • APR_INSTALL_PRIVATE_H: Install extra .h files required for building httpd and Subversion (Default: OFF).
    • APR_MODULAR_DSO: Use DSO build of modular components; otherwise, they are statically linked (Default: ON).
    • APR_BUILD_TESTAPR: Build the APR test suite (Default: OFF).
    • APR_POOL_DEBUG: Turn on pools debugging (Default: OFF).
    • INSTALL_PDB: Install .pdb files if generated (Default: ON).

  10. Set CMake build types and flags

    trunk

    You can control the build configuration using CMAKE_BUILD_TYPE and specific compiler flags. For NMake Makefiles, the available choices for CMAKE_BUILD_TYPE are:

    • DEBUG
    • RELEASE
    • RELWITHDEBINFO
    • MINSIZEREL

    Other backends may support different selections. You can also provide specific flags for different configurations using:

    • CMAKE_C_FLAGS_RELEASE
    • CMAKE_C_FLAGS_DEBUG
    • CMAKE_C_FLAGS_RELWITHDEBINFO
    • CMAKE_C_FLAGS_MINSIZEREL

  11. Use ODBC as an alternative to the FreeTDS DBD Driver

    trunk
    The APR DBD Driver for FreeTDS has been removed from the official build due to maintenance issues. For users requiring database connectivity that FreeTDS previously provided, it is recommended to use the ODBC driver as the primary alternative.

  12. Identify APR DLL metadata and versioning

    trunk

    The libapr.rc file defines the Windows resource metadata for the Apache Portable Runtime (APR) DLLs. This metadata is used by the Windows operating system to display version information, file descriptions, and product names in file explorers and system tools.

    Key metadata fields include:

    • FileDescription: Either Apache Portable Runtime Library or Apache Portable Runtime <DLL_NAME> Module depending on whether a specific DLL name is defined.
    • InternalName and OriginalFilename: Derived from APR_DLL_BASENAME, which typically follows the pattern libapr-<MAJOR_VERSION> or <DLL_NAME>-<MAJOR_VERSION>.
    • FileVersion and ProductVersion: Driven by the APR_VERSION_STRING defined in apr_version.h.
    • CompanyName: Apache Software Foundation.
    • ProductName: Apache Portable Runtime Project.