<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<manualpage metafile="win_compiling.xml.meta">

<parentdocument href="./">Platform Specific Notes</parentdocument>

<title>Compiling Apache for Microsoft Windows</title>

<summary>

<p>There are many important points before you begin compiling

Apache. See <a href="windows.html">Using Apache with Microsoft

Windows</a> before you begin.</p>

</summary>

<section id="requirements">

<title>Requirements</title>

<p>Compiling Apache requires the following environment to be

properly installed:</p>

<ul>

<li>

<p>Disk Space</p>

<p>Make sure you have at least 200 MB of free disk space

available. After installation Apache requires approximately

80 MB of disk space, plus space for log and cache files,

which can grow rapidly. The actual disk space requirements

will vary considerably based on your chosen configuration and

any third-party modules or libraries, especially when OpenSSL

is also built. Because many files are text and very easily

compressed, NTFS filesystem compression cuts these requirements

in half.</p>

</li>

<li>

<p>Appropriate Patches</p>

<p>The httpd binary is built with the help of several patches to

third party packages, which ensure the released code is buildable

and debuggable. These patches are available and distributed from <a

href="http://www.apache.org/dist/httpd/binaries/win32/patches_applied/"

>http://www.apache.org/dist/httpd/binaries/win32/patches_applied/</a>

and are recommended to be applied to obtain identical results as the

"official" ASF distributed binaries.</p>

</li>

<li>

<p>Microsoft Visual C++ 6.0 (Visual Studio 97) or later.</p>

<p>Apache can be built using the command line tools, or from

within the Visual Studio IDE Workbench. The command line

build requires the environment to reflect the <code>PATH</code>,

<code>INCLUDE</code>, <code>LIB</code> and other variables

that can be configured with the <code>vcvars32.bat</code> script.</p>

<note>You may want the Visual Studio Processor Pack for your older

version of Visual Studio, or a full (not Express) version of newer

Visual Studio editions, for the ml.exe assembler. This will allow

you to build OpenSSL, if desired, using the more efficient assembly

code implementation.</note>

<note>Only the Microsoft compiler tool chain is actively supported by

the active httpd contributors. Although the project regularly accepts

patches to ensure MinGW and other alternative builds work and improve

upon them, they are not actively maintained and are often broken in

the course of normal development.</note>

</li>

<li>

<p>Updated Microsoft Windows Platform SDK, February 2003 or later.</p>

<p>An appropriate Windows Platform SDK is included by default in the

full (not express/lite) versions of Visual C++ 7.1 (Visual Studio 2002)

and later, these users can ignore these steps unless explicitly choosing

a newer or different version of the Platform SDK.</p>

<p>To use Visual C++ 6.0 or 7.0 (Studio 2000 .NET), the Platform SDK

environment must be prepared using the <code>setenv.bat</code>

script (installed by the Platform SDK) before starting the command

line build or launching the msdev/devenv GUI environment. Installing

the Platform SDK for Visual Studio Express versions (2003 and later)

should adjust the default environment appropriately.</p>

<example>

"c:\Program Files\Microsoft Visual Studio\VC98\Bin\VCVARS32"<br />

"c:\Program Files\Platform SDK\setenv.bat"

</example>

</li>

<li>

<p>Perl and awk</p>

<p>Several steps recommended here require a perl interpreter during

the build preparation process, but it is otherwise not required.</p>

<p>To install Apache within the build system, several files are

modified using the <code>awk.exe</code> utility. awk was chosen since

it is a very small download (compared with Perl or WSH/VB) and

accomplishes the task of modifying configuration files upon

installation. Brian Kernighan's

<a href="http://www.cs.princeton.edu/~bwk/btl.mirror/"

>http://www.cs.princeton.edu/~bwk/btl.mirror/</a>

site has a compiled native Win32 binary,

<a href="http://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe"

>http://www.cs.princeton.edu/~bwk/btl.mirror/awk95.exe</a> which

