nlopess Sun Sep 18 13:01:14 2005 EDT
Modified files:
/phpdoc/en/install/windows building.xml
Log:
start documentin the new build system (PHP 5)
some structural changes and WS fixes
http://cvs.php.net/diff.php/phpdoc/en/install/windows/building.xml?r1=1.4&r2=1.5&ty=u
Index: phpdoc/en/install/windows/building.xml
diff -u phpdoc/en/install/windows/building.xml:1.4
phpdoc/en/install/windows/building.xml:1.5
--- phpdoc/en/install/windows/building.xml:1.4 Sun Aug 15 08:42:40 2004
+++ phpdoc/en/install/windows/building.xml Sun Sep 18 13:01:12 2005
@@ -1,116 +1,93 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
- <sect1 id="install.windows.building">
- <title>Building from source</title>
- <para>
- Before getting started, it is worthwhile answering the question:
- "Why is building on Windows so hard?" Two reasons come to mind:
- </para>
- <orderedlist>
- <listitem>
- <simpara>
- Windows does not (yet) enjoy a large community of developers
- who are willing to freely share their source. As a direct
- result, the necessary investment in infrastructure required
- to support such development hasn't been made. By and large,
- what is available has been made possible by the porting of
- necessary utilities from Unix. Don't be surprised if some of
- this heritage shows through from time to time.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Pretty much all of the instructions that follow are of the
- "set and forget" variety. So sit back and try follow the
- instructions below as faithfully as you can.
- </simpara>
- </listitem>
- </orderedlist>
+<!-- $Revision: 1.5 $ -->
+<sect1 id="install.windows.building">
+ <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 id="install.windows.building.requirement">
- &reftitle.required;
- <para>
- To compile and build PHP you need a Microsoft
- Development Environment. Microsoft Visual C++ 6.0 is recommended.
- To extract the downloaded files you need a extraction utility
- (e.g.: Winzip). If you don't already have an unzip utility, you
- can get a free version from <ulink url="&url.infozip;">InfoZip</ulink>.
- </para>
- <para>
- Before you get started, you have to download...
- </para>
- <itemizedlist>
- <listitem>
- <simpara>
- ..the win32 buildtools from the PHP site
- at <ulink url="&url.win32.buildtools;">&url.win32.buildtools;</ulink>.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- ..the source code for the DNS name resolver used by PHP from
- <ulink url="&url.win32.dnsresolver;">
- &url.win32.dnsresolver;</ulink>. 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 <ulink url="&url.apache.source;">Apache
- sources</ulink>.
- </simpara>
- </listitem>
- </itemizedlist>
+ <sect2 id="install.windows.building.requirement">
+ &reftitle.required;
+ <para>
+ To compile and build PHP you need a Microsoft Development Environment.
+ Microsoft Visual C++ 6.0 is recommended, although .NET versions will also
+ work. To extract the downloaded files you need a ZIP extraction utility
+ (e.g. Winzip). 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 <ulink
+ url="&url.win32.buildtools;">&url.win32.buildtools;</ulink>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ the source code for the DNS name resolver used by PHP from <ulink
+ url="&url.win32.dnsresolver;">&url.win32.dnsresolver;</ulink>. 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
+ <ulink url="&url.apache.source;">Apache sources</ulink>.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <simpara>
+ Finally, you are going to need the source to PHP itself. You can get the
+ latest development version using <ulink url="&url.php.anoncvs;">anonymous
+ CVS</ulink>, a <ulink url="&url.php.snapshots;">snapshot</ulink> or the
+ most recent released <ulink url="&url.php.downloads;">source</ulink>
+ tarball.
+ </simpara>
+ </sect2>
+
+ <sect2 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>
- Finally, you are going to need the source to PHP itself. You can get
- the latest development version using <ulink url="&url.php.anoncvs;">
- anonymous CVS</ulink>, a <ulink url="&url.php.snapshots;">
- snapshot</ulink> or the most recent released <ulink
url="&url.php.downloads;">
- source</ulink> tarball.
+ Create a working directory where all files end up after extracting, e.g:
+ <filename class="directory">C:\work</filename>.
</simpara>
- </sect2>
-
- <sect2 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>
- </itemizedlist>
- Following this steps your directory structure looks like this:
- <informalexample>
- <programlisting>
+ </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>
+ </itemizedlist>
+ Following this steps your directory structure looks like this:
+ <screen>
<![CDATA[
-
-+--c:\work
++--C:\work
| |
| +--bindlib_w32
| | |
@@ -120,7 +97,7 @@
| | |
| | +--...
| |
-| +--php-4.x.x
+| +--php-5.x.x
| | |
| | +--build
| | |
@@ -137,177 +114,248 @@
| | +--include
| | |
| | +--lib
-
]]>
- </programlisting>
- </informalexample>
- Create the directories <filename
class="directory">c:\usr\local\lib</filename>. 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>
- <ulink url="&url.cygwin;">Cygwin</ulink> users may omit the last
- step. A properly installed Cygwin environment provides the mandatory
- files <filename>bison.simple</filename> and
- <filename>bison.exe</filename>.
- </simpara>
- </note>
- </sect2>
-
- <sect2 id="install.windows.building.configure">
- <title>Configure MVC ++</title>
- <para>
- The next step is to configure MVC ++ to prepare for compiling.
- Launch Microsoft Visual C++, and from the menu select
- Tools => 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>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>
- </sect2>
+ </screen>
+ </para>
+ <para>
+ If you aren't using <ulink url="&url.cygwin;">Cygwin</ulink>, 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>
+ </sect2>
- <sect2 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).
- Build the appropriate configuration:
- <itemizedlist>
- <listitem>
- <simpara>
- For GUI users, launch VC++, and then select File => Open
- Workspace, navigate to <filename
class="directory">c:\work\bindlib_w32</filename> and
- select <filename>bindlib.dsw</filename>. Then select Build=>Set
- Active Configuration and select the desired configuration.
- Finally select Build=>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>
- <userinput>msdev bindlib.dsp /MAKE "bindlib - Win32
Debug"</userinput>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <userinput>msdev bindlib.dsp /MAKE "bindlib - Win32
Release"</userinput>
- </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 id="install.windows.building.compile">
- <title>Compiling</title>
+ <sect2 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
+ you'll have to build PHP in the same way, or you may get linking errors.
+ 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=>Rebuild All.
+ </simpara>
+ </listitem>
+ <listitem>
<simpara>
- The best way to get started is to build the CGI version.
+ 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>
- For GUI users, launch VC++, and then select File => Open
- Workspace and select <filename>c:\work\php-4.x.x\win32\php4ts.dsw
- </filename>. Then select Build=>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=>Rebuild All.
+ <command>msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"</command>
</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:
+ <command>msdev bindlib.dsp /MAKE "bindlib - Win32 Release"</command>
</simpara>
- <itemizedlist>
- <listitem>
- <simpara>
- <userinput>msdev php4ts.dsp /MAKE "php4ts - Win32
Debug_TS"</userinput>
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <userinput>msdev php4ts.dsp /MAKE "php4ts - Win32
Release_TS"</userinput>
- </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>
- <note>
+ </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 id="install.windows.building.new">
+ <title>Building PHP using the new build system [PHP >=5 only]</title>
+ <para>
+ This chapter explains how to compile PHP >=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>
+ 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>buildconf --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 compilling. 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 usefull 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 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
+ more flexible system was made available. 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 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 => 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>
- 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 <ulink
url="&url.php.pear;manual/">
- PEAR</ulink> website.
+ Executable files: <filename
+ class="directory">C:\work\win32build\bin</filename>, Cygwin users:
+ <filename>C:\cygwin\bin</filename>
</simpara>
- </note>
+ </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 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 => Open Workspace
+ and select <filename>C:\work\php-4.x.x\win32\php4ts.dsw</filename>. Then
+ select Build=>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=>Rebuild All.
+ </simpara>
+ </listitem>
+ <listitem>
<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.
+ 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>
- </sect2>
- </sect1>
+ <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>
+ <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 <ulink
+ url="&url.php.pear.manual;">PEAR</ulink> website.
+ </simpara>
+ </note>
+ <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:
