<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<sect1 xml:id="install.windows.building" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Building from source</title>
 <para>
  This chapter teaches how to compile PHP from sources on windows, using
  Microsoft's tools. To compile PHP with cygwin, please refer to <xref
  linkend="install.unix"/>.
 </para>
 
 <sect2 xml:id="install.windows.building.quick-guide">
  <title>Quick Guide to Building On Windows</title>
  
  <para>
   This step-by-step quick-start guide was written in March of 2008, running
   Windows XP Service Pack 2 with all the latest updates and building PHP 5.2.5
   and PHP 5.3. Experiences using different tools may differ.
  </para>
  
  <orderedlist>
   <listitem>
    <para>
     Download and install:
    </para>
    <itemizedlist>
     <listitem>
      <simpara>
       <link xlink:href="&url.vc2k8ee;">Microsoft
       Visual C++ 2008 Express Edition</link>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <link xlink:href="&url.win32.sdk;">
       Windows SDK for Windows Server 2008 and .NET Framework 3.5</link>
      </simpara>
     </listitem>
    </itemizedlist>
   </listitem>
    
   <listitem>
    <simpara>
     Copy <filename>C:\Program Files\Microsoft SDKs\Windows\v6.1\Include\WinResrc.h</filename>
     to <filename>C:\Program Files\Microsoft SDKs\Windows\v6.1\Include\winres.h</filename>.
    </simpara>
   </listitem>
    
   <listitem>
    <simpara>
     Create the directory <filename>C:\work</filename>.
    </simpara>
   </listitem>
    
   <listitem>
    <simpara>
     Download <link xlink:href="&url.win32.buildtools;">the Windows build
     tools</link> and unzip the contents into <filename>C:\work</filename>.
    </simpara>
   </listitem>
    
   <listitem>
    <simpara>
     Create the directory <filename>C:\usr\local\lib</filename>. Copy the
     <filename>C:\work\win32build\bin\bison.simple</filename> into the new
     directory.
    </simpara>
   </listitem>
    
   <listitem>
    <simpara>
     Download <link xlink:href="&url.win32.dnsresolver;">the Windows DNS
     resolver library</link> and unzip the contents into
     <filename>C:\work</filename>.
    </simpara>
   </listitem>
    
   <listitem>
    <simpara>
     Open <filename>C:\work\bindlib_w32\bindlib.dsw</filename>. If and when
     asked whether to update the project, choose Yes. Choose either Debug or
     Release configuration in the top toolbar, then choose Build =&gt; Build
     Solution.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     Obtain a copy of the PHP source and extract it into the
     <filename>C:\work</filename> directory. At this point, that directory
     should look something like this:
    </simpara>
    <screen>
<![CDATA[
+-C:\work
| +-bindlib_w32
| | +-Debug
| | | +-resolv.lib
| | | +-...
| | +-...
| +-win32build
| | +-bin
| | +-include
| | +-lib
| +-php-5.2.5
| | +-build
| | +-win32
| | +-...]]></screen>
   </listitem>
    
   <listitem>
    <simpara>
     Open a shell using the Visual Studio 2008 Command Prompt shortcut in the
     Start menu.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     Execute the command:
    </simpara>
    <screen>
