contrib/apr-util/README.cmake

   1 Experimental cmake-based build support for APR-Util on Microsoft Windows
   2
   3 Status
   4 ------
   5
   6 This build support is currently intended only for Microsoft Windows.
   7 Only Windows NT-based systems can be targeted.  (The traditional
   8 Windows build support for APR can target Windows 9x as well.)
   9
  10 This build support is experimental.  Specifically,
  11
  12 * It does not support all features of APR-Util.
  13 * Some components may not be built correctly and/or in a manner
  14   compatible with the previous Windows build support.
  15 * Build interfaces, such as the mechanisms which are used to enable
  16   optional functionality or specify prerequisites, may change from
  17   release to release as feedback is received from users and bugs and
  18   limitations are resolved.
  19
  20 Important: Refer to the "Known Bugs and Limitations" section for further
  21            information.
  22
  23            It is beyond the scope of this document to document or explain
  24            how to utilize the various cmake features, such as different
  25            build backends or provisions for finding support libraries.
  26
  27            Please refer to the cmake documentation for additional information
  28            that applies to building any project with cmake.
  29
  30 Prerequisites
  31 -------------
  32
  33 The following tools must be in PATH:
  34
  35 * cmake, version 2.8 or later
  36   cmake version 3.1.3 or later is required to work with current OpenSSL
  37   releases.  (OpenSSL is an optional prerequisite of APR-Util.)
  38 * If using a command-line compiler: compiler and linker and related tools
  39   (Refer to the cmake documentation for more information.)
  40
  41 The following support libraries are mandatory:
  42
  43 * APR 1.4.x or APR 1.5.x, built with cmake
  44
  45 Optional support libraries allow optional features of APR to be enabled:
  46
  47 * OpenSSL
  48 * many others potentially, though the build support isn't currently
  49   implemented
  50
  51 How to build
  52 ------------
  53
  54 1. cd to a clean directory for building (i.e., don't build in your
  55    source tree)
  56
  57 2. Some cmake backends may want your compile tools in PATH.  (Hint: "Visual
  58    Studio Command Prompt")
  59
  60 3. set CMAKE_LIBRARY_PATH=d:\path\to\prereq1\lib;d:\path\to\prereq2\lib;...
  61
  62 4. set CMAKE_INCLUDE_PATH=d:\path\to\prereq1\include;d:\path\to\prereq2\include;...
  63
  64 5. cmake -G "some backend, like 'NMake Makefiles'"
  65      -DCMAKE_INSTALL_PREFIX=d:/path/to/aprinst
  66      -DAPR-Util-specific-flags
  67      d:/path/to/aprutilsource
  68
  69    If APR 1.x was installed to a different directory than APR-Util,
  70    also pass these additional arguments:
  71
  72      -DAPR_INCLUDE_DIR=d:/path/to/apr1inst/include
  73      -DAPR_LIBRARIES=d:/path/to/apr1inst/lib/libapr-1.lib
  74
  75    Alternately, use cmake-gui and update settings in the GUI.
  76
  77    APR-Util feature flags:
  78
  79        APU_HAVE_CRYPTO        Build crypt support (only the OpenSSL
  80                               implementation is currently supported)
  81                               Default: OFF
  82        APU_HAVE_ODBC          Build ODBC DBD driver
  83                               Default: ON
  84        APR_BUILD_TESTAPR      Build APR-Util test suite
  85                               Default: OFF
  86        TEST_STATIC_LIBS       Build the test suite to test the APR static
  87                               library instead of the APR dynamic library.
  88                               Default: OFF
  89                               In order to build the test suite against both
  90                               static and dynamic libraries, separate builds
  91                               will be required, one with TEST_STATIC_LIBS
  92                               set to ON.
  93        INSTALL_PDB            Install .pdb files if generated.
  94                               Default: ON
  95
  96    CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
  97
  98    CMAKE_BUILD_TYPE
  99
 100        For NMake Makefiles the choices are at least DEBUG, RELEASE,
 101        RELWITHDEBINFO, and MINSIZEREL
 102        Other backends make have other selections.
 103
 104 6. build using chosen backend (e.g., "nmake install")
 105
 106 Known Bugs and Limitations
 107 --------------------------
 108
 109 * If include/apu.h or other generated files have been created in the source
 110   directory by another build system, they will be used unexpectedly and
 111   cause the build to fail.
 112 * Options should be provided for remaining features, along with finding any
 113   necessary libraries
 114   + DBM:
 115     . APU_HAVE_GDBM
 116     . APU_HAVE_NDBM
 117     . APU_HAVE_DB
 118   + DBD:
 119     . APU_HAVE_PGSQL
 120     . APU_HAVE_MYSQL
 121     . APU_HAVE_SQLITE3
 122     . APU_HAVE_SQLITE2
 123     . APU_HAVE_ORACLE
 124   + CRYPTO:
 125     . APU_HAVE_NSS
 126   + XLATE, APU_HAVE_ICONV (no way to consume an apr-iconv build yet)
 127 * Static builds of APR modules are not supported.
 128 * CHANGES/LICENSE/NOTICE is not installed, unlike Makefile.win.
 129   (But unlike Makefile.win we want to call them APR-Util-CHANGES.txt
 130   and so on.)  But perhaps that is a job for a higher-level script.
 131
 132 Generally:
 133
 134 * Many APR-Util features have not been tested with this build.
 135 * Developers need to examine the existing Windows build in great detail and see
 136   what is missing from the cmake-based build, whether a feature or some build
 137   nuance.
 138 * Any feedback you can provide on your experiences with this build will be
 139   helpful.