ASSUMPTIONS
-1. That the Privoxy CVS project is available in a folder parallel to the one containing this file. If building for release it should have been exported from Sourceforge to a folder named 'dist', pinned at whichever release you intend to build (as per the instructions in the developer manual), you might have simply checked out the head of the CVS project to a folder named 'current'. If you are using a folder name other than these two you will be prompted to enter it.
+1. That the Privoxy CVS project is available in a folder parallel to the one containing this file.
+- If building for release it MUST have been exported from Sourceforge to a folder named 'dist', pinned at whichever release you intend to build (as per the instructions in the Privoxy developer manual)
+- If doing a general test build, you might have simply checked out the head of the CVS project to a folder named 'current'.
+- If you are using a folder name other than these two (or else both exist) you will be prompted to enter the source folder you wish to use when running the scripts detailed below.
2. That you have Xcode installed, including the SDKs for each OS X version you intend your package(s) to support.
3. That your build machine runs Snow Leopard (OS X 10.6). It will likely work equally well on Leopard or Lion (or later), but PackageMaker is substantially different in Tiger and earlier versions of OS X (even the project file format is different).
4. All references to files and folders in this document should be assumed to be within the OSXBuildSystem folder unless stated otherwise.
1. Build the privoxy binary
1.1 Consider whether to use external or bundled PCRE.
+1.2 Builds for the Sourceforge Privoxy project release set
2. Construct the package contents hierarchy
+2.1 Update the supporting documentation for the release
+2.2 Bring together all the contents ready to package
3. Build the package
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 most compatible 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:
+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. The disadvantage of bundling multiple processor architectures is that the build is consequently limited to using the bundled PCRE implementation, which is a Bad Idea™ (see section 1.1 for details).
-./build.sh snowleopard64
+The most common usage therefore would be as follows:
+
+./build.sh snowleopardx64 -pcre
+
+which will build a binary targetting only x86_64 processors (note that OS X has supported only x86_64 since Snow Leopard).
+
+Running build.sh without supplying any parameters will cause it to list all the possible options, should you have an alternative target requirement.
-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. 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 three 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.
+
+The final consideration is that if you are building Privoxy for multiple different targets, you must also build PCRE independently for each of those targets and, when building that target's Privoxy release, ensure that the correct version of PCRE is present in /usr/local/lib.
+
+A sample command line that will build Privoxy with external PCRE to run on Snow Leopard and higher on 64 bit Intel Macs is:
-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.
+./build.sh snowleopardx64 -pcre
+This example assumes that a valid build of PCRE supporting x86_64 processors and a minimum OS X version of 10.6 is present in /usr/local/lib.
-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.
-The second consideration when using external PCRE is that the PCRE build process allows only single-architecture libraries to be built; the corollary being that your Privoxy binary 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.
+1.2 Builds for the Sourceforge Privoxy project release set
+Three packages are built for this target release set:
+
+./build.sh snowleopardx64 -pcre
+./build.sh tigeri386 -pcre
+./build.sh tigerppc -pcre
+
+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.
+
+Note that in order to build each version, the pcre library fileset must be changed to match the architecture being built.
2. Construct the package contents hierarchy
-Use constructPkgContent.sh to build the hierarchy of folders and files necessary for building the package. This will construct a new folder named 'pkg content' and copy in the binary, documentation and supporting files. If you are bundling an external PCRE fileset, use the optional switch -pcre to instruct constructPkgContent.sh to include those files.
+This comprises two steps:
+- ensuring the supporting documentation is updated for the release
+- using the supplied script to bring all the package contents together
-Once this is done, the file 'pkg resources/interface texts/ReadMe.txt' will need to be edited to give a precis of what this release of Privoxy brings. This can be distilled from the README for the latest Privoxy project release.
+2.1 Update the supporting documentation for the release
+The file 'pkg resources/interface texts/ReadMe.txt' is displayed on one of the installer screens; it will need to be edited to give a precis of what this release of Privoxy brings. This can be distilled from the README for the latest Privoxy project release.
+If there is any late-breaking or important info, it should be added to 'pkg content skeleton/Applications/Privoxy/readme.rtfd. This file MUST be edited with TextEdit, however BEWARE! TextEdit rtfd documents are actually a folder with files within (right-click and choose 'Show package contents' to see within). Inside you'll see a CVS folder that the cvs file storage repository software uses to keep track of that folder's files. If you save an .rtfd document in TextEdit, it will delete the CVS folder! The workaround then is to move that folder elsewhere, make the necessary file edits and save, close TextEdit and then move the folder back in place before committing the files back with cvs.
-3. Build the package
+2.2 Bring together all the contents ready to package
-Three different Packagemaker project files are supplied, though the procedure is the same regardless of which you need to use:
+Use constructPkgContent.sh to build the hierarchy of folders and files necessary for building the package. This will construct a new folder named 'pkg content' and copy in the binary, documentation and supporting files. If you are bundling an external PCRE fileset (i.e. if you built privoxy to use an external PCRE library), use the optional switch -pcre to instruct constructPkgContent.sh to include the libpcre fileset, which it will source from the standard installed location on the build machine (/usr/local/lib). The typical command line then is:
-- 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.
+./constructPkgContent.sh -pcre
+
+
+3. Build the package
-Refer to the separate document "Packagemaker Instructions.txt" for complete instructions, however the following covers the list of mandatory changes to make per release:
+Several different Packagemaker project files are supplied, though the procedure is the same regardless of which you need to use:
-'Distribution left-menu item>Configuration>Title'
-'pkg content left-menu item>pkg content>Configuration>Package Identifier'
+- OS X 10.6+ PCRE.pmdoc - if you have built Privoxy against an external PCRE library (see 1.1 above).
+- OS X 10.5+ 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.5.
+- OS X 10.5+.pmdoc - for OS X 10.5-minumum 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.
-Navigate to 'pkg content left-menu item>pkg content>Scripts'
+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:
-and drag and drop the directory 'pkg resources/single-binary scripts' from your file browser (e.g. Finder) into the 'Scripts directory' entry box. This MUST be left as an 'absolute' path due to a bug in PackageMaker; if you select 'relative to project' then the scripts will not be found nor added to the package at build time.
+'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
projects / OSXPackageBuilder.git / blobdiff