release to release as feedback is received from users and bugs and
limitations are resolved.
-This can be used with Apache httpd 2.4.x by copying the following files from
-httpd trunk (in Subversion) into the 2.4.x source tree:
-
-* CMakeLists.txt
-* build/cpR_noreplace.pl
-
Important: Refer to the "Known Bugs and Limitations" section for further
information.
The following tools must be in PATH:
* cmake, version 2.8 or later
+ cmake version 3.1.3 or later is required to work with current OpenSSL
+ releases. (OpenSSL is an optional prerequisite of httpd.)
* Perl
* If the WITH_MODULES feature is used: awk
* If using a command-line compiler: compiler and linker and related tools
The following support libraries are mandatory:
* APR, built with cmake
- + Either APR 2.0-dev (trunk) or APR 1.4.x and APR-Util 1.5.x.
- + When building APR (but not APR-Util 1.5.x), specify the build option
+ + Either APR 2.0-dev (trunk) or APR 1.5.x and APR-Util 1.5.x.
+ + When building APR (but not APR-Util), specify the build option
APR_INSTALL_PRIVATE_H so that non-standard files required for building
Apache httpd are installed.
+ Additional APR settings affect httpd but are not mandatory, such as
APR_HAVE_IPV6.
-* PCRE
+* PCRE (version 6.7 or higher)
-Additional support libraries allow optional features of httpd to be enabled:
+Certain optional features of APR 2.0-dev (trunk) or APR-Util 1.5.x
+allow some optional features of httpd to be enabled. For example,
+APU_HAVE_CRYPTO is required for mod_session_crypto.
+
+Additional support libraries allow some optional features of httpd to be
+enabled:
* libxml2 (e.g., mod_proxy_html)
-* openssl (e.g., mod_ssl)
-* zlib (e.g., mod_deflate)
+* lua 5.1 (mod_lua)
+* nghttp2 (mod_http2)
+* openssl (mod_ssl and https support for ab)
+* zlib (mod_deflate)
+
+OpenSSL
+-------
+
+If you have a binary install of OpenSSL in a well-known directory (e.g.,
+%HOME%\OpenSSL-Win64) and you wish to build httpd against a different
+install of OpenSSL, the cmake build may unexpectedly select OpenSSL
+libraries in the well-known directory even if the expected include files
+are used. Check the cmake output from your httpd build to confirm that
+the expected OpenSSL libraries and include files are used.
+
+The cmake FindOpenSSL module searches for OpenSSL libraries in a "VC"
+subdirectory of the OpenSSL install with filenames that indicate the build
+type (e.g., "<PREFIX>/lib/VC/ssleay32MD.lib"); defining CMAKE_PREFIX_PATH
+or OPENSSL_ROOT_DIR or even OPENSSL_LIBRARIES does not circumvent finding
+these libraries.
+
+To work around this issue, rename the well-known OpenSSL directory while
+building httpd. Let us know if you find a better solution.
+
+nghttp2
+-------
+
+This is required for mod_http2.
+
+cmake-based build support for nghttp2 for Windows can be found at
+https://github.com/trawick/nghttp2-minimal-cmake. That easily fits into
+a build system that already uses cmake for httpd, apr, and perhaps other
+packages. A dynamic build of nghttp2 using its normal Windows build
+system should also be usable by nghttp2.
How to build
------------
1. cd to a clean directory for building (i.e., don't build in your
source tree)
-2. Make sure Perl is in your PATH. Additionally, some backends may want
- your compile tools in PATH. (Hint: "Visual Studio Command Prompt")
- In the unlikely event that you use -DWITH_MODULES, make sure awk is
- in PATH.
+2. Make sure cmake and Perl are in PATH. Additionally, some backends
+ require compile tools in PATH. (Hint: "Visual Studio Command Prompt")
+ In the unlikely event that you use -DWITH_MODULES, described below, make
+ sure awk is in PATH.
3. cmake -G "some backend, like 'NMake Makefiles'"
-DCMAKE_INSTALL_PREFIX=d:/path/to/httpdinst
- -DPCRE_INCLUDE_DIR=d:/path/to/pcreinst/include
- -DPCRE_LIBRARIES=d:/path/to/pcreinst/lib/pcre[d].lib
- -DAPR_INCLUDE_DIR=d:/path/to/aprinst/include
- -DAPR_LIBRARIES="d:/path/to/aprinst/lib/libapr-1.lib;d:/path/to/aprinst/lib/libaprutil-1.lib"
-DENABLE_foo=A|I|O|a|i
+ -DENABLE_MODULES=A|I|O|a|i
d:/path/to/httpdsource
Alternately, you can use the cmake-gui and update settings in the GUI.
- PCRE_INCLUDE_DIR, PCRE_LIBRARIES, APR_INCLUDE_DIR, APR_LIBRARIES:
+ PCRE_INCLUDE_DIR, PCRE_LIBRARIES, APR_INCLUDE_DIR, APR_LIBRARIES,
+ NGHTTP2_INCLUDE_DIR, NGHTTP2_LIBRARIES:
+
cmake doesn't bundle FindXXX for these packages, so the crucial
- information has to be specified in this manner
+ information has to be specified in this manner if they aren't found
+ in their default location.
+
+ -DPCRE_INCLUDE_DIR=d:/path/to/pcreinst/include
+ -DPCRE_LIBRARIES=d:/path/to/pcreinst/lib/pcre[d].lib
+
+ These will have to be specified only if PCRE is installed to a different
+ directory than httpd, or if debug *and* release builds of PCRE were
+ installed there and you want to control which is used. (Currently the
+ build will use pcred.lib (debug) if it is found in the default location
+ and not overridden with -DPCRE_LIBRARIES.)
+
+ -DAPR_INCLUDE_DIR=d:/path/to/aprinst/include
+ -DAPR_LIBRARIES="d:/path/to/aprinst/lib/libapr-1.lib;d:/path/to/aprinst/lib/libaprutil-1.lib"
+
+ These will have to be specified if APR[-Util] was installed to a
+ different directory than httpd.
When building with APR trunk (future APR 2.x, with integrated APR-Util),
specify just the path to libapr-2.lib:
-DAPR_LIBRARIES=d:/path/to/aprinst/lib/libapr-2.lib
+ APR+APR-Util 1.x vs. APR trunk will be detected automatically if they
+ are installed to the same location as httpd.
+
+ APR-Util 1.x has an optional LDAP library. If APR-Util has LDAP enabled
+ and httpd's mod_ldap and mod_authnz_ldap are being used, include the
+ path to the LDAP library in the APR_LIBRARIES setting. (If APR and
+ APR-Util are found in the default location, the LDAP library will be
+ included if it is present.
+
+ -DNGHTTP2_INCLUDE_DIR=d:/path/to/nghttp2inst/include (which has nghttp2/*.h)
+ -DNGHTTP2_LIBRARIES=d:/path/to/nghttp2inst/lib/nghttp2.lib"
+
+ These will have to be specified if nghttp2 was installed to a different
+ directory than httpd.
+
LIBXML2_ICONV_INCLUDE_DIR, LIBXML2_ICONV_LIBRARIES
- If using a module that requires libxml2 and the build of libxml2 requires
+ If using a module that requires libxml2 *and* the build of libxml2 requires
iconv, set these variables to allow iconv includes and libraries to be
used. For example:
CMAKE_C_FLAGS_RELEASE, _DEBUG, _RELWITHDEBINFO, _MINSIZEREL
CMAKE_BUILD_TYPE
+
For NMake Makefiles the choices are at least DEBUG, RELEASE,
RELWITHDEBINFO, and MINSIZEREL
- Other backends make have other selections.
+ Other backends may have other selections.
ENABLE_foo:
+
Each module has a default setting which can be overridden with one of
the following values:
A build and Activate module
Examples: -DENABLE_ACCESS_COMPAT=O
-DENABLE_PROXY_HTML=i
+ ENABLE_MODULES:
+
+ This changes the *minimum* enablement of all modules to the specified
+ value (one of A, a, I, i, O, as described under ENABLE_foo above).
+
+ The ranking of enablement from lowest to highest is O, i, I, a, A.
+ If a specific module has a higher rank enablement setting, either from
+ a built-in default or from -DENABLE_foo, ENABLE_MODULES won't affect
+ that module. However, if a specific module has a lower-rank enablement
+ setting, presumably from a built-in default, the value of ENABLE_MODULES
+ will be used for that module.
+
+ Explanations for possible values:
+
+ -DENABLE_MODULES=a build and activate all possible modules,
+ ignoring any with missing prereqs
+ (doesn't affect modules with A for ENABLE_foo)
+
+ -DENABLE_MODULES=i build but leave inactive all possible
+ modules, ignoring any with missing
+ prereqs
+ (doesn't affect modules with A, a, or I for
+ ENABLE_foo)
+
+ -DENABLE_MODULES=O no impact, since all modules are either
+ already disabled or have a higher setting
+
+ -DENABLE_MODULES=A build and activate all possible modules,
+ failing the build if any module is missing
+ a prereq
+
+ -DENABLE_MODULES=I similar to -DENABLE_MODULES=A
+ (doesn't affect modules with A or a for
+ ENABLE_foo)
+
WITH_MODULES:
- Comma-separated paths to single file modules to statically link into
+
+ Comma-separated paths to single file modules to statically linked into
the server, like the --with-module=modpath:/path/to/mod_foo.c with
the autoconf-based build. Key differences: The modpath (e.g.,
"generators") isn't provided or used, and the copy of the module
source being built is automatically updated when it changes.
- See also EXTRA_INCLUDE_DIRS.
+ See also EXTRA_COMPILE_FLAGS, EXTRA_INCLUDES, and EXTRA_LIBS.
+
+ EXTRA_COMPILE_FLAGS:
+
+ Space-delimited compile flags to define with the build.
+
+ EXTRA_INCLUDES:
- EXTRA_INCLUDE_DIRS:
List of additional directories to search for .h files. This may
be necessary when including third-party modules in the httpd build
via WITH_MODULES.
- Port and SSLPort: port numbers for substitution into default .conf files.
- (The defaults are 80 and 443.)
+ EXTRA_LIBS:
+
+ List of additional libraries to link with. This may be necessary when
+ including third-party modules in the httpd build via WITH_MODULES.
+
+ Port and SSLPort:
+
+ Port numbers for substitution into default .conf files. (The defaults
+ are 80 and 443.)
+
+ INSTALL_PDB:
+
+ If .pdb files are generated for debugging, install them.
+ Default: ON
+
+ The .pdb files are generally needed for debugging low-level code
+ problems. If they aren't installed, they are still available in the
+ build directory for use by alternate packaging implementations or when
+ debugging on the build machine.
+
+ INSTALL_MANUAL:
+
+ Install the Apache HTTP Server manual.
+ Default: ON
+
+ This could be turned off when developing changes in order to speed up
+ installation time.
-4. build using chosen backend (e.g., "nmake install")
+4. Build using the chosen generator (e.g., "nmake install" for cmake's "NMake
+ Makefiles" generator).
Running the server and support programs
---------------------------------------
* Update PATH to include the bin directories of all necessary support
libraries.
- Depending on where PATH is set, it may not effect starting httpd as
+ Depending on where PATH is set, it may not affect starting httpd as
a service.
* Maintain a script which combines required binaries into a common
Known Bugs and Limitations
--------------------------
-* no support for APR/APU optional features as module prerequisites (e.g.,
- the APU_HAVE_CRYPTO requirement of mod_session_crypto)
-* no logic to find support libraries needed by some modules (LUA, distcache)
-* no support for these modules:
- + mod_ldap, mod_authnz_ldap, mod_socache_dc, mod_lua, mod_serf,
- apreq+mod_apreq, mod_session_crypto
+* no standard script or makefile is provided to tie together the builds
+ of httpd and support libraries in a manner suitable for typical users
+* no logic to find support libraries or otherwise build these modules:
+ + mod_socache_dc (requires distcache), mod_serf (requires serf)
+ additionally, mod_lbmethod_rr and mod_firehose don't compile on Windows
anyway
* buildmark.c isn't necessarily rebuilt when httpd.exe is regenerated
-* ab + HAVE_OPENSSL isn't working at all, even for non-SSL
* ApacheMonitor has a build error and is disabled
* CGI examples aren't installed
+* dbmmanage.pl and wintty aren't built/installed
* module enablement defaults are not in sync with the autoconf-based build
+* no support for static support library builds; unclear if that is a
+ requirement; if so: taking PCRE as an example, we'd need to detect that it
+ is static and then turn on PCRE_STATIC for the libhttpd build
Generally: