Repository by liaoxiuli

VIEWS: 45 PAGES: 10

									Creating a Source Repository for use with
Installer.app
From IPod touch Fans Wiki

Jump to:navigation, search

Installer.app, like Macintosh OS X, reads external poperties, such as sources for package
downloads, from an Apple Property List (commonly known as a plist). These property
lists can be represented in either XML or binary format. A sample can be viewed in the
sample below.

When creating a repository, it is generally recommended that you use Apple’s property
list editor, although any plain text editor, such as Microsoft’s Notepad, will work just as
well. One common source of errors is using a Rich Text Editor, such as Microsoft’s
Wordpad or Apple’s TextEdit.

Contents
[hide]

        1 Sample Repository
        2 Building A Repository
            o 2.1 Header Information
            o 2.2 Info
            o 2.3 Package Information
            o 2.4 Scripts
        3 Common Script Commands
            o 3.1 CopyPath() and RemovePath()
            o 3.2 Other Common Commands
            o 3.3 If / IfNot
        4 More on ~/
        5 More on MD5
        6 Download this page in .doc format



[edit] Sample Repository
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple
Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

 <dict>
   <key>info</key>
   <dict>
     <key>name</key>
     <string>iPod Touch Fans</string>
     <key>description</key>
     <string>The Official iPodTouchFans Repository!</string>
     <key>maintainer</key>
     <string>Skylar</string>
     <key>contact</key>
     <string>TouchRepo@gmail.com</string>
     <key>url</key>
     <string>http://www.ipodtouchfans.com</string>
     <key>category</key>
     <string>iPodTouchFans.com</string>
   </dict>
   <key>packages</key>
   <array>
     <dict>
       <key>bundleIdentifier</key>
       <string>com.Larzhog.iZoo</string>
       <key>name</key>
       <string>iZoo</string>
       <key>version</key>
       <string>1.1-3</string>
       <key>location</key>
       <string>http://www.touchrepo.com/Apps/Games/iZoo.zip</string>
       <key>category</key>
       <string>Games</string>
       <key>size</key>
       <string>1276224</string>
       <key>hash</key>
       <string>2c250d07856eb73d7215d5a27e99fe4f</string>
       <key>url</key>
       <string>http://www.casey.org.uk/ipod_izoo/index.html</string>
       <key>maintainer</key>
       <string>Lazrhog</string>
       <key>contact</key>
       <string>izoo@casey.org.uk</string>
       <key>description</key>
       <string>Fun game in the style of Zoo Keeper/Bejeweled. (Now
1.1.3 compatible!)</string>
       <key>date</key>
       <string>1201815661</string>
       <key>scripts</key>
       <dict>
          <key>install</key>
          <array>
            <array>
              <string>CopyPath</string>
              <string>iZoo.app/</string>
              <string>/Applications/iZoo.app</string>
            </array>
          </array>
          <key>uninstall</key>
          <array>
            <array>
              <string>RemovePath</string>
              <string>/Applications/iZoo.app</string>
            </array>
         </array>
       </dict>
     </dict>
   </array>
 </dict>

</plist>

[edit] Building A Repository
[edit] Header Information

The basic header information is the standard for Apple plists. You should not change this.


<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple
Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

 <dict>
 ...
 ...
 ...
 </dict>

</plist>

[edit] Info

Within this plist, you should create a dictionary with two keys. The first of which is the
info key. This is where Installer gets all the information about your repository.

   <key>info</key>
   <dict>
     <key>name</key>
     <string>iPod Touch Fans</string>
     <key>description</key>
     <string>The Official iPodTouchFans Repository!</string>
     <key>maintainer</key>
     <string>Skylar</string>
     <key>contact</key>
     <string>TouchRepo@gmail.com</string>
     <key>url</key>
     <string>http://www.ipodtouchfans.com</string>
     <key>category</key>
     <string>iPodTouchFans.com</string>
   </dict>
   Key      Optional                               Description
                      This is the category in which you want you source to appear in
category   No.
                      Installer's Sources List.
                      This is the name you want Installer to display for your source in its
name       No.
                      Sources List.
                      This is the description you want Installer to display for your source
description Yes.
                      in its Sources List.
maintainer No.        Your name or your company's name.
                      The email at where you want to receive email form users about
contact    No.
                      your source
                      This is the link you want to load when the user taps the "More Info"
url        Yes.
                      tab about your source.

[edit] Package Information

