## Packaging Products for Installation on a GlobalPC

This document outlines the creation of packages to be installed with the Software Manager on the GlobalPC. This document essentially describes how to use the pack.pl Perl script to create one or more .PAK files; these files, when downloaded to the GlobalPC, can be unpacked via the Software Manager application.

## The Software Manager (How Installation Works)

The GlobalPC has a software manager built in that allows for installation and removal of add-on software. The software manager application can be reached through the "Computer Utilities" folder by opening the "Add/Remove Software" item.

Software packages are added and removed in a single operation—that is, there is nothing in the user interface or the software manager that indicates the contents or structure of what is being installed or removed, and users can not install or remove individual components of a package. This is true even if the package contains multiple applications, as is the case with the "Card Games" package available as an add-on from MyTurn.com.

When software is added to the GlobalPC through the software manager, the user is shown only the title of the package. The package is actually a file ending in the extension .PAK, but the filename of that file is never shown to the user. Similarly, the user never sees the detailed list of files being added to or removed from their system. Instead, the software manager interrogates the .PAK file for the relevant information.

When the .PAK file is unpacked to the machine, the software manager knows inherently where to put the extracted files. The destinations of the files are determined at the time that the .PAK file is created.

## Creating the .PAK Files

Software packages are files that end in the .PAK extension. These files are created with a Perl script called pack.pl, available from MyTurn.com. In the future, a more automated facility for creating .PAK files will exist, but for now you must obtain the script and run it on a system that has Perl installed.

The script first opens up a list file and then builds the .PAK file using information specified in that list file. The list file is a simple text file describing the contents and metadata of the package, and you can create it using any ASCII text editor. The structure of the file is detailed in a section below.

To create a package, you must first create all the files you want to put into the package, then follow these three steps:

1. Put your files into the appropriate directory structure.
2. Create the list file.
3. Run pack.pl

### Setting Up Directories and Files

In order to create a package, you must know the location of all the files that will go into the package. The files can be located anywhere on a single disk, but it is easiest if you put all the files into a tree within a given directory. Also, it is best if you can put the files into a directory structure that mirrors the directory structure of the GlobalPC.

The pack.pl script looks in a root directory which is specified in the list file, and all your files for the package have to be located relative to that root directory. Because packages should have only files that are related to each other, typically all the files can and should be in the same subtree. Although it is possible to identify files that are located all over your hard disk, that is much more difficult and is discouraged.

Even if your package is only a single file, you must create a .PAK package for it if you want it manageable by the software manager application.

### MultiPak Packages

If you want to have packages that are both individually available and available as bundles, you will want to create multipak packages for the bundles.

For example, if you create and distribute clip art, you might create one package of Valentine's Day clip art, one package of Independence Day clip art, and one package of Halloween clip art. To do this, you create one .PAK file for each of these packages. If you then want to special-offer all three as a single "Holiday Clip Art" bundle, you can create a holiday multipak .PAK file that contains each of the three other .PAK files.

To create a multipak file, you specify some additional information in the list file. Multipaks can only contain regular .PAK packages; they may not contain other multipaks.

When the software manager installs a multipak, what it really does is create a temporary directory on the hard disk, unpack the multipak into the temporary directory, install the packages individually, then remove the temporary directory and the files within it. When it removes the multipak, it simply removes all the packages that were in it. Throughout all this activity, the only thing the user sees is the name of the multipak (e.g., "Holiday Clip Art"). The user is not able to remove individual packages that were installed as part of a multipak.

If a package was previously installed individually and is now being installed again as part of a multipak, the user will be asked if they want to re-install the package. If they opt to re-install the package as part of the multipak, the package disappears from their installed software listing, and it becomes part of the multipak. Similarly, if a package was initially installed as part of a multipak and is being re-installed individually, the user will be given the option to re-install or leave it as is. If the user opts to re-install the package, it will show up as an individual package and will not be removed if the user later removes the multipak.

The way the software manager checks whether a package is already installed is by the package's "name" attribute (see the list file instructions below). For this reason, it is important to ensure that your package names are unique; you should put some additional identifier in the package name. For example, instead of calling your clip art bundle "Holiday Clip Art," you might call it "Holiday Clip Art from Late Nite Munchies Studio."

### Creating the List File

Every configurable attribute of a package is specified in the list file. The list file first defines some metadata for the package such as the package's name, version, author, etc. Then it lists the files to be included in the package. An example list file is shown below:

        # Example List File for a clip art file
        # Lines beginning with # are ignored by pack.pl
        Type = geos data
        Name = Valentine's Day Clip Art
        Version = 1.0
        Author = Late Nite Munchies Studio
        System = 3.0
        Installpath = document\clip_art
        Rootdir = C:\lnms\gpc_art\clip_art\valentin

        # Here is where the files are listed
        *.000

