1Experimental cmake-based build support for APR on Microsoft Windows
2
3Status
4------
5
6This build support is currently intended only for Microsoft Windows.
7Only Windows NT-based systems can be targeted.  (The traditional 
8Windows build support for APR can target Windows 9x as well.)
9
10This 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
20Important: 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
30Prerequisites
31-------------
32
33The 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
39How to build
40------------
41
421. cd to a clean directory for building (i.e., don't build in your
43   source tree)
44
452. Some cmake backends may want your compile tools in PATH.  (Hint: "Visual
46   Studio Command Prompt")
47
483. 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
924. build using chosen backend (e.g., "nmake install")
93
94Known 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
105Generally:
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.
113