This is the second key in your main dictionary, in which you tell Installer about each
specific package in your repository. Each package should be set up as a separate
dictionary within an array.

   <key>packages</key>
   <array>
     <dict>
       <key>bundleIdentifier</key>
       <string>com.Larzhog.iZoo</string>
       <key>name</key>
       <string>iZoo</string>
       <key>version</key>
       <string>1.1-3</string>
       <key>location</key>
       <string>http://www.touchrepo.com/Apps/Games/iZoo.zip</string>
       <key>category</key>
       <string>Games</string>
       <key>size</key>
       <string>1276224</string>
       <key>hash</key>
       <string>2c250d07856eb73d7215d5a27e99fe4f</string>
       <key>url</key>
       <string>http://www.casey.org.uk/ipod_izoo/index.html</string>
       <key>maintainer</key>
       <string>Lazrhog</string>
       <key>contact</key>
       <string>izoo@casey.org.uk</string>
       <key>description</key>
       <string>Fun game in the style of Zoo Keeper/Bejeweled. (Now
1.1.3 compatible!)</string>
       <key>date</key>
       <string>1201815661</string>
       <key>scripts</key>
       <dict>
         <key>install</key>
         <array>
            <array>
              <string>CopyPath</string>
              <string>iZoo.app/</string>
              <string>/Applications/iZoo.app</string>
            </array>
         </array>
         <key>uninstall</key>
         <array>
            <array>
              <string>RemovePath</string>
              <string>/Applications/iZoo.app</string>
            </array>
         </array>
       </dict>
     </dict>
   </array>
      Key                                        Description
                 This is how Installer knows what your package is. DO NOT CHANGE
bundleIdentifier
                 THIS once you have it set, or else you will break updates.
                 This is the category in which your package appears; ie Games. Books,
category
                 Themes, etc.
name             This is the actual name of your package.
description      The package description that the user sees.
                 Your package's current version number. Any change to this causes your
version
                 package to appear as an update.
                 This is the actual location of your package; the specific place from
location
                 where Installer will download your package.
                 The name of whoever maintains the package. It's a good idea to put the
maintainer
                 package creator here.
                 This is the contact email of whoever created the package. Use yours
contact
                 from the info key if you do not have the creator's email.
                 This is the exact size of your package in bits. If you are one bit off,
size
                 Installer will refuse the download.
sponsor          Creates a tag at where your Sponsor's name will appear.
                 This is the md5 checksum of your package. If this does not match your
hash
                 package's size exactly, Installer will refuse the download.
                 This is the standard UNIX timestamp. It is the number of seconds since
date
                 1970.
                 This is where you put the preflight, install, upgrade, postflight, and
scripts
                 uninstall scripts.
                 The link that is loaded when the user taps the "More Info" tab in
url
                 Installer's about section for your package.

[edit] Scripts

Scripts are the instructions that Installer uses to actually install or uninstall your package.
There are five types of scripts you can use, each performing their own special functions.
Scripts should appear in a subdictionary of its package directly attached to the "scripts"
key.

Each script should appear as a key of this subdictionary with its commands forming an
array. Each command should appear as a separate array of strings within the script's
master array.

      <key>scripts</key>
       <dict>
         <key>install</key>
         <array>
           <array>
              <string>CopyPath</string>
              <string>iZoo.app/</string>
              <string>/Applications/iZoo.app</string>
           </array>
           <array>
              <string>Notice</string>
              <string>This is how you create a second command in a
script</string>
           </array>
           <array>
              <string>Notice</string>
              <string>This is another command. Notice how each command
is listed in a subarray of the script's master array.<string>
           </array>
         </array>
         <key>uninstall</key>
         <array>
           <array>
              <string>RemovePath</string>
              <string>/Applications/iZoo.app</string>
           </array>
         </array>
       </dict>
  Script                                            Usage
install    Used for Installing the actual package.
uninstall Used for uninstalling the package.
           Used when upgrading requires special instructions. If there is no uninstall
upgrade
           script, Installer uses the install script when upgrading.
           This script runs before the install process. This is handy for performing checks
preflight as to whether Install should install the package or abort the package. Also this
           can be used to ready the iPhone/iPod for install.
           This script runs after install. It is handy for such things as verifying proper
postflight install, cleaning up install, setting certain privileges, or anything else that must
           occur after installing a package.

The only script that is necessary is the install script. If you leave out the uninstall script,
Installer will only give the user the option to install or reinstall (as seen in the Uninstall
Section of Installer when you select to uninstall Installer).
[edit] Common Script Commands
[edit] CopyPath() and RemovePath()

The most common commands you will use are the CopyPath(oldPath, newPath) and the
RemovePath(path) commands. These will be expressed as

              <array>
                <string>CopyPath</string>
                <string>iZoo.app/</string>
                <string>/Applications/iZoo.app</string>
              </array>

and

              <array>
                <string>RemovePath</string>
                <string>/Applications/iZoo.app</string>
              </array>

respectively. You will find yourself using both during both the install and uninstall phase.

In the CopyPath command, the first string (the oldPath) represents the directory within
your package where all your files are. DO NOT put a slash at the beginning of this string.
The second path (newPath) is the exact location of where you would like the package to
be saved on the iPhone/iPod. Notice that this path has the slash at the beginning of the
string. This is absolutely necessary, else your package will be installed into a temporary
directory and will be deleted upon reboot. Make sure to put the EXACT location in here.
CopyPath will overwrite files by default, so again, make sure your newPath is exactly
correct. Finally, do not use shortcuts such as an expanding tilde to represent the user's
home directory.