The exact structure of the file is flexible, and it is not required to put all the metadata at the top and all the files at the bottom. Only the Name and the Type of the package must be defined before the file list; other information is optional. If left blank, directory entries will be set to the current working directory (the directory in which the script is being run).

All of the metadata attributes defined in the list file are stored in the .PAK file's header unless otherwise specified in the table below. This table contains all the attributes that may be specified in the metadata, and any specific instructions for each attribute.

Attribute | Possible Values | Description
Type | GEOS DOS System MultiPak Geos Data Font Print Driver | Type of the package being built. The types and their meanings are described in a table in a following section.
Name | Any string | The name of the package. This is the name displayed by the software manager when installing and removing the package. It is also used to create the package filename.
Version | major.minor | Version of the software being packed.
Author | Any string | Author/creator of software.
System | major.minor | Minimum version of system required to support software. (Currently, this should always be 3.0)
Note | Any string | Any note you care to add.
Rootdir | Any DOS path | Points to the top directory where all of the files you wish to include in the package are located. This information is not stored in the package header; it is only used to build the package.
Mainprog | File name of the product's main geode | Indicates which .GEO file is the main program. This is only valid for types GEOS application and DOS application.
Readme | Filename of readme | A simple text readme file that may be displayed by the software manager if it exists.
Installpath | Any DOS path | This value is appended to the default install path to result in the final destination of the files to be installed. Additional notes: For GEOS and DOS applications, if this is blank or missing, the name field will be used instead. For MultiPak and Print Driver packages, this should be left blank. For Font packages, this name should be something appropriate for the font pack. For Data File packages, this should be part of the standard path; e.g., document\clip_art for a clip art package.
Linkpath | Any DOS path or standard path in the path tail format as specified for INI file settings | Tells the software manager where to create a symbolic link to the installed Mainprog geode or DOS application. If this value is a DOS path, it is appended to the default link path to result in the final link path. This is only useful for GEOS and DOS applications. If the value is the INI file format (standard path, path tail), then it overrides the default link path and allows the package to specify a location anywhere in the GEOS tree in which to create the link. Ideally, this should only be one of the standard directories under the SP_APPLICATION directory.
Inifile | Path to special INI modification file | Specifies the location of a file containing directives for adding or removing keys from the system INI file at install time. This feature is used only by the system update mechanism.
SetupGeos | Path to custom setup program | A geode to be launched after the package has been installed. This is useful for packages which require a setup application be run before the application may be executed.

### Package Types

Only the Name and Type fields are required in a list file. The Name identifies the package, and the Type field specifies the type of package being created. There are several types of packages, and each type implies certain default directories and characteristics. The table below shows the type names and the types of packages they represent. In the definition of the type in the list file, the case, spacing, and punctuation are ignored. (E.g., "geos-data" is the same as "GEOSdata".)

Type | Description
GEOS | Any GEOS application.
DOS | Any DOS application. Creation of DOS applications for deployment on the GlobalPC is covered under a separate document; you will need to read that document to ensure that your DOS application can be deployed and run on a GlobalPC.
System | A system update. This is not used by the software manager and should not be specified in your list file.
MultiPak | A package containing only other packages. This allows multiple packages to be installed at one time. Ssub-packages of a MultiPak type can not themselves be MultiPak type.
Geos Data | Any miscellaneous GEOS files such as clip art, dictionaries, thesaurus, crossword puzzles, etc.
Font | GEOS font files
Print Driver | GEOS print drivers.

If you are not sure what type your package should be, you should specify it as Geos Data.

By specifying the type of the package, you are implicitly giving instructions to the software manager on where to install the files and where to create any symbolic links, if they are applicable. The table below indicates the default installation directories for the various types, as well as the INI file setting that may modify the default directory.

Type | Default Top Installation Directory | INI File Setting
GEOS | SP_TOP\..\GEOSAPPS | geosappdir
DOS | SP_TOP\..\DOSAPPS | dosappdir
MultiPak | SP_TEMP_FILES\* (see description below) | multipakdir
GEOS Data | SP_TOP | dataFilesDir
Font | SP_TOP\..\GEOSAPPS | fontdir
Print Driver | SP_PRINTER_DRIVERS | printDriverDir

In the table, SP_TOP, SP_TEMP_FILES, and SP_PRINTER_DRIVERS are "standard paths" defined by the GlobalPC's operating system. Typically, SP_TOP will refer to C:\globalpc\. This means that the default installation directory for type GEOS would be C:\geosapps\.

For the Multipak type, the .PAK packages in the multipak are extracted to a custom-created subdirectory in the temporary directory, then the files and the custom subdirectory are deleted after the installation is completed.

The Type also indicates to the software manager where, if anywhere, it should create a symbolic link to the application. This is appropriate only for DOS and GEOS applications, and the value may be modified by setting the list file attribute Linkpath.

Type | Default Symbolic Link Location
GEOS | SP_APPLICATION\Play and Learn
DOS | SP_APPLICATION\Play and Learn
Other Types | No default symbolic link is created.

