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 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.
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:
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.
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."
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:
|
|
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. |
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. |
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:
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
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
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.
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.