you must save with the name <code>awk.exe</code> (rather than

<code>awk95.exe</code>).</p>

<note>If awk.exe is not found, Makefile.win's install target

will not perform substitutions in the installed .conf files.

You must manually modify the installed .conf files to allow

the server to start. Search and replace all "@token@" tags

as appropriate.</note>

<note>The Visual Studio IDE will only find <code>awk.exe</code>

from the PATH, or executable path specified in the menu option

Tools -&gt; Options -&gt; (Projects -&gt;) Directories. Ensure

awk.exe is in your system path.</note>

<note>Also note that if you are using Cygwin tools

(<a href="http://www.cygwin.com/">http://www.cygwin.com/</a>)

the awk utility is named <code>gawk.exe</code> and that the file

<code>awk.exe</code> is really a symlink to the <code>gawk.exe</code>

file. The Windows command shell does not recognize symlinks, and

because of this building InstallBin will fail. A workaround is

to delete <code>awk.exe</code> from the cygwin installation and

copy <code>gawk.exe</code> to <code>awk.exe</code>. Also note the

cygwin/mingw ports of gawk 3.0.x were buggy, please upgrade to 3.1.x

before attempting to use any gawk port.</note>

</li>

<li>

<p>[Optional] zlib library (for <module>mod_deflate</module>)</p>

<p>Zlib must be installed into a <code>srclib</code> subdirectory named

<code>zlib</code>. This must be built in-place. Zlib can be obtained

from <a href="http://www.zlib.net/">http://www.zlib.net/</a> -- the

<module>mod_deflate</module> is confirmed to work correctly with

version 1.2.3.</p>

<example>

nmake -f win32\Makefile.msc<br />

nmake -f win32\Makefile.msc test

</example>

</li>

<li>

<p>[Optional] OpenSSL libraries (for <module>mod_ssl</module>

and <code>ab.exe</code> with ssl support)</p>

<note>The OpenSSL library is cryptographic software. The country

in which you currently reside may have restrictions on the import,

possession, use, and/or re-export to another country, of encryption

software. BEFORE using any encryption software, please check your

country's laws, regulations and policies concerning the import,

possession, or use, and re-export of encryption software, to see

if this is permitted. See

<a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>

for more information.</note>

<p>Configuring and building OpenSSL requires perl to be installed.</p>

<p>OpenSSL must be installed into a <code>srclib</code> subdirectory

named <code>openssl</code>, obtained from

<a href="http://www.openssl.org/source/"

>http://www.openssl.org/source/</a>, in order to compile

<module>mod_ssl</module> or the <code>abs.exe</code> project, which

is ab.c with SSL support enabled. To prepare OpenSSL to be linked

to Apache mod_ssl or abs.exe, and disable patent encumbered features

in OpenSSL, you might use the following build commands:</p>

<example>

perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32

-Ipath/to/srclib/zlib -Lpath/to/srclib/zlib<br />

ms\do_masm.bat<br />

nmake -f ms\ntdll.mak

</example>

<note>It is not advisable to use zlib-dynamic, as that transfers

the cost of deflating SSL streams to the first request which must

load the zlib dll. Note the suggested patch enables the -L flag to

work with windows builds, corrects the name of zdll.lib and ensures

.pdb files are generated for troubleshooting. If the assembler is

not installed, you would add no-asm above and use ms\do_ms.bat

instead of the ms\do_masm.bat script.</note>

</li>

<li>

<p>[Optional] Database libraries (for <module>mod_dbd</module>

and <module>mod_authn_dbm</module>)</p>

<p>The apr-util library exposes dbm (keyed database) and dbd (query

oriented database) client functionality to the httpd server and its

modules, such as authentication and authorization. The sdbm dbm and

odbc dbd providers are compiled unconditionally.</p>

<p>The dbd support includes the Oracle instantclient package, MySQL,

PostgreSQL and sqlite. To build these all, for example, set up the

LIB to include the library path, INCLUDE to include the headers path,

and PATH to include the dll bin path of all four SDK's, and set the

DBD_LIST environment variable to inform the build which client driver

SDKs are installed correctly, e.g.;</p>

<example>

set DBD_LIST=sqlite3 pgsql oracle mysql

</example>

<p>Similarly, the dbm support can be extended with DBM_LIST to

build a Berkeley DB provider (db) and/or gdbm provider, by similarly

configuring LIB, INCLUDE and PATH first to ensure the client library

libs and headers are available.</p>

<example>

set DBM_LIST=db gdbm

</example>

<note>Depending on the choice of database distributions, it may be

necessary to change the actual link target name (e.g. gdbm.lib vs.

libgdb.lib) that are listed in the corresponding .dsp/.mak files

within the directories srclib\apr-util\dbd or ...\dbm.</note>

<p>See the README-win32.txt file for more hints on obtaining the

various database driver SDKs.</p>

</li>

</ul>

</section>

<section id="commandbuild">

<title>Command-Line Build</title>

<p><code>Makefile.win</code> is the top level Apache makefile.

To compile Apache on Windows, simply use one of the following commands

to build the <code>release</code> or <code>debug</code> flavor:</p>

<example>

nmake /f Makefile.win _apacher<br /><br />

nmake /f Makefile.win _apached

</example>

<p>Either command will compile Apache. The latter will disable

optimization of the resulting files, making it easier to single

step the code to find bugs and track down problems.</p>

<p>You can add your apr-util dbd and dbm provider choices with the

additional make (environment) variables DBD_LIST and DBM_LIST,

see the comments about [Optional] Database libraries, above.

Review the initial comments in Makefile.win for additional options

that can be provided when invoking the build.</p>

</section>

<section id="workspacebuild">

<title>Developer Studio Workspace IDE Build</title>

<p>Apache can also be compiled using VC++'s Visual Studio

development environment. To simplify this process, a

Visual Studio workspace, <code>Apache.dsw</code>, is provided.

This workspace exposes the entire list of working <code>.dsp</code>

projects that are required for the complete Apache binary release.

It includes dependencies between the projects to assure that they

are built in the appropriate order.</p>

<p>Open the <code>Apache.dsw</code> workspace, and select

<code>InstallBin</code> (<code>Release</code> or <code>Debug</code> build,

as desired) as the Active Project. <code>InstallBin</code> causes all

related project to be built, and then invokes <code>Makefile.win</code> to

move the compiled executables and dlls. You may personalize the

<code>INSTDIR=</code> choice by changing <code>InstallBin</code>'s Settings,

General tab, Build command line entry. <code>INSTDIR</code> defaults to the

<code>/Apache2</code> directory. If you only want a test compile (without

installing) you may build the <code>BuildBin</code> project instead.</p>

<p>The <code>.dsp</code> project files are distributed in Visual Studio 6.0

(98) format. Visual C++ 5.0 (97) will recognize them. Visual Studio

2002 (.NET) and later users must convert <code>Apache.dsw</code> plus

the <code>.dsp</code> files into an <code>Apache.sln</code> plus

<code>.msproj</code> files. Be sure you reconvert the <code>.msproj</code>

file again if its source <code>.dsp</code> file changes! This is really

trivial, just open <code>Apache.dsw</code> in the VC++ 7.0 IDE once again

and reconvert.</p>

<note>There is a flaw in the .vcproj conversion of .dsp files. devenv.exe

will mis-parse the /D flag for RC flags containing long quoted /D'efines

which contain spaces. The command:

<example>

perl srclib\apr\build\cvtdsp.pl -2005

</example>

will convert the /D flags for RC flags to use an alternate, parseable

syntax; unfortunately this syntax isn't supported by Visual Studio 97

or its exported .mak files. These /D flags are used to pass the long

description of the mod_apachemodule.so files to the shared .rc resource

version-identifier build.</note>

<p>Visual Studio 2002 (.NET) and later users should also use the Build

menu, Configuration Manager dialog to uncheck both the <code>Debug</code>

and <code>Release</code> Solution modules <code>abs</code>,

<module>mod_deflate</module> and <module>mod_ssl</module> components, as

well as every component starting with <code>apr_db*</code>. These modules

are built by invoking <code>nmake</code>, or the IDE directly with the

<code>BinBuild</code> target, which builds those modules conditionally

if the <code>srclib</code> directories <code>openssl</code> and/or

<code>zlib</code> exist, and based on the setting of <code>DBD_LIST</code>

and <code>DBM_LIST</code> environment variables.</p>

</section>

<section id="workspacebuild">

<title>Exporting command-line .mak files</title>

<p>Exported <code>.mak</code> files pose a greater hassle, but they are

required for Visual C++ 5.0 users to build <module>mod_ssl</module>,

abs (<program>ab</program> with SSL support) and/or

<module>mod_deflate</module>. The .mak files also support a broader

range of C++ tool chain distributions, such as Visual Studio Express.</p>

<p>You must first build all projects in order to create all dynamic

auto-generated targets, so that dependencies can be parsed correctly.

Build the entire project from within the Visual Studio 6.0 (98) IDE,

using the <code>BuildAll</code> target, then use the Project Menu Export

for all makefiles (checking on "with dependencies".) Run the following

command to correct absolute paths into relative paths so they will build

anywhere:</p>

<example>

perl srclib\apr\build\fixwin32mak.pl

</example>

<p>You must type this command from the <em>top level</em>

directory of the httpd source tree. Every

<code>.mak</code> and <code>.dep</code> project file within

the current directory and below will be corrected, and the

timestamps adjusted to reflect the <code>.dsp</code>.</p>

<p>Always review the generated <code>.mak</code> and <code>.dep</code>

files for Platform SDK or other local, machine specific file paths.

The <code>DevStudio\Common\MSDev98\bin\</code> (VC6) directory contains

a <code>sysincl.dat</code> file, which lists all exceptions. Update

this file (including both forward and backslashed paths, such as both

<code>sys/time.h</code> and <code>sys\time.h</code>) to ignore such

newer dependencies. Including local-install paths in a distributed

<code>.mak</code> file will cause the build to fail completely.</p>

<p>If you contribute back a patch that revises project files, we

must commit project files in Visual Studio 6.0 format. Changes

should be simple, with minimal compilation and linkage flags that

can be recognized by all Visual Studio environments.</p>

</section>

<section id="installation">

<title>Installation</title>

<p>Once Apache has been compiled, it needs to be installed in

its server root directory. The default is the

<code>\Apache2</code> directory, of the same drive.</p>

<p>To build and install all the files into the desired folder

<em>dir</em> automatically, use one of the following

<code>nmake</code> commands:</p>

<example>

nmake /f Makefile.win installr INSTDIR=<em>dir</em><br />

nmake /f Makefile.win installd INSTDIR=<em>dir</em>

</example>

<p>The <em>dir</em> argument to <code>INSTDIR</code> provides

the installation directory; it can be omitted if Apache is

to be installed into <code>\Apache22</code> (of the current

drive).</p>

</section>

<section id="projectcomponents-warn">

<title>Warning about building Apache from the development tree</title>

<note>Note only the <code>.dsp</code> files are maintained between <code>release</code>

builds. The <code>.mak</code> files are NOT regenerated, due to the tremendous

waste of reviewer's time. Therefore, you cannot rely on the <code>NMAKE</code>

commands above to build revised <code>.dsp</code> project files unless you

then export all <code>.mak</code> files yourself from the project. This is

unnecessary if you build from within the Microsoft

Developer Studio environment.</note>

</section>

</manualpage>