### Specifying Files to be Packed

After the attributes have been specified in the list file, you must indicate which files are to be inserted into the .PAK file. This is done by a simple listing of file names, one on each line.

Special rules apply when specifying the file list:

- All file names and paths in the list file are appended to the RootDir attribute
- If the RootDir is not specified, it defaults to the current directory in which the pack.pl script is being run
- If no file name is given, the default is *.*
- Wildcard characters are accepted. * means zero or more of any character, and ? means exactly one of any character
- The relative locations of the files on your development system will be the same as the relative locations of the files when they are installed (see the next section on specifying installation directories).

So, to specify that all .GEO files in the current directory are to be packed, you would simply type

        *.GEO

as the only entry in the list file.

Many packages are more complex than this simple example, however. You can specify files anywhere under the RootDir by including their relative paths in the file list. For example, if you had set RootDir equal to C:\MyApp and you had images in a subdirectory called images and data files in a subdirectory called data, you might have a file list that looks like this:

        *.GEO
        data\*.dat
        images\*.gif

### Specifying Installation Directories

The pack.pl script allows you only one degree of freedom when specifying installation directories for your files: You are allowed to specify the top directory on the GlobalPC into which the .PAK file will be unpacked (the InstallPath attribute). This is similar to how other zip-style and tar programs work: The directory and file structure is essentially picked up from the development system and plunked down on the target system in the same structure.

In the above example, therefore, you would specify the InstallPath directory into which the file tree is to be unpacked, and the software manager would rebuild the tree on the GlobalPC, creating subdirectories if necessary. If you specified InstallPath to be C:\GEOSAPPS\MyApp, then the resulting installation tree may look like this:

        C:\GEOSAPPS\MyApp\MyApp.GEO
        C:\GEOSAPPS\MyApp\data\data1.dat
        C:\GEOSAPPS\MyApp\data\data2.dat
        C:\GEOSAPPS\MyApp\images\img1.gif
        C:\GEOSAPPS\MyApp\images\img2.gif

### Running pack.pl

The pack.pl Perl script is a command-line tool which can accept several arguments. The usage of this script is below; run the script with no arguments to see this output:

        Usage:  [-p listfile [-s size] [-n]] [-v package]
          -p : Use the given file as the file list to pack.
          -s : The output package file size, for packing use only.
               This might generate multiple files and each of them
               will be equal to or smaller than the give size
               (kbytes).
          -v : View the information on the following package file.
               If there is more than one file, just use the first
               file name.
          -n : Specify GEOS longnames for the paths in all files.
               (Typically only used for creating an update pack.)

To run the script, you must provide either -p listfile or -v package as arguments.

To view the contents of a .PAK file, run the script thus:

        perl pack.pl -v filename.PAK

where filename.PAK is replaced with the name of the .PAK file you are investigating. Sample output of this file is shown below:

        name = Professional Fonts
        type = 6
        version = 1.0
        author = TLC
        system = 3.0
        mainprog =
        readme = Prodb.txt
        installpath = ProFonts
        linkpath =
        inifile =
        setupGeos =
        note = Beta Release 1.2
        date = 6/7/100

        total 10 files and in 1 disks(files).

        disk 0 ...
        file: AUBA120c.fnt 19520
        file: AVEN123d.fnt 20985
        file: CIMI1603.fnt 27894
        file: GALO1009.fnt 31658
        file: GREE1033.fnt 59041
        file: HAST1008.fnt 34276
        file: LEWE1211.fnt 29117
        file: PEDI1230.fnt 23274
        file: PING1801.fnt 42495
        file: Prodb.txt 464

The command shows all the attributes, then lists the files along with their file sizes and which disk the files were packed into. (See the -s size command below.)

To pack a file using a list file and no other information, simply run the pack.pl script thus:

        perl pack.pl -p listfile

You can, however, control two other aspects of how the pack.pl script works. If your package is large, you can direct the pack.pl script to break the .PAK file into several files less than a given size. This is most useful if you have an extremely large package and need to distribute it on floppy disks. If you have a package that is extremely large but consists of smaller logical units, consider creating multiple smaller packages instead of using the size limiter.

To break a package up across multiple .PAK files, use the pack.pl script thus:

        perl pack.pl -p listfile -s size

where size is replaced with the maximum size, in kilobytes, of each of the files to be created.

You can also direct the pack.pl script to use GEOS long names instead of the actual file names by specifying the -n option. This is useful primarily for update packages.

## Resources

In order to use the pack.pl script, you need two things: Perl installed on your computer, and the pack.pl script itself. You can obtain Perl from ActiveState Tool Corp at http://www.activestate.com/. They have distributions for Windows as well as other platforms.

The pack.pl script is available from MyTurn.com Developer Relations. You can download it from the Downloads Section of the Developer Relations Web site.