contrib/apr/README.cmake

   1 Experimental cmake-based build support for APR 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.
  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 * If using a command-line compiler: compiler and linker and related tools
  37   (Refer to the cmake documentation for more information.)
  38
  39 How to build
  40 ------------
  41
  42 1. cd to a clean directory for building (i.e., don't build in your
  43    source tree)
  44
  45 2. Some cmake backends may want your compile tools in PATH.  (Hint: "Visual
  46    Studio Command Prompt")
  47
  48 3. cmake -G "some backend, like 'NMake Makefiles'"
  49      -DCMAKE_INSTALL_PREFIX=d:/path/to/aprinst
  50      -DAPR-specific-flags
  51      d:/path/to/aprsource
  52
  53    Alternately, use cmake-gui and update settings in the GUI.
  54
  55    APR feature flags:
  56
  57        APR_INSTALL_PRIVATE_H  Install extra .h files which are required when
  58                               building httpd and Subversion but which aren't
  59                               intended for use by applications.
  60                               Default: OFF
  61        APR_HAVE_IPV6          Enable IPv6 support
  62                               Default: ON
  63        APR_BUILD_TESTAPR      Build APR test suite
  64                               Default: OFF
  65        TEST_STATIC_LIBS       Build the test suite to test the APR static
  66                               library instead of the APR dynamic library.
  67                               Default: OFF
  68                               In order to build the test suite against both
  69                               static and dynamic libraries, separate builds
  70                               will be required, one with TEST_STATIC_LIBS
  71                               set to ON.
  72        MIN_WINDOWS_VER        Minimum Windows version supported by this build
  73                               (This controls the setting of _WIN32_WINNT.)
  74                               "Vista" or "Windows7" or a numeric value like
  75                               "0x0601"
  76                               Default: "Vista"
  77                               For desktop/server equivalence or other values,
  78                               refer to
  79                               http://msdn.microsoft.com/en-us/library/windows/
  80                               desktop/aa383745(v=vs.85).aspx
  81        INSTALL_PDB            Install .pdb files if generated.
  82                               Default: ON
  83
  84    CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
  85
  86    CMAKE_BUILD_TYPE
  87
  88        For NMake Makefiles the choices are at least DEBUG, RELEASE,
  89        RELWITHDEBINFO, and MINSIZEREL
  90        Other backends make have other selections.
  91
  92 4. build using chosen backend (e.g., "nmake install")
  93
  94 Known Bugs and Limitations
  95 --------------------------
  96
  97 * If include/apr.h or other generated files have been created in the source
  98   directory by another build system, they will be used unexpectedly and
  99   cause the build to fail.
 100 * Options should be provided for remaining features:
 101   + APR_POOL_DEBUG
 102 * APR-CHANGES.txt, APR-LICENSE.txt, and APR-NOTICE.txt are not installed,
 103   though perhaps that is a job for a higher-level script.
 104
 105 Generally:
 106
 107 * Many APR features have not been tested with this build.
 108 * Developers need to examine the existing Windows build in great detail and see
 109   what is missing from the cmake-based build, whether a feature or some build
 110   nuance.
 111 * Any feedback you can provide on your experiences with this build will be
 112   helpful.