Welcome to i-Installer v2

This is the Help file for i-Installer.app v2, which is an application to install and configure software on Mac OS X.

Table of Contents

• Introduction
• Basic operations
• Installation
• The Menu
• Setting Preferences
• The i-Package Window
• The i-Directory Window (Known Packages)
• What is in a package? How do I create i-Installer v2 i-Packages? (Help created automatically from helper program)
• How do I write (interactive) i-Installer v2 i-Packages scripts?
• How safe is this?
• Performance issues (network access and mirroring)
• Miscellaneous details
• Complex i-Packages (i-Packages with Sets)
• No Warranty

Introduction

i-Installer is a software installation and configuration engine. It can read i-Packages, which are socalled wrappers, directories that to the user normally look as if they are plain files. The reason for developing i-Installer while there is already an Installer.app on Mac OS X can be found here. i-Installer is free software and open source.

Basic operations

Start i-Installer. When you are on a system that has network access, go to the i-Package/Known Packages i-Directory menu. This will open a i-Directory window with amongst others a list of socalled "known packages" (an i-Directory). Select a package you want to use from the top right hand table and open it (e.g. by double-clicking). It will be created from its remote repository in a default location on your disk. The table of contents for the package and the readme for the package (if it exists) will be downloaded. The package will then be opened from its location on disk and displayed in its own i-Package window. The package on disk now only contains a table of contents and a readme, everything else will be downloaded only when necessary.

i-Installer downloads package contents only when needed. There is no need to download an entire 60MB archive of a large package when the only thing you want to do is run the 10kB configure script inside it. Under normal operations, any missing file is downloaded when needed. You can rely on i-Installer never to download anything it does not need. Packages also may work fine without Internet access, just as long as there is no need to download anything to perform the requested function (install & configure, configure or remove). If your package is complete on disk for the requested function, it will operate fine for that function. To use a package on a non-networked system, just make sure it is complete (fattened), which downloads everything that is in the remote repository to your local package on disk, then copy a complete package there by other means (e.g. CD-ROM).

Depending on the contents of a package, it has different capabilities. Packages may contain archives with installable files (data, programs), they may contain configuration scripts, removal scripts and as many extras as needed for those functions.

To install a package, just click the Install or Install & Configure button (the title depends on the availability of a configuration phase). This will offer a choice of parts to install (optionally), run a preparation script (if available), install the contents of any package archive on your system and then run the configuration script (if available). To run just the configuration script, click the Configure button. To run the removal script click the Uninstall button. If a button is dimmed, then the package you have opened does not provide that functionality.

Some packages are combinations of many parts, and they might offer you the option of selecting whatever you want to install, you might not need everything. For instance, a package may contain parts that are only useful for developers and not for users of certain software. If a package had this capability, a separate selector stage will run before any install action. Other packages may do this selection autmaticallyu, depending in the state or your system. E.g. when you have X11 installed, a different version of the software may be installed than when you do not have X11 installed.