<![CDATA[
C:\Program Files\Microsoft Visual Studio 9.0\VC> set "PATH=C:\work\win32build\bin;%PATH%"
C:\Program Files\Microsoft Visual Studio 9.0\VC>]]></screen>
   </listitem>
   
   <listitem>
    <simpara>
     Enter the <filename>C:\work\php-5.2.5</filename> directory.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     Run <command>cscript /nologo win32\build\buildconf.js</command>.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     Run <command>cscript /nologo configure.js --disable-all --enable-cli
     --enable-cgi --enable-object-out-dir=.. --disable-ipv6</command>. To
     enable debugging, add <command>--enable-debug</command> to the end.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     Run <command>nmake</command>.
    </simpara>
   </listitem>
   
   <listitem>
    <simpara>
     If all went well, there will now be a working PHP CLI executable at
     <filename>C:\work\Debug_TS\php.exe</filename>, or
     <filename>C:\work\Release_TS\php.exe</filename>.
    </simpara>
   </listitem>

  </orderedlist>
 </sect2>

 <sect2 xml:id="install.windows.building.environment">
  <title>Build Environment</title>
  <para>
   To compile and build PHP you need a Microsoft Development Environment.
   The following environments are supported:
  </para>
  <itemizedlist>
   <listitem>
    <simpara>
     Microsoft Visual C++ 6.0 (official)
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Microsoft Visual C++ .NET
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Microsoft Visual C++ 2005, Windows Platform SDK and .NET Framework SDK (current)
    </simpara>
   </listitem>
  </itemizedlist>
  <para>
   While VC6 (Microsoft Visual C++ 6.0) is used to perform official Windows
   builds, it can no longer be downloaded from Microsoft's website. New users
   seeking to build PHP for free must use Microsoft Visual C++ 2005 Express
   Edition and its auxiliary components.
  </para>
  
  <sect3 xml:id="install.windows.building.environment.express2005">
   <title>Setting up Microsoft Visual C++ 2005 Express</title>
   <note>
    <simpara>
     Combined, these components are very large and will require over one
     gigabyte of disk space.
    </simpara>
   </note>
   <para>
    Setting up Microsoft Visual C++ 2005 Express is rather involved,
    and requires the installation of three separate packages and various
    compatibility changes. Be sure to keep track of the paths in which
    these programs are installed into. Download and install the following
    programs:
   </para>
   <itemizedlist>
    <listitem>
     <simpara>
      <link xlink:href="&url.win32.msvc2005express;">Microsoft Visual C++ 2005 Express</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link xlink:href="&url.win32.platform-sdk;">Microsoft Windows Server 2005 Platform SDK</link>
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <link xlink:href="&url.win32.net2.0-sdk;">.NET Framework 2.0 Software Development Kit</link>
     </simpara>
    </listitem>
   </itemizedlist>
   <para>
    There are a few post-installation steps:
   </para>
   <itemizedlist>
    <listitem>
     <simpara>
      <link xlink:href="&url.win32.express-and-sdk;">MSVC 2005 Express must
      be configured to use Windows Platform SDK</link>. It is not necessary
      to perform step two, as PHP does not use the graphical user interface.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Windows Platform SDK contains a file named <filename>WinResrc.h</filename>
      usually in <filename>Include</filename> folder inside the SDK's installation
      directory. This needs to be copied and renamed to <filename>winres.h</filename>,
      the name PHP uses for the file.
     </simpara>
    </listitem>
   </itemizedlist>
   <para>
    Finally, when using MSVC 2005 Express from the command line, several
    environment variables must be set up. <filename>vsvars32.bat</filename>
    usually found in <filename>C:\Program Files\Microsoft Visual Studio 8\Common7\Tools</filename>
    (search for the file if otherwise) contains these declarations. The
    <varname>PATH</varname>, <varname>INCLUDE</varname> and <varname>LIB</varname>
    environment variables need the corresponding <filename>bin</filename>,
    <filename>include</filename> and <filename>lib</filename> directories
    of the two newly installed SDKs added to them.
   </para>
   <note>
    <simpara>
     The .NET SDK paths may already be present in the <filename>vsvars32.bat</filename>
     file, as this SDK installs itself into the same directory as
     Microsoft Visual C++ 2005 Express.
    </simpara>
   </note>
  </sect3>
 </sect2>
 
 <sect2 xml:id="install.windows.building.libraries">
  <title>Libraries</title>
  <para>
   To extract the downloaded files you will also need a ZIP extraction
   utility. Windows XP and newer already include this functionality built-in.
  </para>
  <para>
   Before you get started, you have to download:
  </para>
  <itemizedlist>
   <listitem>
    <simpara>
     the win32 buildtools from the PHP site at <link
     xlink:href="&url.win32.buildtools;">&url.win32.buildtools;</link>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     the source code for the DNS name resolver used by PHP from <link
     xlink:href="&url.win32.dnsresolver;">&url.win32.dnsresolver;</link>. This is a
     replacement for the <filename>resolv.lib</filename> library included in
     <filename>win32build.zip</filename>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     If you plan to compile PHP as a Apache module you will also need the
     <link xlink:href="&url.apache.source;">Apache sources</link>.
    </simpara>
   </listitem>
  </itemizedlist>
  <simpara>
   Finally, you are going to need the source to PHP itself. You can get the
   latest development version using <link xlink:href="&url.php.anoncvs;">anonymous
   CVS</link>, a <link xlink:href="&url.php.snapshots;">snapshot</link> or the
   most recent released <link xlink:href="&url.php.downloads;">source</link>
   tarball.
  </simpara>
 </sect2>

 <sect2 xml:id="install.windows.building.install">
  <title>Putting it all together</title>
  <para>
   After downloading the required packages you have to extract them in a
   proper place:
   <itemizedlist>
    <listitem>
     <simpara>
      Create a working directory where all files end up after extracting, e.g:
      <filename class="directory">C:\work</filename>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Create the directory <filename>win32build</filename> under your  working
      directory (<filename class="directory">C:\work</filename>) and unzip
      <filename>win32build.zip</filename> into it.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Create the directory <filename>bindlib_w32</filename> under your working
      directory (<filename class="directory">C:\work</filename>) and unzip
      <filename>bindlib_w32.zip</filename> into it.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Extract the downloaded PHP source code into your working directory
      (<filename class="directory">C:\work</filename>).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Build the libraries you are going to need (or download the binaries if
      available) and place the headers and libs in the <filename
       class="directory">C:\work\win32build\include</filename> and <filename
       class="directory">C:\work\win32build\lib</filename> directories,
      respectively.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      If you don't have cygwin installed with bison and flex, you also need to
      make the <filename class="directory">C:\work\win32build\bin</filename>
      directory available in the PATH, so that thoses tools can be found by
      the configure script.
     </simpara>
    </listitem>
   </itemizedlist>
   Following this steps your directory structure looks like this:
   <screen>
