To install Nutshell for Windows, unzip and copy the Nutshell Windows.exe program to your hard disk.
Installing on Mac OS X
To install Nutshell for Mac OS X, mount the disk image file and drag the Nutshell application to your Applications folder.
Adding/Removing Files
Launch the Nutshell application. A new nutshell document is automatically created. The top of the Nutshell main screen allows you to add and remove PRC and PDB files from the installer. You can use the "Add" and "Remove" buttons to browse for Palm files on your hard disk. You can also drag Palm files to the list. Nutshell remembers the absolute path to your files. If a file cannot be found, the list will display that file in red.
General Tab
This tab includes important settings for your installer.
Short Name (Icon)
The "Short Name (Icon)" specifies the name which will display under the installer icon in the Palm OS launcher. The length of this field should be short to allow the name to display correctly in the Palm OS launcher.
Long Name (Database)
The "Long Name (Database)" field sets the installer's database name. A Palm OS database name must be unique on a Palm device. Installing a file with a duplicate database name will replace the existing file. Therefore, you should choose a database name for your installer, and continue to use this name for future versions of your installer. That will ensure that older copies of your installer will be replaced by newer ones. Database names are limited to 31 characters.
Description Text
The "Description Text" will be displayed to the user while the installer is running. If the installer contents is small, this message may not even stay on the screen long enough to be readable.
Installer Category
Specifies the default launcher category in which the installer will show up.
Installer Version
This is the version number that will show up in the Palm's Info window. Any text string can be provided.
Creator ID
Since the installer is an actual program, it is necessary for it to have a creator ID. A creator ID is a unique four letter code assigned to Palm programs and databases.
IMPORTANT: If you need multiple Nutshell installers to show up individually in the Palm's main menu or Palm's built-in beaming list, you must assign each Nutshell archive a unique Creator ID. This only applies to some Palm OS versions.
If you plan to distribute your Nutshell installer, and you do not use 'SHEL' as the creator ID, you must register the new creator ID with PalmSource. This is a free, process that can be done at www.palmsource.com.
Options Tab
This tab includes more options to add functionality to your installer.
Ask Before Replacing Databases
Prompts the user before overwriting databases with the same name. The user is presented with version information about the old and new databases. A "Replace All" option is made available to the user.
Auto-Run Installer After HotSync
The installer will run automatically after it arrives on a device, either via HotSync or a beaming transfer.
Auto-Delete Installer After Installation
The installer will be erased after a successful installation. This option is recommended since it is unlikely that a user will need to install your software twice. Installers run from an expansion card will not auto-delete.
Prevent Installation on Palm OS 5 or Higher
The "Prevent Installation on Palm OS 5 or Higher" option is provided for software that doesn't support Palm OS 5.
Prevent Installation on Palm OS 6 or Higher
The "Prevent Installation on Palm OS 6 or Higher" option is provided for software that doesn't support Palm OS 6.
Archive Can't Be Beamed
This will set the "Copy Protected" bit on your installer. A padlock icon will show up beside the installer in the Palm's beaming and sending interface.
Use Compression
This option will use ZIP compression to reduce the size of your installer by up to 70%. On slower Palm devices, this may increase the time it takes to install.
Minimum Palm OS
"Minimum Palm OS" allows you to specify a minimum Palm OS version for your software package. Users attempting to install on a lower Palm OS version will see an appropriate error message.
Auto-Launch After Install
If any of the files that you have selected are executable programs or PQA files, they will show up in the "Launch After Install" list, and you can choose one to be automatically launched after the install process is complete.
Inherit Icon from Auto-Launch App
If you choose an auto-launch application (above), then you can choose to have your installer automatically use its icon by checking "Inherit Icon from Auto-Launch App".
Install Message Tab
You can choose to display a message to users before the installer runs. You can also choose what button are displayed to the user. You can use this message as a license agreement by choosing the "Accept/Decline" button set. If the user chooses the "Decline" or "Cancel" button, the installer will abort. You have the option of providing international versions of the installer message. English will be used on foreign language Palms if the specific language's message is not provided.
Languages Tab
Nutshell provides various language options.
Require User To Scroll To The Bottom of the Message
If your message is a license agreement, you may wish to require the user to scroll to the bottom of the message before continuing with the installation process.
Additional Languages
Nutshell includes additional languages for alerts and messages that show up during the installation process. The extra languages will be used automatically on international devices. Choose these checkboxes to add languages. Each language adds about 2 kilobytes to the installer.
Only Install Overlays for Device Locale
Overlay databases are special Palm OS resource databases which allow developers to add new languages to applications. This checkbox enables a mechanism by which only the appropriate overlay database for a Palm device's locale will be installed. For example, your installer may include overlay databases for English, French, Spanish and Japanese. When the installer is run on a Spanish Palm, only the Spanish overlay database will be installed. When run on an English Palm, only the English overlay will be installed.
Uninstaller Tab
Nutshell can create an uninstaller to go along with your installer. The uninstaller is not installed by the installer, but can be installed separately by the user. The uninstaller program will confirm the process with the user and then delete all files installed by the installer.
Create Uninstaller
Select "Create Uninstaller" to create an uninstaller PRC.
Warn User if Different Version Detected
If this option is selected, the uninstaller will warn the user if it is about to uninstall a different version of an app than was originally installed. Note that in earlier versions of Nutshell, there was no option for this, and it always happened.
Remove All Files With Included Creator IDs
Use this option if your app creates new PDB files after it is installed. When the uninstaller runs, it will erase all files and databases with your app's creator ID. (Without this option, the uninstaller will just delete exactly what it originally installed.)
Uninstaller Creator ID
Optionally provide a unique creator ID code for your uninstaller. The default ID is 'uPRO'. In most cases it should be fine to use the default ID.
Creating a Nutshell Installer
After you have chosen the items to be included in the archive, and set your desired options, click the "Create Nutshell Installer" button.
You will be prompted to save the installer PRC file. If you chose to create an uninstaller, you will also be prompted to save a second PRC.
Distributing a Nutshell File
You are done. You can now distribute the Nutshell installer file as you would a regular Palm file. It will self-expand when it is run on a Palm device.
Saving and Restoring
You can choose to save your installer settings and list of files as a .nutshell document by choosing "Save" from the "File" menu. This can be useful if you often create the same installer for testing or distribution.
Compatibility/System Requirements
General Requirements
The Nutshell installer is compatible with Palm OS 3.0 or later. This includes Palm OS 5 and 6.
Nutshell installer is incompatible with !pZip v1.1. This may be corrected in later versions of !pZip.
Windows Requirements
Nutshell for Windows requires Windows 95 or higher.
Mac OS X Requirements
Nutshell for Mac OS X is compatible with Mac OS 10.3.9 or higher.
