design/librarymacinstallerplan.mdwn

   1 ##Plan Mac Installer for GSS EAP and SASL GS2 libraries
   2 ###Introduction:
   3 This document describes Codethink's plan for producing an installer for the Moonshot GSS EAP and SASL GS2 libraries for Mac OS X 10.6 (“Snow Leopard”) and 10.7 (“Lion”).
   4 It describes the goals, activities, deliverables and milestones for the development.
   5 It also gives some background on the intended locations of the files to be installed, system configuration modifications and any other pertinent information. It explains how the installer conforms to Apple’s relevant guidelines to developers.
   6 ###Goals
   7 The primary goal is to allow users to install these initiator libraries on a computer running Mac OS X without needing to build them from source.
   8
   9 Secondary goals are
  10
  11 1. To allow users who are familiar with the autotools tool chain to install, as well as build, the libraries using autotools on a computer running Mac OS X. (This is currently possible for the Cyrus SASL library, but not for the Moonshot GSS EAP library).
  12
  13 2. To automate (as far as possible) and document the process, allowing Moonshot project developers to easily produce installer packages for future versions of these libraries.
  14
  15 ###Deliverables:
  16 1. Changes to files if required to allow the Moonshot GSS EAP library to be installed, as well as built, under Mac OS using autotools.
  17 2. An installer package (or packages) that, when run, will install the necessary files to the required places in the files system. (See Outstanding questions/issues 1).
  18 3. A compressed disk image file containing the installer package(s), which can be mounted to run the installer package. (See Outstanding questions/issues 2)
  19 4. Instructions and scripts for creating the installers and disk images from source. PackageMaker, (the tool provided by Apple to build installer packages - see Ref. 2) does not have a command line interface, and there do not appear to be any freely available alternatives which do, so it will probably not be possibly to automate the production of the installer package(s).
  20
  21 ###Activities and Milestones
  22 1. Build and install the Cyrus SASL Library for Mac OS using autotools to prove this currently works and that it is a valid goal for the Moonshot GSS EAP library. Due Wednesday 16th November.
  23 2. Create an installer package and compressed disk image for the Cyrus SASL Library, with notes on how to achieve the process. Due Friday 18th November.
  24 3. Make the necessary changes to the Moonshot GSS EAP library source and configuration files to build and install it for Mac OS using autotools. Due Friday 25th November.
  25 4. Create an installer package and compressed disk image for the Moonshot GSS EAP library. Due Tuesday 29th November.
  26 5. Create the scripts and instructions. Due Wednesday 30th November.
  27
  28 ###Background information
  29 ####Installer functionality:
  30 There are two parts to the installation:
  31
  32 1. The installer will install library and header files in /usr/local/lib and /usr/local/include, as for the Linux 'make install'.
  33 2: Frameworks: in addition, the installer will install frameworks in sub-directories of /Library/Frameworks on the main drive of the machine. The Cyrus SASL framework will be installed in /Library/Frameworks/SASL2.framework (as in the existing Cyrus SASL 'make install'). The Moonshot GSS EAP framework will be installed in /Library/Frameworks/MoonshotGSS_EAP.framework. The installer will create the .framework directories if they are not already present. The frameworks are wrappers for symlinks to the respective dynamic libraries in /usr/local/lib (libsasl2.dylib and mech_eap.dylib).
  34
  35 If an installation with a lower version number is present, the new installation will be installed, and the /Versions/Current alias changed to refer to the new installation.
  36
  37 If an installation with a higher version number is present, the new installation will terminate with a message explaining why.
  38
  39 If an installation with the same version number as version being installed is present, a message is displayed to the User asking them to confirm whether the existing installation should be overwritten?
  40
  41 The User will not be able to configure the installation to install only some of the components.
  42
  43 The exact text to be used in messages displayed to the user will be specified as part of the implementation of the installer.
  44
  45 The appearance of the installer will not be customized to use special icons and window backgrounds.
  46
  47 Apple's Developer documentation (Ref. 1) states
  48 > public frameworks should be installed at the local level in /Library/Frameworks.
  49 Frameworks installed here are available to all users of the machine.
  50
  51 ####Structure of the Moonshot.framework directory tree.
  52 The Moonshot.framework directory will have the following sub-directory structure, allowing future versions to be installed without breaking applications that rely on an earlier version:
  53
  54     /Headers -> (alias to Versions/Current/include)
  55     /Home -> (alias to Versions/Current)
  56     /Libraries -> (alias to Versions/Current/lib)
  57     /Versions
  58       /1.0.1
  59       /1.0.2
  60       ...
  61       /3.1.2
  62       /Current --> (alias to most recently installed version e.g /Versions/3.1.2)
  63 Each numbered version sub-directory will have the necessary directories from the file system hierarchy e.g.
  64
  65     /etc
  66     /include
  67     /man
  68     /etc
  69     /lib
  70     /sbin
  71     /share
  72       /doc
  73       /xml
  74     /var
  75       /log
  76
  77 ###Package and Component Properties
  78 The Package properties will be
  79
  80     Provider Identifier (Organization): net.ja.moonshot
  81     Target OS (Minimum Target): Mac OS 10.6 Snow Leopard
  82
  83 For each component in the package, properties will be
  84
  85     Destination (To): The appropriate subdirectory of the /Library/Frameworks/Moonshot directory tree
  86     Custom destination consent (Allow custom location): False.
  87     Package identifier: net.ja.moonshot.xxxx (where xxx identifies the individual library)
  88     Package version number: 1 for first release, incremented in future releases
  89     Finalization action (Post-install): None
  90     Administrator-authentication requirement (Require admin authorization): True
  91     Relocatable: False
  92     Downgradeable: False
  93     No pre- or post-installation scripts are planned (but this may change during implementation)
  94     The owner will be root and the group admin. The owner, group, and access permissions of the component files will be determined during implementation.
  95 (See Ref.2 for an explanation of these properties)
  96 ####Delivered components and files
  97 The installer will install the following libraries:
  98 #####Moonshot GSS EAP Library
  99 This library consists of the following files installed in the following locations:
 100 To be completed (See Outstanding questions/issues 3)
 101 <table border="1">
 102 <tr>
 103 <td>/bin</td> <td>list of files in /bin</td>
 104 </tr>
 105 <tr>
 106 <td>/include</td> <td>list of files in /include</td>
 107 </tr>
 108 <tr>
 109 <td>/lib</td><td>list of files in /lib</td>
 110 </tr>
 111 </table>
 112 #####Cyrus SASL Library
 113 This library consists of the following files installed in the following locations:
 114 To be completed (See Outstanding questions/issues 3)
 115
 116 <table border="1">
 117 <tr>
 118 <td>/bin</td> <td>list of files in /bin</td>
 119 </tr>
 120 <tr>
 121 <td>/include</td> <td>list of files in /include</td>
 122 </tr>
 123 <tr>
 124 <td>/lib</td><td>list of files in /lib</td>
 125 </tr>
 126 </table>
 127
 128 #####Dependencies
 129 The installer will not include any dependencies which are present by default in the installed version Mac OS X.
 130
 131 For any dependencies which are not present by default in the installed version Mac OS X, the installer will install the needed versions in the /Library/Frameworks/Moonshot directory tree. It will not attempt to locate or use existing installations of these dependencies. This means that if such existing implementations are uninstalled in the future, the Moonshot libraries will not be broken. This decision has a cost in terms of disk space, but is justified because it a: decreases the complexity of the installation and b: protects the installation from potential failure.
 132
 133 ###Outstanding questions/issues:
 134 1. One package each for "Snow Leopard" and "Lion", or a single package that works for both?
 135 2. One disk image each for "Snow Leopard" and "Lion", or a single disk image containing both packages?
 136 3. For each library, consisting of which files in which sub directories?
 137
 138 ###References:
 139 1. [Mac OS X Developer Library, Framework Programming Guide, Installing Your Framework](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Tasks/InstallingFrameworks.html#//apple_ref/doc/uid/20002261-BBCCFBJA)
 140 2. [Mac OS X Developer Library, PackageMaker User Guide](https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/PackageMakerUserGuide/)