rewrite

1 files changed, 157 insertions, 60 deletions

diff --git a/README.WIN32-BUILD-SYSTEM b/README.WIN32-BUILD-SYSTEM
index 798c60e906..a9afc0c083 100644
--- a/README.WIN32-BUILD-SYSTEM
+++ b/README.WIN32-BUILD-SYSTEM
@@ -1,61 +1,158 @@
-I've committed the build infrastructure for the 
-"real programmers don't need an IDE" build system for win32.
-
-Why?
-- It's frustrating to have to use VC6 to work on PHP if you
-  have a newer version that has incompatible project files.
-- It's annoying to mess around with libxml2 stuff until it
-  stabilizes :-) and a pain to have to remember to edit
-  the config.w32.h header each time, and a pain to have to
-  avoid accidentally committing those changes each time.
-- It's difficult to set up a fully working build environment
-  for PHP without installing everything.
-- It's difficult for people without VC6 to create a win32
-  project file for their extensions.
-
-Requirements:
-You need windows script host (cscript.exe) and JScript installed.
-This should be a standard config on windows machines since win98
-(perhaps optional under win98).
-
-You also need the Microsoft build tools (cl.exe, link.exe and nmake.exe).
-These are freely available as part of the Platform SDK, but also
-come with VC++/Visual Studio.
-
-Finally, you need the php_build dir that contains all the
-headers and libraries for the things that php is linked
-against; see [1] for details.
-
-Usage:
-Check out PHP 5 and run buildconf.bat from the root of the php
-source.  This script is roughly equivalent to the unix buildconf
-in that it scans ext/* and sapi/* for config.w32 files describing
-optional build components and generates a configure script
-named configure.js
-
-Now run "cscript configure.js --help" to get a list of configure
-options; enable and disable stuff as appropriate.
-
-Then type nmake to build the things you configured.
-
-You will find the various .exe and .dll files in the build dir
-that configure selects for you based on debug and zts settings;
-it will be one of the usual Debug_TS, Release_TS, Debug or Release
-dirs found under the source root.
-
-You can also run the test suite by running "nmake test".
-[we have some issues under win32 with current CVS!]
-
-TODO:
-- Write config.w32 files for more extensions and sapis.
-  They're quite easy (just a couple of javascript function calls)
-  and can be put together almost without thinking by copying the
-  guts of the config.m4 file from the same extension.
-- add those .rc files with version info the generated .dll's and .exe's
-- Test if it actually works under win98 (Steph?)
-  There are only two places that I suspect might have difficulty
-  under win98.
-
-[1] 
-http://www.php.net/manual/en/install.windows.php#install.windows.build
+The Win32 Build System.
+$Id$
+Wez Furlong <wez@thebrainroom.com>
+
+NB: Please don't mail me asking for help on this, unless
+you are a Core PHP developer, or you are prepared to donate
+some money via paypal or buy me something from my wishlist.
+http://pecl.php.net/user/wez
+Thanks :-)
+
+===========================================================
+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
+ 
+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 either:
+     Microsoft Visual Studio (VC6) or later
+  Microsoft Platform SDK
+ 
+ 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.
+
+    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"
+
+vim:tw=78:sw=1:ts=1:et