php/README.WIN32-BUILD-SYSTEM

The Win32 Build System.
$Id$
Wez Furlong <wez@thebrainroom.com>

If you need help with the build system, send mail to
internals@lists.php.net; please don't email me directly.

===========================================================
Contents:
1. How to build PHP under windows
 a. Requirements
 b. Opening a command prompt
 c. Generating configure.js
 d. Configuring
 e. Building
 f. Cleaning up
 g. Running the test suite
 h. snapshot building
 
2. How to write config.w32 files
 x. to be written.

===========================================================
1. How to build PHP under windows
a. Requirements

 You need:
  - Windows Scripting Host (cscript.exe)
  - Microsoft Build Tools from:
     Microsoft Visual Studio (VC6) or later
 
 You also need:
  - bindlib_w32 [http://www.php.net/extra/bindlib_w32.zip]
  - win32build  [http://www.php.net/extra/win32build.zip]

 b. Opening the Build Environment Command Prompt:
  - Using Visual Studio (VC6)
    1. Install it
    2. If you have a VC++ Command Prompt icon on your start menu,
       click on it to get a Command Prompt with the env vars
       set up correctly.

       If not, create a new shortcut and set the Target to:

       %comspec% /k "C:\Program Files\Microsoft Visual Studio\VC98\Bin\vcvars32.bat"

       You might also want to set the prompt to start in
       a convenient location (such as the root of your
       PHP source checkout).

  - Using Visual Studio .Net
    1. Install it.
    2. Under the Visual Studio .Net Tools sub menu of your start
       menu, you should have a Visual Studio .Net Command Prompt
       icon.  If not, create a new shortcut and set the Target to:

       %comspec% /k "C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat"

       You might also want to set the prompt to start in
       a convenient location (such as the root of your
       PHP source checkout).

  - Using the Platform SDK tools
    1. Download the Platform SDK:
       http://www.microsoft.com/msdownload/platformsdk/sdkupdate/

       - You need the Core SDK, which is approx 200MB to download
         and requires approx 500MB of disk space.
       - The other components of the SDK are not required by PHP
       - You might be able to reduce the download size by downloading
         the installer control component first and then selecting
         only the Build Environment (around 30MB), but I haven't
         tried this.

         ** Note: it seems that MS don't include the 32 bit
            build tools in the platform SDK any longer, so
            you will probably have very limited luck if you
            don't also have VC++ or VS.Net already installed.

    2. Once installed, you will have an icon on your start menu
       that will launch the build environment; the latest SDK's
       install a number of different versions of this; you probably
       want to choose the Windows 2000 Retail build environment.
       Clicking on this will open a command prompt with its Path,
       Include and Lib env vars set to point to the build tools
       and win32 headers.

c. Generating configure

 Change directory to where you have your PHP 5 sources.
 Run buildconf.bat.

d. Configuring
 
 cscript /nologo configure.js --help
 
 Will give you a list of configuration options; these will
 have the form:
 
 --enable-foo or --disable-foo or --with-foo or --without-foo.
 
 --enable-foo will turn something on, and is equivalent to
 specifying --enable-foo=yes
 
 --disable-foo will turn something off, and is equivalent to
 specifying --enable-foo=no

 --enable-foo=shared will attempt to build that feature as
 a shared, dynamically loadable module.

 Sometimes a configure option needs additional information
 about where to find headers and libraries; quite often
 you can specify --enable-foo=option where option could be
 the path to where to find those files.  If you want to
 specify a parameter and build it as shared, you can use
 this syntax instead:  --enable-foo=shared,option

 The same rules all apply to --with-foo and --without-foo;
 the only difference is the way the options are named;
 the convention is that --enable-foo means that you are
 switching on something that comes with PHP, whereas
 --with-foo means that you want to build in something
 external to PHP.

e. Building

 Once you have successfully configured your build (make
 sure you read the output from the command to make sure
 it worked correctly), you can build the code; simply type

 "nmake" at the command prompt, and it will build everthing
 you asked for.

 Once the build has completed, you will find your binaries
 in the build dir determined by configure; this is typically
 Release_TS for release builds or Debug_TS for debug builds.
 If you build a non-thread-safe build, it will use Release
 or Debug to store the files.  Also in this build dir you
 will find sub directories for each module that went into
 your PHP build.  The files you'll want to keep are the
 .exe and .dll files directly in your build dir.

f. Cleaning Up
 
 You can automatically delete everything that was built
 by running "nmake clean".  This will delete everything
 that was put there when you ran nmake, including the
 .exe and .dll files.

g. Running the test suite

 You can verify that your build is working well by running
 the regression test suite.  You do this by typing
 "nmake test".  You can specify the tests you want to run
 by defing the TESTS variable - if you wanted to run the
 sqlite test suite only, you would type
 "nmake /D TESTS=ext/sqlite/tests test"

h. Snapshot Building

 If you want to set up an automated build that will tolerate
 breakages in some of the modules, you can use the
 --enable-snapshot-build configure option to generate a
 makefile optimized for that purpose.  A snapshot build will
 switch the argument parser so that the default option for
 configure switches that your don't specify will be set
 to "shared".  The effect of this is to turn on all options
 unless you explicitly disable them.  When you have configured
 your snapshot build, you can use "nmake build-snap" to build
 everything, ignoring build errors in individual extensions
 or SAPI.

vim:tw=78:sw=1:ts=1:et