Further clarifications around using external PCRE and the builds to create for a...

diff --git a/OS X Package Builder HOWTO.txt b/OS X Package Builder HOWTO.txt
index a12e584..ff55b98 100644 (file)
--- a/OS X Package Builder HOWTO.txt
+++ b/OS X Package Builder HOWTO.txt
@@ -25,25 +25,41 @@ DETAILS
 
 Use privoxy-create.sh (run via sudo) to create the privoxy group and user; these are a prerequisite for the build process.
 
-Use build.sh to build a privoxy binary for the desired (range of) platform(s). The simplest usage is:
+Use build.sh to build a privoxy binary for the desired (range of) platform(s) and to control whether or not to compile against the external PCRE library (see 1.1 below). The simplest usage is:
 
 ./build.sh leopardupwards
 
 which will build a Universal binary containing targets for PPC, i386 and x86_64 processor architectures that'll run on all Macintosh OS X versions from 10.5 (Leopard) and upwards. If however you would prefer to, for example, build a binary that runs solely on 64 bit Intel processors, you could instead use:
 
-./build.sh snowleopard64
+./build.sh snowleopardx64
 
 Running build.sh without supplying any parameters will cause it to list all the possible options.
 
+
 1.1 Consider whether to use external or bundled PCRE.
 
-Privoxy uses the Perl Compatible Regular Expressions (PCRE) library when matching its rules against the folder-and-file part of a target URL. Privoxy ships with a bundled PCRE library that, whilst convenient, is very out of date (version 3). The recommendation is therefore to download, make and install the latest PCRE distribution to your build machine and compile Privoxy against that instead.
+Privoxy uses the Perl Compatible Regular Expressions (PCRE) library when matching its rules against the folder-and-file part of a target URL. Privoxy's source ships with a version of the PCRE library that, whilst convenient, is very out of date (version 3). The recommendation is therefore to download, make and install the latest PCRE distribution to your build machine and compile Privoxy against that instead.
+
+To support this, build.sh takes an optional second parameter (-pcre) which tells it to look for an installation of the PCRE library in the standard location on the build machine (/usr/local/lib). The obvious corrollary is that you must have downloaded, configured, made and installed PCRE before building Privoxy if you wish to link to the external library.
+
+There are two important further considerations that this approach brings. Firstly, you must ensure when building PCRE that you build it to support the same minimum version of OS X that you wish Privoxy to support (note that by default PCRE's build process assumes the OS X version of the build machine is the minimum version to be supported). Failure to match the minimum supported versions will mean that, whilst Privoxy will still build, the external PCRE check will fail and you will end up compiling in the bundled PCRE, not linking to the external PCRE library as you'd intended.
+
+The second consideration when using external PCRE is that the PCRE build process allows only single-architecture libraries to be built, which means that the Privoxy binary you build must also be single-architecture. The outcome of not following this rule would be as above; you will succeed in building Privoxy but it will compile in the bundled PCRE rather than linking to the external library.
+
+A sample command line for building Privoxy with external PCRE to run on Snow Leopard and higher on 64 bit Intel Macs is:
+
+./build.sh snowleopardx64 -pcre
+
+
+1.2 Builds for the Sourceforge Privoxy project release set
 
-build.sh takes an optional second parameter (-pcre) which tells it to look for an installation of the PCRE library in the standard location on the build machine (/usr/local/lib). The obvious corrollary is that you must have downloaded, configured, made and installed PCRE before building Privoxy if you wish to link to the external library.
+Three packages are built for this target release set:
 
-There are two important further considerations that this approach brings. Firstly, you must ensure when building PCRE that you build it to support the same minimum version of OS X that you wish Privoxy to support (note that by default PCRE will assume the OS X version of the build machine is the minimum version to be supported). Failure to observe this will mean that, whilst Privoxy will still build, the external PCRE check will fail and you will end up compiling in the bundled PCRE, not linking to the external PCRE library as you'd intended.
+./build.sh snowleopardx64 -pcre
+./build.sh tigeri386 -pcre
+./build.sh tigerppc -pcre
 
-The second consideration when using external PCRE is that the PCRE build process allows only single-architecture libraries to be built, which means that your Privoxy binary can also only be single-architecture. The outcome of not following this rule would be as above; you will succeed in building Privoxy but it will compile in the bundled PCRE rather than linking to the external library.
+The rationale is that the first one will support 64 bit systems running 10.6 and higher, the second 32 bit Intel running 10.4 or 10.5, and the last one PPC systems running 10.4 or 10.5.
 
 
 
@@ -57,14 +73,15 @@ Once this is done, the file 'pkg resources/interface texts/ReadMe.txt' will need
 
 3. Build the package
 
-Three different Packagemaker project files are supplied, though the procedure is the same regardless of which you need to use:
+Several different Packagemaker project files are supplied, though the procedure is the same regardless of which you need to use:
 
 - OS X 10.5+ PCRE.pmdoc - if you have built Privoxy against an external PCRE library (see 1.1 above).
 - OS X 10.5+.pmdoc - if you are using the bundled PCRE library.
-- OS X 10.4.pmdoc - for Tiger builds with the bundled PCRE library.
+- OS X 10.4+ PCRE.pmdoc - if you have built Privoxy against an external PCRE library (see 1.1 above) but wish to target a minimum OS X version of 10.4.
+- OS X 10.4.pmdoc - for OS X 10.4-minumum builds with the bundled PCRE library.
 
 Refer to the separate document "Packagemaker Instructions.txt" for complete instructions, however the following item is all that needs to be changed if you are building a package for a newer version of Privoxy:
 
 'pkg content left-menu item>pkg content>Configuration>Package Version'
 
-Finally click the 'Build' button at screen top-left. The package filename is up to you but I recommend "Privoxy <version>.pkg", e.g. "Privoxy 3.0.19.pkg". For the down-level release I have used "Privoxy <version> OS X 10.4.mpkg"
\ No newline at end of file
+Finally click the 'Build' button at screen top-left. The package filename is up to you but I recommend "Privoxy <version> <architecture>.pkg", e.g. "Privoxy 3.0.19 64 bit.pkg".
\ No newline at end of file