<![CDATA[
+--C:\work
|  |
|  +--bindlib_w32
|  |  |
|  |  +--arpa
|  |  |
|  |  +--conf
|  |  |
|  |  +--...
|  |
|  +--php-5.x.x
|  |  |
|  |  +--build
|  |  |
|  |  +--...
|  |  |
|  |  +--win32
|  |  |
|  |  +--...
|  |
|  +--win32build
|  |  |
|  |  +--bin
|  |  |
|  |  +--include
|  |  |
|  |  +--lib
]]>
   </screen>
  </para>
  <para>
   If you aren't using <link xlink:href="&url.cygwin;">Cygwin</link>, you must also
   create the directories <filename
    class="directory">C:\usr\local\lib</filename> and then copy
   <filename>bison.simple</filename> from <filename
    class="directory">C:\work\win32build\bin </filename> to <filename
    class="directory">C:\usr\local\lib</filename>.
  </para>
  <note>
   <simpara>
    If you want to use PEAR and the comfortable command line installer, the
    CLI-SAPI is mandatory. For more information about PEAR and the installer
    read the documentation at the <link
     xlink:href="&url.php.pear.manual;">PEAR</link> website.
   </simpara>
  </note>
 </sect2>

 <sect2 xml:id="install.windows.building.resolvlib">
  <title>Build resolv.lib</title>
  <para>
   You must build the <filename>resolv.lib</filename> library. Decide whether
   you want to have debug symbols available (bindlib - Win32 Debug) or not
   (bindlib - Win32 Release), but please remember the choice you made, because
   the debug build will only link with PHP when it is also built in debug mode.
   Build the appropriate configuration:
   <itemizedlist>
    <listitem>
     <simpara>
      For GUI users, launch VC++, by double-clicking in
      <filename>C:\work\bindlib_w32\bindlib.dsw</filename>. Then select
      Build=&gt;Rebuild All.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      For command line users, make sure that you either have the C++
      environment variables registered, or have run
      <command>vcvars.bat</command>, and then execute one of the following
      commands:
     </simpara>
     <itemizedlist>
      <listitem>
       <simpara>
        <command>msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"</command>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <command>msdev bindlib.dsp /MAKE "bindlib - Win32 Release"</command>
       </simpara>
      </listitem>
     </itemizedlist>
    </listitem>
   </itemizedlist>
   At this point, you should have a usable <filename>resolv.lib</filename> in
   either your <filename
   class="directory">C:\work\bindlib_w32\Debug</filename> or
   <filename>Release</filename> subdirectories. Copy this file into your
   <filename class="directory">C:\work\win32build\lib</filename> directory
   over the file by the same name found in there.
  </para>
 </sect2>

 <sect2 xml:id="install.windows.building.new">
  <title>Building PHP using the new build system [PHP &gt;=5 only]</title>
  <para>
   This chapter explains how to compile PHP &gt;=5 using the new build system,
   which is CLI-based and very similar with the main PHP's Unix build system.
  </para>
  <note>
   <para>
    This build system isn't available in PHP 4. Please refer to <xref
    linkend="install.windows.building.dsw"/> instead.
   </para>
  </note>
  <para>
   Before starting, be sure you have read <xref
    linkend="install.windows.building.install"/> and you have built all needed
   libraries, like <link xlink:href="&url.libxml;">Libxml</link> or <link
    xlink:href="&url.icu;">ICU</link> (needed for PHP &gt;= 6).
  </para>
  <para>
   First you should open a Visual Studio Command Prompt, which should be
   available under the Start menu. A regular Command Prompt window shouldn't
   work, as probably it doesn't have the necessary environment variables set.
   Then type something like <command>cd C:\work\php-5.x.x</command> to enter
   in the PHP source dir. Now you are ready to start configuring PHP.
  </para>
  <para>
   The second step is running the <command>buildconf</command> batch file to
   make the configure script, by scanning the folder for
   <filename>config.w32</filename> files. By default this command will also
   search in the following directories: <filename class="directory">pecl;
   ..\pecl; pecl\rpc; ..\pecl\rpc</filename>. Since PHP 5.1.0, you can change
   this behaviour by using the <literal>--add-modules-dir</literal> argument
   (e.g. <command>cscript /nologo win32/build/buildconf.js
    --add-modules-dir=../php-gtk2 --add-modules-dir=../pecl</command>).
  </para>
  <para>
   The third step is configuring. To view the list of the available
   configuration options type <command>cscript /nologo configure.js
   --help</command>. After choosing the options that you will enable/disable,
   type something like: <command>cscript /nologo configure.js --disable-foo
   --enable-fun-ext</command>. Using <literal>--enable-foo=shared</literal>
   will attempt to build the 'foo' extension as a shared, dynamically loadable
   module.
  </para>
  <para>
   The last step is compiling. To achieve this just issue the command
   <command>nmake</command>. The generated files (e.g. .exe and .dll) will be
   placed in either <filename class="directory">Release_TS</filename> or
   <filename class="directory">Debug_TS</filename> directories (if built with
   Thread safety), or in the <filename class="directory">Release</filename> or
   <filename class="directory">Debug</filename> directories otherwise.
  </para>
  <para>
   Optionally you may also run PHP's test suite, by typing <command>nmake
   test</command>. If you want to run just a specific test, you may use the
   'TESTS' variable (e.g. <command>nmake /D TESTS=ext/sqlite/tests
   test</command> - will only run sqlite's tests). To delete the files that
   were created during the compilation, you can use the <command>nmake
   clean</command> command.
  </para>
  <para>
   A very useful configure option to build snapshots is
   <literal>--enable-snapshot-build</literal>, which add a new compiling mode
   (<command>nmake build-snap</command>). This tries to build every extension
   available (as shared, by default), but it will ignore build errors in
   individual extensions or SAPI.
  </para>
 </sect2>

 <sect2 xml:id="install.windows.building.dsw">
  <title>Building PHP using DSW files [PHP 4]</title>
  <para>
   Compiling PHP using the DSW files isn't supported as of PHP 5, as a much
   <link linkend="install.windows.building.new">more flexible system was made
    available</link>. Anyway, you can still use them, but keep in mind that
   they are not maintained very often, so you can have compiling problems. To
   compile PHP 4 for windows, this is the only available way though.
  </para>
 
  <sect3 xml:id="install.windows.building.dsw.configure">
   <title>Configure MVC ++</title>
   <para>
    The first step is to configure MVC++ to prepare for compiling. Launch
    Microsoft Visual C++, and from the menu select Tools =&gt; Options. In the
    dialog, select the directories tab. Sequentially change the dropdown to
    Executables, Includes, and Library files. Your entries should look like
    this:
    <itemizedlist>
     <listitem>
      <simpara>
       Executable files: <filename
       class="directory">C:\work\win32build\bin</filename>, Cygwin users:
       <filename>C:\cygwin\bin</filename>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Include files: <filename
       class="directory">C:\work\win32build\include</filename>
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Library files: <filename
       class="directory">C:\work\win32build\lib</filename>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </sect3>

  <sect3 xml:id="install.windows.building.dsw.compile">
   <title>Compiling</title>
   <simpara>
    The best way to get started is to build the CGI version:
   </simpara>
   <itemizedlist>
    <listitem>
     <simpara>
      For GUI users, launch VC++, and then select File =&gt; Open Workspace
      and select <filename>C:\work\php-4.x.x\win32\php4ts.dsw</filename>. Then
      select Build=&gt;Set Active Configuration and select the desired
      configuration, either <literal>php4ts - Win32 Debug_TS</literal> or
      <literal>php4ts - Win32 Release_TS</literal>. Finally select
      Build=&gt;Rebuild All.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      For command line users, make sure that you either have the C++
      environment variables registered, or have run
      <command>vcvars.bat</command>, and then execute one of the following
      commands from the <filename
      class="directory">C:\work\php-4.x.x\win32</filename> directory:
     </simpara>
     <itemizedlist>
      <listitem>
       <simpara>
        <command>msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"</command>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <command>msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"</command>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        At this point, you should have a usable <filename>php.exe</filename>
        in either your <filename
        class="directory">C:\work\php-4.x.x\Debug_TS</filename> or
        <filename>Release_TS</filename> subdirectories.
       </simpara>
      </listitem>
     </itemizedlist>
    </listitem>
   </itemizedlist>
   <simpara>
    It is possible to do minor customization to the build process by editing
    the <filename>main/config.win32.h</filename> file. For example you can
    change the default location of &php.ini;, the built-in extensions, and the
    default location for your extensions.
   </simpara>
   <simpara>
    Next you may want to build the CLI version which is designed to use <link
    linkend="features.commandline">PHP from the command line</link>. The steps
    are the same as for building the CGI version, except you have to select
    the <literal>php4ts_cli - Win32 Debug_TS</literal> or <literal>php4ts_cli
    - Win32 Release_TS</literal> project file. After a successful compiling
    run you will find the <filename>php.exe</filename> in either the directory
    <filename class="directory">Release_TS\cli\</filename> or <filename
    class="directory">Debug_TS\cli\</filename>.
   </simpara>
   <simpara>
    In order to build the SAPI module (<filename>php4isapi.dll</filename>) for
    integrating PHP with Microsoft IIS, set your active configuration to
    <filename>php4isapi-whatever-config</filename> and build the desired dll.
   </simpara>
  </sect3>
 </sect2>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->