1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="win_compiling.xml.meta">
24 <parentdocument href="./">Platform Specific Notes</parentdocument>
26 <title>Compiling Apache for Microsoft Windows</title>
30 <p>There are many important points before you begin compiling
31 Apache. See <a href="windows.html">Using Apache with Microsoft
32 Windows</a> before you begin.</p>
36 <section id="requirements">
38 <title>Requirements</title>
40 <p>Compiling Apache requires the following environment to be
41 properly installed:</p>
46 <p>Make sure you have at least 180 MB of free disk space
47 available. After installation Apache requires approximately
48 60 MB of disk space, plus space for log and cache files,
49 which can grow rapidly. The actual disk space requirements
50 will vary considerably based on your chosen configuration and
51 any third-party modules or libraries, especially when OpenSSL
52 is also built. Because many files are text and very easily
53 compressed, NTFS filesystem compression cuts these requirements
58 <p>Microsoft Visual C++ (Microsoft Visual Studio) 6.0 or higher.</p>
60 <p>Apache can be built using the command line tools, or from
61 within the Visual Studio IDE Workbench. The command line
62 build requires the environment to reflect the <code>PATH</code>,
63 <code>INCLUDE</code>, <code>LIB</code> and other variables
64 that can be configured with the <code>vcvars32.bat</code> file:</p>
67 "c:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32"
72 <p>The Windows Platform SDK for Visual C 6.0 (97) or 7.0 (.NET)</p>
74 <p>Apache's APR and APR-util builds require an updated Microsoft
75 Windows Platform SDK, from Feb 2003 or later, included in the
76 Visual C++ 7.1 (Studio 2003) and later. For command line builds with
77 Visual C++ 6.0 or 7.0, the Platform SDK environment is prepared by
78 the <code>setenv.bat</code> file:</p>
80 "c:\Program Files\Platform SDK\setenv.bat"
83 <p>The Platform SDK files distributed with Visual C++ 6.0 and
84 Visual Studio .NET (2000) are no longer sufficient and cause many
85 compilation warnings and linkage errors. Users of Visual C++ 8.0
86 (Studio 2003) and later versions (of the full product, not the
87 'Visual Studio Express' flavor) may skip this requirement.</p>
89 <p>If using the GUI, either start msdev or devenv with the /setenv
90 flag (after invoking setenv.bat), or ensure the paths are correct
91 under the Tools -> Options -> (Projects ->) Directories
92 menu option. The Platform SDK installer will generally help you
97 <p>The awk utility (awk, gawk or similar).</p>
98 <p>To install Apache within the build system, several files are
99 modified using the <code>awk.exe</code> utility. awk was chosen since
100 it is a very small download (compared with Perl or WSH/VB) and
101 accomplishes the task of modifying configuration files upon
102 installation. Brian Kernighan's
103 <a href="http://cm.bell-labs.com/cm/cs/who/bwk/"
104 >http://cm.bell-labs.com/cm/cs/who/bwk/</a>
105 site has a compiled native Win32 binary,
106 <a href="http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe"
107 >http://cm.bell-labs.com/cm/cs/who/bwk/awk95.exe</a> which
108 you must save with the name <code>awk.exe</code> rather than
109 <code>awk95.exe</code>.</p>
111 <note>If awk.exe is not found, Makefile.win's install target
112 will not perform substitutions in the installed .conf files.
113 The installed .conf files must then be modified by hand for
114 this situation.</note>
116 <p>Note that Developer Studio IDE will only find
117 <code>awk.exe</code> from the Executable path specified in the menu
118 option Tools -> Options -> (Projects ->) Directories.
119 Add the path for <code>awk.exe</code> to this list, and your
120 system <code>PATH</code> environment variable, as needed.</p>
122 <note>Also note that if you are using Cygwin tools
123 (<a href="http://www.cygwin.com/">http://www.cygwin.com/</a>)
124 the awk utility is named <code>gawk.exe</code> and that the file
125 <code>awk.exe</code> is really a symlink to the <code>gawk.exe</code>
126 file. The Windows command shell does not recognize symlinks, and
127 because of this building InstallBin will fail. A workaround is
128 to delete <code>awk.exe</code> from the cygwin installation and
129 copy <code>gawk.exe</code> to <code>awk.exe</code>. Also note the
130 cygwin/mingw ports of gawk 3.0.x were buggy, please upgrade to 3.1.x
131 before attempting to use any gawk port.</note>
135 <p>[Optional] zlib library (for <module>mod_deflate</module>)</p>
136 <p>Zlib must be installed into a <code>srclib</code> subdirectory named
137 <code>zlib</code>. This must be built in-place. Zlib can be obtained
138 from <a href="http://www.zlib.net/">http://www.zlib.net/</a> -- the
139 <module>mod_deflate</module> is confirmed to work correctly with
143 nmake -f win32\Makefile.msc<br />
144 nmake -f win32\Makefile.msc test
149 <p>[Optional] OpenSSL libraries (for <module>mod_ssl</module>
150 and <code>ab.exe</code> with ssl support)</p>
151 <p><strong>Caution: there are significant restrictions and
152 prohibitions on the use and distribution of strong cryptography
153 and patented intellectual property throughout the world.</strong>
154 OpenSSL includes strong cryptography controlled by both export
155 regulations and domestic law, as well as intellectual property
156 protected by patent, in the United States and elsewhere. Neither
157 the Apache Software Foundation nor the OpenSSL project can provide
158 legal advise regarding possession, use, or distribution of the code
159 provided by the OpenSSL project. <strong>Consult your own legal
160 counsel, you are responsible for your own actions.</strong></p>
162 <p>OpenSSL must be installed into a <code>srclib</code> subdirectory
163 named <code>openssl</code>, obtained from
164 <a href="http://www.openssl.org/source/"
165 >http://www.openssl.org/source/</a>, in order to compile
166 <module>mod_ssl</module> or the abs project (<code>ab.exe</code>
167 enabled with SSL support.) To prepare OpenSSL for both
168 <code>release</code> and <code>debug</code> builds of Apache, and
169 disable the patent protected features in OpenSSL, you might use
170 the following build commands:</p>
173 perl Configure no-mdc2 no-rc5 no-idea enable-zlib VC-WIN32 -Ipath/to/srclib/zlib<br />
175 nmake -f ms\ntdll.mak
178 <p>Note: It is not advisable to use zlib-dynamic, as that could
179 pose a thread race condition. If building zlib on win32, be sure
180 to adjust the resulting ms\ntdll.mak file to link to the full
181 path of srclib\zlib\zdll.lib rather than zlib1.lib (that error in
182 configuration of OpenSSL through 0.9.8d and earlier reflects older
183 zlib 1.1 versions.)</p>
190 <section id="commandbuild">
192 <title>Command-Line Build</title>
194 <p>First, unpack the Apache distribution into an appropriate
195 directory. Open a command-line prompt and <code>cd</code> to that
198 <p>The master Apache makefile instructions are contained in the
199 <code>Makefile.win</code> file. To compile Apache on Windows
200 NT, simply use one of the following commands to compiled the
201 <code>release</code> or <code>debug</code> build, respectively:</p>
204 nmake /f Makefile.win _apacher
206 nmake /f Makefile.win _apached
209 <p>Either command will compile Apache. The latter will disable
210 optimization of the resulting files, making it easier to single
211 step the code to find bugs and track down problems.</p>
215 <section id="workspacebuild">
217 <title>Developer Studio Workspace IDE Build</title>
219 <p>Apache can also be compiled using VC++'s Visual Studio
220 development environment. To simplify this process, a
221 Visual Studio workspace, <code>Apache.dsw</code>, is provided.
222 This workspace exposes the entire list of working <code>.dsp</code>
223 projects that are required for the complete Apache binary release.
224 It includes dependencies between the projects to assure that they
225 are built in the appropriate order.</p>
227 <p>Open the <code>Apache.dsw</code> workspace, and select
228 <code>InstallBin</code> (<code>Release</code> or <code>Debug</code> build,
229 as desired) as the Active Project. <code>InstallBin</code> causes all
230 related project to be built, and then invokes <code>Makefile.win</code> to
231 move the compiled executables and dlls. You may personalize the
232 <code>INSTDIR=</code> choice by changing <code>InstallBin</code>'s Settings,
233 General tab, Build command line entry. <code>INSTDIR</code> defaults to the
234 <code>/Apache2</code> directory. If you only want a test compile (without
235 installing) you may build the <code>BuildBin</code> project instead.</p>
237 <p>The <code>.dsp</code> project files are distributed in Visual
238 C++ 6.0 format. Visual C++ 5.0 (97) will recognize them. Visual C++
239 7.0 (.net) must convert <code>Apache.dsw</code> plus the <code>.dsp</code>
240 files into an <code>Apache.sln</code> plus <code>.msproj</code> files,
241 be sure you reconvert the <code>.msproj</code> file if any of the source
242 <code>.dsp</code> files change! This is really trivial, just open
243 <code>Apache.dsw</code> in the VC++ 7.0 IDE once again.</p>
245 <note>There is a flaw in the .vcproj conversion of .dsp through
246 Visual Studio 2005 SP1; devenv.exe will mis-parse the /D flag for RC
247 flags containing long quoted /D'efines containing spaces. The command:
249 perl srclib\apr\build\cvtdsp.pl -2005
251 will convert the /D flags for RC flags to use an alternate, parseable
252 syntax; unfortunately this syntax isn't supported by Visual Studio 97
253 or it's exported .mak files. These /D flags are used to pass the long
254 description of the mod_apachemodule.so files to their .rc resource
255 version-identifier compilations, and replace the use of awk for generating
256 .rc files formerly used for Apache 2.0.</note>
258 <p>Visual C++ 7.0 (.net) users should also use the Build
259 menu, Configuration Manager dialog to uncheck both the <code>Debug</code>
260 and <code>Release</code> Solution modules abs, <module>mod_ssl</module>
261 and <module>mod_deflate</module>.
262 These modules are built by invoking <code>nmake</code> or the IDE directly
263 with the <code>BinBuild</code> target to build those modules conditionally
264 if the <code>srclib</code> directories <code>openssl</code> and/or
265 <code>zlib</code> exist.</p>
267 <p>Exported <code>.mak</code> files pose a greater hassle, but they are
268 required for Visual C++ 5.0 users to build <module>mod_ssl</module>,
269 abs (<program>ab</program> with SSL support) and/or
270 <module>mod_deflate</module>. VC++ 7.0 (Visual Studio .NET) users
271 also benefit, <code>nmake</code> builds were faster than
272 <code>binenv</code> builds until the parallel compilation features
273 introduced in Visual Studio 2005. Build the entire project from within
274 the VC++ 5.0 or 6.0 IDE, preferably with mod_deflate, mod_ssl and abs,
275 then use the Project Menu Export for all makefiles (preferably, with
276 dependencies.) You must build the projects first in order to create
277 all dynamic auto-generated targets, so that dependencies can be parsed
278 correctly. Run the following command to fix the paths so they will build
282 perl srclib\apr\build\fixwin32mak.pl
285 <p>You must type this command from the <em>top level</em>
286 directory of the httpd source tree. Every
287 <code>.mak</code> and <code>.dep</code> project file within
288 the current directory and below will be corrected, and the
289 timestamps adjusted to reflect the <code>.dsp</code>.</p>
291 <p>If you contribute back a patch that revises project files, we
292 must commit project files in Visual Studio 6.0 format. Changes
293 should be simple, with minimal compilation and linkage flags that
294 will be recognized by all VC++ 5.0 through 7.0 environments.</p>
298 <section id="projectcomponents">
300 <title>Project Components</title>
302 <p>The <code>Apache.dsw</code> workspace and <code>makefile.win</code>
303 <code>nmake</code> script both build the <code>.dsp</code> projects
304 of the Apache server in the following sequence:</p>
307 <li><code>srclib\apr\apr.dsp</code></li>
309 <li><code>srclib\apr\libapr.dsp</code></li>
311 <li><code>srclib\apr-util\uri\gen_uri_delims.dsp</code></li>
313 <li><code>srclib\apr-util\xml\expat\lib\xml.dsp</code></li>
315 <li><code>srclib\apr-util\aprutil.dsp</code></li>
317 <li><code>srclib\apr-util\libaprutil.dsp</code></li>
319 <li><code>srclib\pcre\dftables.dsp</code></li>
321 <li><code>srclib\pcre\pcre.dsp</code></li>
323 <li><code>srclib\pcre\pcreposix.dsp</code></li>
325 <li><code>server\gen_test_char.dsp</code></li>
327 <li><code>libhttpd.dsp</code></li>
329 <li><code>Apache.dsp</code></li>
332 <p>In addition, the <code>modules\</code> subdirectory tree contains
333 project files for the majority of the modules.</p>
335 <p>The <code>support\</code> directory contains project files for
336 additional programs that are not part of the Apache runtime,
337 but are used by the administrator to test Apache and maintain
338 password and log files. Windows-specific support projects are
339 broken out in the <code>support\win32\</code> directory.</p>
342 <li><code>support\ab.dsp</code></li>
344 <li><code>support\htdigest.dsp</code></li>
346 <li><code>support\htpasswd.dsp</code></li>
348 <li><code>support\logresolve.dsp</code></li>
350 <li><code>support\rotatelogs.dsp</code></li>
352 <li><code>support\win32\ApacheMonitor.dsp</code></li>
354 <li><code>support\win32\wintty.dsp</code></li>
357 <p>Once Apache has been compiled, it needs to be installed in
358 its server root directory. The default is the
359 <code>\Apache2</code> directory, of the same drive.</p>
361 <p>To build and install all the files into the desired folder
362 <em>dir</em> automatically, use one of the following
363 <code>nmake</code> commands:</p>
366 nmake /f Makefile.win installr INSTDIR=<em>dir</em>
368 nmake /f Makefile.win installd INSTDIR=<em>dir</em>
371 <p>The <em>dir</em> argument to <code>INSTDIR</code> gives
372 the installation directory; it can be omitted if Apache is
373 to be installed into <code>\Apache2</code>.</p>
375 <p>This will install the following:</p>
378 <li><code><em>dir</em>\bin\Apache.exe</code> - Apache
381 <li><code><em>dir</em>\bin\ApacheMonitor.exe</code> - Service
382 monitor taskbar icon utility</li>
384 <li><code><em>dir</em>\bin\htdigest.exe</code> - Digest auth
385 password file utility</li>
387 <li><code><em>dir</em>\bin\htdbm.exe</code> - SDBM auth
388 database password file utility</li>
390 <li><code><em>dir</em>\bin\htpasswd.exe</code> - Basic auth
391 password file utility</li>
393 <li><code><em>dir</em>\bin\logresolve.exe</code> - Log file
394 dns name lookup utility</li>
396 <li><code><em>dir</em>\bin\rotatelogs.exe</code> - Log file
399 <li><code><em>dir</em>\bin\wintty.exe</code> - Console window
402 <li><code><em>dir</em>\bin\libapr.dll</code> - Apache
403 Portable Runtime shared library</li>
405 <li><code><em>dir</em>\bin\libaprutil.dll</code> - Apache
406 Utility Runtime shared library</li>
408 <li><code><em>dir</em>\bin\libhttpd.dll</code> - Apache Core
411 <li><code><em>dir</em>\modules\mod_*.so</code> - Loadable
414 <li><code><em>dir</em>\conf</code> - Configuration
417 <li><code><em>dir</em>\logs</code> - Empty logging
420 <li><code><em>dir</em>\include</code> - C language header
423 <li><code><em>dir</em>\lib</code> - Link library files</li>
426 <section id="projectcomponents-warn">
428 <title>Warning about building Apache from the development tree</title>
430 <note>Note only the <code>.dsp</code> files are maintained between <code>release</code>
431 builds. The <code>.mak</code> files are NOT regenerated, due to the tremendous
432 waste of reviewer's time. Therefore, you cannot rely on the <code>NMAKE</code>
433 commands above to build revised <code>.dsp</code> project files unless you
434 then export all <code>.mak</code> files yourself from the project. This is
435 unnecessary if you build from within the Microsoft
436 Developer Studio environment.</note>
438 <note>Also note it is very worthwhile to build the <code>BuildBin</code>
439 target project (or the command line <code>_apacher</code> or
440 <code>_apached</code> target) prior to exporting the make files.
441 Many files are autogenerated in the build process. Only a full
442 build provides all of the dependent files required to build proper
443 dependency trees for correct build behavior.</note>
445 <p>In order to create distribution <code>.mak</code> files, always
446 review the generated <code>.mak</code> (or <code>.dep</code>)
447 dependencies for Platform SDK or other garbage, machine specific
448 includes. The <code>DevStudio\SharedIDE\bin\</code> (VC5) or
449 <code>DevStudio\Common\MSDev98\bin\</code> (VC6) directory contains
450 the <code>sysincl.dat</code> file, which must list all exceptions.
451 Update this file (including both forward and backslashed paths, such
452 as both <code>sys/time.h</code> and <code>sys\time.h</code>) to ignore
453 such dependencies. Including local-install paths in a distributed
454 <code>.mak</code> file will cause the build to fail completely. And
455 don't forget to run <code>srclib/apr/build/fixwin32mak.pl</code> in
456 order to fix absolute paths within the <code>.mak</code> files.</p>