If the package requires authenticated access, it will present you with a panel where you can enter an administrator password. As downloading, unarchiving or running scripts may take a lot of time to complete, it might happen that you are presented with a renewal authentication panel as your authentication times out after 5 minutes (Mac OS X standard). For large packages, this might even happen during unarchiving. i-Installer limits authenticated operations to a bare minimum and will only run something authenticated when necessary (opposed to some other installers (not Apple's) which fudge the issue by turning themselves into a fully authenticated program). You can rely on i-Installer only doing something under authentication when it is necessary, most of the operations will be run without system administrator privileges.

More details on package contents can be found here, and on the package window here, but one warning has to be made here. It is only convention that the buttons are called Configure and Uninstall. As they only run a script or program provided by the package, their actual function depends on the package provider. Especially for packages that require authentication from sources you do not trust, it is wise to inspect before you act. (The same is of course true of all other installers, but few of these offer you any inspection capabilities at all, they just ignore this issue and have scripts anyway. A reminder: installing software, especially with system administrator authentication will always be an activity with elevated risk levels).

i-Installer's behaviour is sometimes unfriendly, e.g. you get notified that there is a dependency and i-Installer will not automatically install it for you. The design of the behaviour and the reasons behind it can be read here.

Installation

Drag i-Installer.app to your hard disk. Preferred locations are /Applications/Utilities or ~/Applications (~ is your home directory). You may need to log in and out before Mac OS X recognizes i-Packages and i-Directories as file bundles and lets you open i-Packages by double-clicking.

Plans

• (Low) Multi-packages. A wrapper package like Apple's .mpkg for i-packages.
• (Medium) More native display for inspection (e.g. for images) and an "Inspect With" feature.
• A local packages view based on /Library/i-Installer/Receipts.
• Use /Library/i-Installer/Receipts for the start of the check on updates.
• Combine central receipts with receipts in install location (maybe just a symlink will do).
• A set of default answers to interactive parts of phases would enable fully automated installation. However, given that some questions may depend on external factors, this might not be feasible.
• Optionally remove the package when it is uninstalled
• Have the following additions to a package TOC: requiresreboot and requiresrestart, the latter for installing i-Installer itself.
• When a package is fat, have this visually signalled in some way. Maybe support extra functionality on fat packages like creating a DMG for it.
• If there is a secure way of implementing single-authentication runs (currently, the authentication times out after a default of 5 minutes) I would like to implement it.
• Authenticating proxy support. The problem here is that this means using a completely different part of Apple's framework, to be precise, a part that is n ot available on Mac OS X 10.2, which means that this can only be implemented if 10.2 support is dropped. Or use CURLHandle.

Known Bugs

• Tooltips for some buttons are incorrect.
• (Old, unchecked) checkii2status does not use the foo.updatestatus file yet.
• (Old, unchecked) Close application will bypass the check for thin-at-close.
• (Old, unchecked) Uninstall, a newer version is detected, ignore is chosen, but then th eremove phase is not executed.
• (Old, unchecked) Update does not update the display views (hence these might still display old versions)
• (Old, unchecked) Are there enough checks on the usability of the default save dir and is the feedback OK? E.g. if someone changes the permissions on that directory and newly opened packages cannot be created as a result, do you get the right feedback?
• I have had one report of a Mac OS X 10.3.2 system crash when using the fast network option (parallel downloads). This agrees with my observation that Apple's Foundation framework is less than perfectly stable on this point (using ftp does not work at all in i-Installer, while it should and past Mac OS X prereleases have also seen this unstable behaviour). This is not an i-installer bug but a Mac OS X bug. Nonetheless, I am reporting it here for your information.
• I have had one report of a crash of i-Installer on Mac OS X 10.3.3 where a package was installing, probably downloading, and preferences were changed while this was going on. Probably the Known Packages window was open. As far as I have been able to deduct, the problem is Apple's.
• It is a known problem that sometimes your default i-Directory (known packages) comes up empty. The origin is unclear, but it seems to be some sort of subtle defaults problem (maybe in Apple's kits even) as resetting defaults to factory settings usually clears the problem. This problem may be connected to the previous one, in which case there is a problem with my code.
• I am less than fully satisfied with security. There are some possible (unlikely, but still possible) exploits to get root status if someone already has access to your user account. Note that if they know your password and you are admin, they already have root status, so the exploit is not likely to be used (it only occurs if they have access to your account without knowing your password, e.g. when you have been away from a logged in session). The window of opportunity has been closed as much as possible. Note that this exploit (which I am not going to explain here) is true also for certain other authenticating installers as well. Given that some widely used programs just put your password in the process list for everyone to see, and nobody notices or minds, makes me feel that I am overdoing my concerns. My guess is that if I explain the scenario in detail,people will probably think I am crazy.
• GPG signature process output sometimes seem incomplete (error stream handling, probably) in the Pkg Properties tab.
• Stderr output sometimes gets lost when a process closes. E.g. a prepare script that warns and exits might not display the warning in the appropriate view. This is unfortunate as error messages in reports may also get lost.
• Sometimes sheets do not get displayed and in some cases a warning is displayed about this problem. This is an Apple problem.

Release Notes

• Version 2.75
  • Fixed broken (for Mac OS X 10.2.8) helper programs
• Version 2.74
  • Small change in writing receipts. Remove remaining test code from 2.73 development.
• Version 2.73
  • Provide setting to influence the use of the received environment via Preferences.
• Version 2.72
  • Fixed problem with recognizing file data type on x86.
• Version 2.71
  • Fixed that mailing reports did not work for large reports (Applescript problem) by adding the report as compressed attachment instead.
  • Made sure that the environment gets reset after completion of an action so that choices in previous runs do not get transported to later runs.
  • All universal binaries inside i-Installer were compiled on the Developer Transition System with XCode 2.2 preview 8m624 (for i686) and XCode 1.2 on Mac OS X Server 10.3.9 (for powerpc).
  • Updated gpg to 1.2.7 (universal binary). Note: this is the last version I can use for this kind of setup. gpg 1.4 can only be used when installed on the system.
  • Fallback public domain helper programs taken from Mac OS X 10.2.8 (powerpc) and Mac OS X 10.4.2 8B1072 (i686) and combined into universal binaries.
• Version 2.70
  • Built against Mac OS X 10.2.8 (was 10.2.7) on Mac OS X 10.4.2 for architectures powerpc and i686
• Version 2.69
  • Cosmetic changes (regarding a log message).
• Version 2.68
  • Bugfix: The new TeX i-Package has so many files and parts that parallel execution on many of its operations exceed the standard open file limit (256).
• Version 2.67
  • Bugfix: when opening an locally existing package from a new rmeote location, the info about the remote package is updated.
• Version 2.66
  • Create subdirs before unarchiving part
  • Display full path for files in archive when inspecting (only for real inspect, not cached)
  • Display full path for directory where archive part has been installed (messages)
  • A panel is displayed (next to a console message) when creation of the receipts directory fails.
  • Welcome panel shows version number and build date.
• Version 2.65.2
  • ADA release.
  • Slightly changed layout of i-Directory window.
  • Updated Help
• Version 2.65.1
  • Changed resize behaviour of button in i-Directory window. No code has changed, so I let this qualify as a minor update.
• Version 2.65.0
  • Changed startup splash screen
  • Changed i-Directory window
• Version 2.64.0
  • Added the fragger script to the application resources for package building.
• Version 2.63.0
  • Compiled with XCode 1.2
  • Added my own copy of the Mac::PropertyList module to the program so everything to build packages is available.
• Version 2.62.0
  • Changed iibless script so it can work without a GPG keyid
  • Fixed buglet where the action progress bar would not always disappear at the end of an action sequence. There may be some situations left where this could happen (because of the action performing design, which has some advantages but also disadvantages), but I have not seen them yet.
• Version 2.61.0
  • Changed download information display (now includes size). Accidentally released.
• Version 2.60.0
  • Buglet fix: mail report also recreated report. That can be time consuming. Maybe it did not even work.
  • Bug fix: I was trying to write in a nonmutable NSDictionary.
• Version 2.59.0
  • Bug fix: the program did not work on Mac OS X 10.2
• Version 2.58.0
  • Implemented the system-wide receipts location. Old receipts are not searched for and moved (yet). Rearranged what goes in the install and what in the custom property list. Old style receipts are searched for in the default places and translated into the new location /Library/i-Installer/Receipts.
• Version 2.57.1
  • Bug fix. Save install info not only after unarchive but also after configuration as we might have changed things. This demotes the set-info in Custom.plist to temporary only. The result is that at the end of a long configure phase (like TeX's) you will need to re-enter your password (as this install info might have to be written with authentication).
• Version 2.56.0
  • Added II2USER and II2AUTHENTICATED (YES/NO) to environment variables given to phases
  • Temporary .l file removed in i-Package (iibless forgot to clean it up)
• Version 2.55.1
  • Added progress bar control to phase scripts.
• Version 2.54.0
  • Added progress bars for downloads and actions.
  • Packages generated/updated with iibless now contain output size information for the unarchiving process that drive the action progress bar.
  • The old dynamic display preference has been replaced by a new one so that everybody using this version will nog get dynamic displays.
• Version 2.53.0
  • Bug fix: report window does not appear on menu action.
  • Bug fix: dynamic display of windows did not activate the Readme window on initial remote opening of an i-Package.
• Version 2.52.0
  • Recompile using the sources from SourceForge.
• Version 2.51.0
  • Added Fast Network preference setting. With this setting you can control parallel versus serial downloads.
• Version 2.50.0
  • Fixed bug: missing directory was not created when user chose Ignore on missing dependencies (and possibly update check).
  • First release from Sourceforge CVS repository
• Version 2.49.1.
  • 2.48.0 was broken and would not install anything (I missed a compiler warning) so 2.49.0 was release quickly as soon as I found out. This is 2.49.1 and the only difference is this release note.
• Version 2.48.0.
  • Changed dependency checking preference settings (and actually use the setting, which so far was not the case).
• Version 2.47.0.
  • Fixed small bug in 'selected' handling. Selection behaved cumulatively, which is not what was intended.
• Version 2.46.0.
  • Fixed small bug in 'available' checking, affecting read-only/locked operations.
• Version 2.45.0.
  • Re-read remote version after a change of URL
  • Use the installed package table of contents preferably for information on sets.
  • (High) Add 'available' as a status for sets. A set is available when it is either in the package or when it can be downloaded (writable location, not locked, network access permitted). Having this enables packages not to offer certain sets, based on their availability.
  • Thin at close only offered when package writable and not locked.
• Version 2.44.0.
  • Dependency checking moved to after the selection stage, this required a complete rewrite of the various dependency (files, up-to-dateness) handlings which had become rather spaghetti-like
  • Dependency checking now honours the possibility for a package to restrict dependencies to a certain selector set.
  • Made code here and there somewhat more forgiving (check if array has members before addressing them). This may mask programmer problems, so warnings should still be added.
  • Most Alert sheets have been converted to the internal sheet queue handler.
• Version 2.43.0.
  • Added execution bit double check to package builder script
  • Changed message on dependency failure somewhat. Still not satisfied here.
• Version 2.42.0.
  • Documentation adapted.
• Version 2.41.0.
  • Rewritten dependency functionality
• Version 2.40.0.
  • Some small bug fixes, display improvements
  • Use system tools when available and possible
• Version 2.39.0.
  • Added BSD license everywhere
• Version 2.38.0.
  • iibless can produce old-style packages
• Version 2.37.0.
  • Some small bug fixes
  • Package dependency checking disabled (needs a rewrite)
• Version 2.36.0.
  • Internal experimental version
• Version 2.35.0.
  • Changed (probably broken) code in preferences re: default save directory and tilde home directory expansion.
  • Made sure GPG check of Table of Contents is performed on opening of package (preference dependent).
  • Made sure that files get an extra intergity MD5 check when GPG is turned on.
  • Made sure all downloads are performed in series instead of in parallel.
  • Made dynamic tab view behaviour preference dependent.
  • Released as beta to a wider audience.
• Version 2.34.0.
  • Fixed foo.stamp and Custom.plist handling.
  • Changed to pgp.mit.edu as default key server for GPG.
  • Released as beta to a wider audience.
  • Known bugs:
    I saw i-Installer hang once when I selected activated the app by selecting the Activity tab and then clicking the Activity tab again. I had to force-quit the application. This seems like a Cocoa framework problem.
• Version 2.33.0.
  • Replaced all internal binaries for support programs with Jaguar versions from 2.27.0
  • Released as beta.
• Version 2.32.0.
  • Renamed 'remove' to 'uninstall' in UI
  • Implemented missing code in i-Installer which enable the unsetting of variables from scripts
  • Implemented warning (and a better reset functionality) for forced resetting of incompatible defaults.
  • Released as beta.
• Version 2.31.0.
  • Added support to give package different subdirs for different parts of the archive.
  • Fixed lost connection between abort button and program (abort process did not work)
  • Released as beta.
• Version 2.30.0.
  • Released as beta.
• Version 2.29.0.
  • Basic implementation of communication from prepare to unarchive and configure. Released as beta.
• Version 2.28.0.
  • A complete overhaul of the user interface. Released as beta.
• Version 2.27.0.
  • Repaired bug that made i-Installer not robust with respect to directory names with spaces and such in them.
• Version 2.26.0.
  • Added fragmented archives handling.
• Version 2.25.0.
  • Added ZIP-file handling
  • Discovered but did not solve crasher bug when remote i-Package part is unavailable (unlikely problem, will do this later).
• Version 2.24.0.
  • Known Packages (i-Directory) window sorts on name by default.
• Version 2.23.0.
  • Changed the default i-Directory descend level to 1. First start will therefore reset your defaults.
  • Changed names of buttons on Properties tab to improve the intuitiveness.
  • Updated a few Help items.
• Version 2.22.0.
  • Let the i-Directory class obey the max descend level from preferences.
• Version 2.21.0.
  • i-Directories (.iid files either remote or local) have gotten 'document' status. It is therefore possible to open multiple i-Directories (known packages).
  • Stuff opened from i-Directories can now be addressed relatively. This opens up the possibility of shipping a CD or image with a relative i-Directory to be opened.
  • Both improvements must be considered a dirty hack because of the nature of Apple's frameworks (or my misunderstanding of those frameworks) with respect to 'documents' that are actually not local file bundles (like remote i-Directories which do not have a local counterpart like remote i-Packages do).
• Version 2.20.1.
  • Added two kinds of messages when thinning a package (one per removed file and one final). This is a code change, but since it is only messaging this release will only have an increased sub-minor version number.
• Version 2.20.0.
  • Remove scripts are not guarantueed to remove the installation (e.. after user interaction nothing can happen, but the script will finish succesfully). The removal of the install time stamp file is in that case a mistake. A mechanism has been added so that remove scripts can communicate back that the time stamp file should not be removed.
• Version 2.19.0.
  • Fixed bug where the "Set" button for the install location remained active even when th epackage was not relocatable.
• Version 2.18.0.
  • Fixed bug where the .updatestatus file was being included in the TOC, breaking GPG checking.
• Version 2.17.0.
  • Added Make a PayPal donation... menu item to the i-Installer menu ;-)
• Version 2.16.0.
  • Create default save directory when it does not exist yet. It's parent should exist.
  • Basic report-through-mail functionality added (Menu item: Mail Report)
  • Set umask to something reasonable.
• Version 2.15.1.
  • Cosmetic change in startup splash screen.
• Version 2.15.0.
  • Added support for new-style upload protocol protection. This protocol will prevent the HTTP servers to be flooded with "file unavailable" messages.
• Version 2.14.0.
  • Added package timestamp environment variables to subprocess. Main reason: these end up in a report.
• Version 2.13.0.
  • Inspect view is updated after update.
• Version 2.12.0.
  • Archive is extracted with -p flag for gnutar, preserving as much as possible from the file statuses in the archive.
• Version 2.11.0.
  • Unreleased.
• Version 2.10.0.
  • Fixed lagging button status and text update for the Inspect button when lock status changes.
  • Note: There is still some behaviour that needs to be ironed out. I suspect that Inspect button deactivation during activities is still not entirely implemented correctly. But I rather fix the real cause ( alack of parallelism support) than hack another fix.
  • Fixed the situation with a sheet could appear before the window is activated (e.g. when the info RTF file is missing and the package cannot download it because the package is locked).
• Version 2.9.0.
  • Added warning panel when local package cannot be created.
  • Removed p flag from unarchiving. Unarchiving now writes files as root or user, depending on authentication status. If p is important for a package, it shoul dbe handled in a configuration script anyway.
• Version 2.8.0.
  • Locking of a package added.
  • Changed behaviour of dependencies when dependent package cannot be found (ignore depndencies when this happens)
• Version 2.7.0.
  • User interface change. The check remote version is now a button in the Properties tab. The menu item for checking the remote version has been removed.
• Version 2.6.0.
  • Pevious bug fix produced a crash on fattening. Ugh! Repaired.
• Version 2.5.0.
  • Fixed a bug where a file descriptor leak could occur while fattening.
• Version 2.4.0.
  • Fixed a bug in Known Packages (i-Directories) where the i-Directory was always reset to the installed default.
  • Moving the default save directory will also move a Finder .DS_Store file (if available) to make removal of the old directory possible (if furthermore empty).
• Version 2.3.0.
  • The cli program checkii2status now also reports how much of a package has been updated
  • There is a new menu item called "Open Updated...". This checks all packages in your default save directory and opens them when they have been updated. The size of the changes is written in the message view of the opened package. This is potentially a slow foreground operation, hence no option for doing this at launch will be available.
  • When the i-Directory location is changed in Preferences, an already open Known Packages window will be updated immediately.
  • Compiler optimizations turned on.
• Version 2.2.0.
  • Add preference for displaying only unique package names in Known Packages
  • Buglet fix: inspect button is updated according to status of select item in file table
  • Open package with Inspect window.
  • Give user the option to install/configure package when the remote is being updated and the local is complete.
  • A change of default save directory will move the existing i-packages from the old to the new location.
• Version 2.1.0.
  • Bug fix: the install directory was not created when an install followed an ignore of a remotely available different version.
  • Bug fix: running install/configure/remove when the remote package was being updated was not supported (missing button in sheet).
• Version 2.0.0.
  • Finished processes are not completely finished if the activity window is open and there are still dependent tasks running. Closing and re-opening the Activity window makes them disappear from the list.
  • When running under certain versions of Mac OS X 10.1 (I have a reliable report about 10.1.4 Server) the downloading of files may hang on a regular basis. There is nothing I can do about that as it is deep inside the 10.1 Frameworks where this happens. I do not have any reports of this happening with Mac OS X 10.1.5.
  • I have one report of a putenv() error/warning message when installing i-Installer from it's i-Package without authentication (note: this is the default mode of the i-Package). The message is probably harmless, but if you encounter this, please contact me and help me locate the problem.

No Warranty

Version numbering

The version number will change according to the following rules:

• x.y.z → x.y.z++ No code change, code documentation and Help only
• x.y.z → x.y++.0 Code change, no backward incompatibilities with existing i-Packages
• x.y.z → x++.0.0 Code change, incompatibilities introduced