1 Experimental cmake-based build support for Apache httpd on Microsoft Windows
6 This build support is currently intended only for Microsoft Windows.
8 This build support is experimental. Specifically,
10 * It does not support all features of Apache httpd.
11 * Some components may not be built correctly and/or in a manner
12 compatible with the previous Windows build support.
13 * Build interfaces, such as the mechanisms which are used to enable
14 optional functionality or specify prerequisites, may change from
15 release to release as feedback is received from users and bugs and
16 limitations are resolved.
18 Important: Refer to the "Known Bugs and Limitations" section for further
21 It is beyond the scope of this document to document or explain
22 how to utilize the various cmake features, such as different
23 build backends or provisions for finding support libraries.
25 Please refer to the cmake documentation for additional information
26 that applies to building any project with cmake.
31 The following tools must be in PATH:
33 * cmake, version 2.8 or later
35 * If the WITH_MODULES feature is used: awk
36 * If using a command-line compiler: compiler and linker and related tools
37 (Refer to the cmake documentation for more information.)
39 The following support libraries are mandatory:
41 * APR, built with cmake
42 + Either APR 2.0-dev (trunk) or APR 1.5.x and APR-Util 1.5.x.
43 + When building APR (but not APR-Util), specify the build option
44 APR_INSTALL_PRIVATE_H so that non-standard files required for building
45 Apache httpd are installed.
46 + Additional APR settings affect httpd but are not mandatory, such as
50 Certain optional features of APR 2.0-dev (trunk) or APR-Util 1.5.x
51 allow some optional features of httpd to be enabled. For example,
52 APU_HAVE_CRYPTO is required for mod_session_crypto.
54 Additional support libraries allow some optional features of httpd to be
57 * libxml2 (e.g., mod_proxy_html)
59 * openssl (mod_ssl and https support for ab)
65 If you have a binary install of OpenSSL in a well-known directory (e.g.,
66 %HOME%\OpenSSL-Win64) and you wish to build httpd against a different
67 install of OpenSSL, the cmake build may unexpectedly select OpenSSL
68 libraries in the well-known directory even if the expected include files
69 are used. Check the cmake output from your httpd build to confirm that
70 the expected OpenSSL libraries and include files are used.
72 The cmake FindOpenSSL module searches for OpenSSL libraries in a "VC"
73 subdirectory of the OpenSSL install with filenames that indicate the build
74 type (e.g., "<PREFIX>/lib/VC/ssleay32MD.lib"); defining CMAKE_PREFIX_PATH
75 or OPENSSL_ROOT_DIR or even OPENSSL_LIBRARIES does not circumvent finding
78 To work around this issue, rename the well-known OpenSSL directory while
79 building httpd. Let us know if you find a better solution.
84 1. cd to a clean directory for building (i.e., don't build in your
87 2. Make sure cmake and Perl are in PATH. Additionally, some backends
88 require compile tools in PATH. (Hint: "Visual Studio Command Prompt")
89 In the unlikely event that you use -DWITH_MODULES, described below, make
92 3. cmake -G "some backend, like 'NMake Makefiles'"
93 -DCMAKE_INSTALL_PREFIX=d:/path/to/httpdinst
94 -DENABLE_foo=A|I|O|a|i
95 -DENABLE_MODULES=A|I|O|a|i
96 d:/path/to/httpdsource
98 Alternately, you can use the cmake-gui and update settings in the GUI.
100 PCRE_INCLUDE_DIR, PCRE_LIBRARIES, APR_INCLUDE_DIR, APR_LIBRARIES:
102 cmake doesn't bundle FindXXX for these packages, so the crucial
103 information has to be specified in this manner if they aren't found
104 in their default location.
106 -DPCRE_INCLUDE_DIR=d:/path/to/pcreinst/include
107 -DPCRE_LIBRARIES=d:/path/to/pcreinst/lib/pcre[d].lib
109 These will have to be specified only if PCRE is installed to a different
110 directory than httpd, or if debug *and* release builds of PCRE were
111 installed there and you want to control which is used. (Currently the
112 build will use pcred.lib (debug) if it is found in the default location
113 and not overridden with -DPCRE_LIBRARIES.)
115 -DAPR_INCLUDE_DIR=d:/path/to/aprinst/include
116 -DAPR_LIBRARIES="d:/path/to/aprinst/lib/libapr-1.lib;d:/path/to/aprinst/lib/libaprutil-1.lib"
118 These will have to be specified if APR[-Util] was installed to a
119 different directory than httpd.
121 When building with APR trunk (future APR 2.x, with integrated APR-Util),
122 specify just the path to libapr-2.lib:
124 -DAPR_LIBRARIES=d:/path/to/aprinst/lib/libapr-2.lib
126 APR+APR-Util 1.x vs. APR trunk will be detected automatically if they
127 are installed to the same location as httpd.
129 APR-Util 1.x has an optional LDAP library. If APR-Util has LDAP enabled
130 and httpd's mod_ldap and mod_authnz_ldap are being used, include the
131 path to the LDAP library in the APR_LIBRARIES setting. (If APR and
132 APR-Util are found in the default location, the LDAP library will be
133 included if it is present.
135 LIBXML2_ICONV_INCLUDE_DIR, LIBXML2_ICONV_LIBRARIES
137 If using a module that requires libxml2 *and* the build of libxml2 requires
138 iconv, set these variables to allow iconv includes and libraries to be
141 -DLIBXML2_ICONV_INCLUDE_DIR=c:\iconv-1.9.2.win32\include
142 -DLIBXML2_ICONV_LIBRARIES=c:\iconv-1.9.2.win32\lib\iconv.lib
144 CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
147 For NMake Makefiles the choices are at least DEBUG, RELEASE,
148 RELWITHDEBINFO, and MINSIZEREL
149 Other backends may have other selections.
153 Each module has a default setting which can be overridden with one of
154 the following values:
155 A build and Activate module
156 a build and Activate module IFF prereqs are available; if
157 prereqs are unavailable, don't build it
158 I build module but leave it Inactive (commented-out
159 LoadModule directive)
160 i build module but leave it Inactive IFF prereqs are
161 available; if prereqs are unavailable, don't build it
162 O Omit module completely
164 Examples: -DENABLE_ACCESS_COMPAT=O
165 -DENABLE_PROXY_HTML=i
169 This changes the *minimum* enablement of all modules to the specified
170 value (one of A, a, I, i, O, as described under ENABLE_foo above).
172 The ranking of enablement from lowest to highest is O, i, I, a, A.
173 If a specific module has a higher rank enablement setting, either from
174 a built-in default or from -DENABLE_foo, ENABLE_MODULES won't affect
175 that module. However, if a specific module has a lower-rank enablement
176 setting, presumably from a built-in default, the value of ENABLE_MODULES
177 will be used for that module.
179 Explanations for possible values:
181 -DENABLE_MODULES=a build and activate all possible modules,
182 ignoring any with missing prereqs
183 (doesn't affect modules with A for ENABLE_foo)
185 -DENABLE_MODULES=i build but leave inactive all possible
186 modules, ignoring any with missing
188 (doesn't affect modules with A, a, or I for
191 -DENABLE_MODULES=O no impact, since all modules are either
192 already disabled or have a higher setting
194 -DENABLE_MODULES=A build and activate all possible modules,
195 failing the build if any module is missing
198 -DENABLE_MODULES=I similar to -DENABLE_MODULES=A
199 (doesn't affect modules with A or a for
204 Comma-separated paths to single file modules to statically linked into
205 the server, like the --with-module=modpath:/path/to/mod_foo.c with
206 the autoconf-based build. Key differences: The modpath (e.g.,
207 "generators") isn't provided or used, and the copy of the module
208 source being built is automatically updated when it changes.
209 See also EXTRA_COMPILE_FLAGS, EXTRA_INCLUDES, and EXTRA_LIBS.
213 Space-delimited compile flags to define with the build.
217 List of additional directories to search for .h files. This may
218 be necessary when including third-party modules in the httpd build
223 List of additional libraries to link with. This may be necessary when
224 including third-party modules in the httpd build via WITH_MODULES.
228 Port numbers for substitution into default .conf files. (The defaults
233 If .pdb files are generated for debugging, install them.
236 The .pdb files are generally needed for debugging low-level code
237 problems. If they aren't installed, they are still available in the
238 build directory for use by alternate packaging implementations or when
239 debugging on the build machine.
243 Install the Apache HTTP Server manual.
246 This could be turned off when developing changes in order to speed up
249 4. Build using the chosen generator (e.g., "nmake install" for cmake's "NMake
250 Makefiles" generator).
252 Running the server and support programs
253 ---------------------------------------
255 This build system does not copy binaries such as dlls from other projects
256 into the httpd install location. Without taking some precautions, httpd
257 and support programs can fail to start or modules can fail to load because
258 a support library can't be found in PATH or in the directory of the httpd
261 This can be resolved in several different ways:
263 * Install httpd and the various support libraries to a common install
264 prefix so that support libraries and httpd programs are installed in
265 the same bin directory and are found without setting PATH.
267 * Update PATH to include the bin directories of all necessary support
270 Depending on where PATH is set, it may not affect starting httpd as
273 * Maintain a script which combines required binaries into a common
274 location, such as the httpd installion bin directory, and use that
275 script after building or otherwise installing or updating support
278 * AVOID THE USE of any unrepeatable process of copying dll files around
279 from different install locations until something starts working. The
280 result is that when you later update a support library to pick up a
281 security fix, httpd will likely continue to use the old, vulnerable
284 Known Bugs and Limitations
285 --------------------------
287 * no standard script or makefile is provided to tie together the builds
288 of httpd and support libraries in a manner suitable for typical users
289 * no logic to find support libraries or otherwise build these modules:
290 + mod_socache_dc (requires distcache), mod_serf (requires serf)
291 + additionally, mod_lbmethod_rr and mod_firehose don't compile on Windows
293 * buildmark.c isn't necessarily rebuilt when httpd.exe is regenerated
294 * ApacheMonitor has a build error and is disabled
295 * CGI examples aren't installed
296 * dbmmanage.pl and wintty aren't built/installed
297 * module enablement defaults are not in sync with the autoconf-based build
298 * no support for static support library builds; unclear if that is a
299 requirement; if so: taking PCRE as an example, we'd need to detect that it
300 is static and then turn on PCRE_STATIC for the libhttpd build
304 * Many httpd features have not been tested with this build.
305 * Developers need to examine the existing Windows build in great detail and see
306 what is missing from the cmake-based build, whether a feature or some build
308 * Any feedback you can provide on your experiences with this build will be