| <?xml version="1.0" encoding="UTF-8" ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <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 to consider before you begin compiling |
| Apache HTTP Server (httpd). See <a href="windows.html">Using Apache HTTP |
| Server on Microsoft Windows</a> before you begin.</p> |
| |
| <p>httpd can be built on Windows using a cmake-based build system or with |
| Visual Studio project files maintained by httpd developers. The cmake-based |
| build system directly supports more versions of Visual Studio but currently |
| has considerable functional limitations.</p> |
| |
| </summary> |
| |
| <section id="vstudio"> |
| <title>Building httpd with the included Visual Studio project files</title> |
| |
| <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 -> Options -> (Projects ->) 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="unixsrcbuild"> |
| |
| <title>Building from Unix sources</title> |
| |
| <p>The policy of the Apache HTTP Server project is to only release Unix sources. |
| Windows source packages made available for download have been supplied by |
| volunteers and may not be available for every release. You can still build |
| the server on Windows from the Unix source tarball with just a few additional |
| steps.</p> |
| |
| <ol> |
| <li>Download and unpack the Unix source tarball for the latest version.</li> |
| <li>Download and unpack the Unix source tarball for latest version of |
| APR, AR-Util and APR-Iconv, place these sources in directories httpd-2.x.x\srclib\apr, httpd-2.x.x\srclib\apr-util and httpd-2.x.x\srclib\apr-iconv</li> |
| <li>Open a Command Prompt and CD to the httpd-2.x.x folder</li> |
| <li>Run the line endings conversion utility at the prompt;</li> |
| </ol> |
| |
| <example> |
| perl srclib\apr\build\lineends.pl |
| </example> |
| |
| <p>You can now build the server with the Visual Studio development |
| environment using the IDE. Command-Line builds of the server are not |
| possible from Unix sources unless you export .mak files as explained |
| below. |
| </p> |
| |
| </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> |
| |
| <note><strong>Building with OpenSSL 1.1.0 and up</strong> |
| Due to difference in the build structure of OpenSSL begining with version |
| 1.1.0 you will need to convert the dsp files affected with cvtdsp.pl from |
| APR 1.6 or greater. The command: |
| <example> |
| perl srclib\apr\build\cvtdsp.pl -ossl11 |
| </example> |
| </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="exportingmakfiles"> |
| |
| <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> |
| </section> |
| |
| <section id="cmake"> |
| <title>Building httpd with cmake</title> |
| |
| <p>The primary documentation for this build mechanism is in the |
| <code>README.cmake</code> file in the source distribution. Refer to that file |
| for detailed instructions.</p> |
| |
| <p>Building httpd with cmake requires building APR and APR-util separately. |
| Refer to their <code>README.cmake</code> files for instructions.</p> |
| |
| <p>The primary limitations of the cmake-based build are inherited from the APR-util |
| project, and are listed below because of their impact on httpd:</p> |
| |
| <ul> |
| <li>No cmake build for the APR-iconv subproject is available, and the |
| APR-util cmake build cannot consume an existing APR-iconv build. Thus, |
| <module>mod_charset_lite</module> and possibly some third-party modules |
| cannot be used.</li> |
| <li>The cmake build for the APR-util subproject does not support most of the |
| optional DBM and DBD libraries supported by the included Visual Studio |
| project files. This limits the database backends supported by a number of |
| bundled and third-party modules.</li> |
| </ul> |
| |
| </section> |
| |
| </manualpage> |
| |