Also, note that CopyPath() can be used for copying files withing the iPhone/iPod itself.
This is handy for back up purposes. In this case, you will want the oldPath string to begin
with a slash. The oldPath MUST also have the exact address of the fil or directory that
you want to copy.

In the RemovePath, you will need to specify the exact location of the file or directory that
you want to remove. Know that removing a file or directory is a permanent. Be careful

[edit] Other Common Commands

Remember that each command is an array of strings. Look at CopyPath and RemovePath
if you are not sure how to create an array out of each command.

       Command                                       What It Does
AbortOperation(string)       This will make Installer both abort the install process and
                           display a message telling the user why. Example: "This
                           package requires firmware version 1.1.2 to be installed
                           first."
                           Adds the named url to Installer's Sources List. Don't forget
AddSource(url)             the http://. Also, make sure you have your capitalization
                           absolutely correct.
                           Runs a Terminal command. Useful for things like chmod,
Exec(terminalCommand)
                           chown, etc.
InstallApp(nameOfApp)      Installs your Application. Example: InstallApp(iZoo.app)
LinkPath(oldPath, newPath) Links the two paths.
MovePath(oldPath,
                           Moves files from one location to another
newPath)
Notice(string)             Displays a pop message while Installing
                           Removes the source with the specified url from Installer's
RemoveSource(url)
                           Sources List.
                           Sets the status of the install process. Useful for lengthy
SetStatus
                           installs or adding zazz to you install.
UninstallApp(NameOfApp) Uninstalls your Application. Example: Uninstall(iZoo.app)

[edit] If / IfNot

If(condition[array], action[array]) Use this to check for specific conditions and have
Installer react accordingly. Example

           <array>
             <string>IfNot</string>
             <array>
                <array>
                  <string>FirmwareVersionIs</string>
                  <array>
                    <string>1.1.2</string>
                  </array>
                </array>
             </array>
             <array>
                <array>
                  <string>AbortOperation</string>
                  <string>Firmware 1.1.2 is required to update to
1.1.3.</string>
                </array>
             </array>
           </array>

IfNot(condition[array], action[array]) Uses this to check for specific conditions and have
Installer react accordingly. Example

              <array>
                <string>IfNot</string>
             <array>
                <array>
                  <string>InstalledPackage</string>
                  <string>com.natetrue.iphone.iphone_binkit</string>
                </array>
             </array>
             <array>
                <array>
                  <string>AbortOperation</string>
                  <string>You must install the BSD Subsystem package
first.</string>
                </array>
             </array>
           </array>

Some common things to check with If / IfNot

                           Command                                  What It Does
                                                              Checks to see whether or
InstalledPackages(bundleIdentifierFromInfoPlistOfApplication) not an application is
                                                              installed.
                                                              Checks to see whether a
ExistsPath(path)                                              specific file or directory
                                                              exists.
                                                              Checks the iPhone / iPod
FirmwareVersionIs(arrayOfFirmwaresTocheck)
                                                              firmware.

[edit] More on ~/
Installer 3.0 and later has the ability to use expanding tildes in its paths. This is to
accomodate the fact that some users are using firmware 1.1.2 or earlier, and some people
are using firmware 1.1.3 or later. After 1.1.3 was released, Mobile OS X starting running
the user as "mobile" instead of "root." While this is great for security purposes, it makes
install a headache. Repository Managers would have to have to check firmware version
then install to the right location, creating more work and taking up needless space
(causing giant repositories). In order to prevent these two options, Installer now lets
Repository Managers use one simply script for install and uninstall. Installer
automatically locates the correct directory.

As the ~ feature is only available using Installer 3.0 or later, it is not recommended that
you use it yet, as not everybody has yet updated to Installer 3.0.

[edit] More on MD5
The md5 is a checksum. That is, it is the encrypted size of the package. In this case, it is
32 bit encryption. Installer uses this to verify each package it downloads. If it does not
match, then Installer will reject the package. Note that the string representing the
checksum must be written entirely in numbers and lowercase letters. Uppercase has been
known to cause Installer the reject the download.

Having Installer verify the package is to ensure that your package has not been tainted. It
is also one more step to ensure the legitimacy of your package.

While currently not necessary, Installer will start making this tag mandatory. That is, it
will not download packages without a hash tag. It's a good idea to start implementing this
as soon as possible to avoid obsolescence.

There are several tools you can use to find out the md5 of your package. In Linux, you
can use the md5 tool built into Terminal. If you don't have it, then open up terminal and
type

sudo apt-get install md5sum

On a Mac, you can download and use MD5.app, a free application distributed by Eternal
Storms Software. http://www.eternalstorms.at/md5/index.html

On A Windows Platform Download http://www.pc-
tools.net/files/win32/freeware/md5sums-1.2.zip and then just drop the zip file over the
md5sums.exe file

								
To top