Clarified pre-requisites with respect to where the privoxy software should be checked out
[OSXPackageBuilder.git] / Packagemaker Instructions.txt
1 Packagemaker instructions
2
3 The following gives raw information on what settings need to be edited when creating a new Privoxy package when starting from a new project in Packagemaker. You should NOT need to follow all of these instructions if you are starting from one of the Packagemaker project files (*.pmdoc) already present in this directory.
4
5 At the end of the document are some additional (very) useful notes regarding certain Packagemaker quirks and bugs.
6
7 Each section in this document from here on relates to one entry tab in the Packagemaker interface - you should populate each tab in the order presented below.
8
9
10
11 Package Properties
12
13 Organisation is: org.ijbswa.privoxy
14 Minimum target depends on which release is being built.
15
16
17 Distribution Configuration
18
19 Title is 'Privoxy X.Y.ZZ' without the quotes and replacing X.Y.ZZ with the version being packaged (e.g. Privoxy 3.0.19).
20 User sees easy install only
21 Untick all 'Installation Destination' checkboxes to ensure root volume is selected by default (this will result in a warning when building package).
22 No Description (apparently this is only displayed on the Custom Install page)
23
24 N.B. I have chosen not to enforce installation to the boot volume only so as to allow more savvy users to install to a remote-connected Mac's root volume. If you'd prefer to enforce installation only to the target machine boot volume (thereby removing one installation step) you can check the 'System Volume' Installation Destination tickbox.
25
26
27 Distribution Requirements
28
29 Add a Target OS Version check, pass is true, OS X version depends on release being built. Make sure your target version is complete down to the minor version (e.g. 10.5.8 or 10.4.11).
30
31
32 Distibution Actions
33
34 Empty.
35
36
37 Edit Interface
38
39 Background is empty.
40 Copy and paste texts from file 'pkg texts' to the relevant entry box on the left (having selected the 'embedded' radio button on the right). The license can be a File reference to the file LICENSE in the directory containing Privoxy's source code (likely ../current or ../dist).
41
42
43 Pkg Content
44
45 Once the Privoxy build instructions have been completed and the 'constructPkgContent.sh' script has been run successfully, drag and drop the folder 'pkg content' into the Contents pane of Packagemaker.
46
47 No changes need be made to the Choice: pkg content Configuration or Requirements.
48
49 Click the pkg content folder icon on the left.
50
51 Package: pkg content Configuration
52
53 Destination is /
54 No custom location
55 The Package Identifier _MUST_ be: 'org.ijbswa.privoxy.pkg'. This is important since the uninstall.command script references this identifier.
56 Package Version should match the version of Privoxy being built.
57 Restart Action: None
58 Require admin authentication should be ticked.
59 Open the Package Flags window (Package>Package Flags...) and tick Discard Resource Forks.
60
61 Package: pkg content Content
62
63 Highlight 'pkg content' then change the owner to 'root' and the group to 'wheel'. Click 'Apply Recommendations' to set the owner, group and perms of all the files within. The folders and files within /Library need to be manually tweaked to remove the group write permission.
64
65 Package: pkg content Scripts
66
67 Drag and drop the scripts folder to the 'Scripts directory' entry field and set 'absolute' in the cog drop-down to the right of the entry field. Note that there is a bug in PackageMaker such that if you select 'relative to project' then the scripts will not be found nor added to your package at build time.
68
69
70
71 Useful Notes about PackageMaker
72
73 The scripts directory contains two scripts (pre- and post- install), each of which do all that is necessary regardless of whether Privoxy is being installed fresh or over the top of an existing installation.
74
75 Each script has an additional hard link (pre- and post- upgrade). In 10.5+ the upgrade scripts are unused, but for 10.4- the existing installation may be detected and in this case the Installer will look for pre- and post- upgrade scripts in the installation package.
76
77 PackageMaker will bundle _all_ files in your 'pkg content' folder regardless of whether they are listed in your PackageMaker project's Contents pane or not. It is however mandatory that you set the intended ownership and permissions of the installation files, which means that whenever you wish to add or remove a file from the 'pkg content' folder you are forced to delete and re-drag-drop the pkg content element inside your PackageMaker project. Each time you do this you must re-correct the Package Identifier (hence copy it before deleting the element), re-tick 'Discard Resource Forks' in the Package Flags window, then reset the owner and group and Apply Recommendations.
78
79 Apply Recommendations can make mistakes - most notably it will incorrectly give group write permission to LaunchDaemon and StartupItem files and folders. You must untick this box on all those items or else Privoxy will not start when the target machine is booted (and a scary-sounding warning message is displayed). It will however only make these mistakes if the items are NOT present on your build machine when the button is clicked.