PortableApps.com Format Spec Outline (DRAFT 2) [2008-05-01]

Ok, I'm posting a quick outline for comment as the full spec isn't done yet and I'd like to get some more input from the community. Here are just the basics. Nothing too fancy. Please offer up any comments or suggestions. Thanks!

PortableApps.com Format Spec Outline (DRAFT 2) [2008-05-01]

1. DIRECTORY LAYOUT

The basic directory layout of each portable app consists of a main directory, AppNamePortable which contains three directories: App, Data and Other.

AppNamePortable
+ App
  + AppInfo
  + AppName
  + DefaultData
+ Data
+ Other
  + Help
    + Images
  + Source

AppNamePortable: contains the main application launcher, typically named AppNamePortable.exe and the main help file help.html. No other files are present in this directory by default.

App: contains all the binary and other files that make up the application itself, usually within a directory called AppName. The other directory called AppInfo (discussed in section 2) contains the configuration details for the PortableApps.com Platform as well as the icons used within the menu. The third directory, DefaultData is usually used as a container for the default files to be placed within the Data directory. Generally, the launcher, when run, will check if there is a set of files within Data and, if not, will copy them from DefaultData. The next release of the PortableApps.com Installer will do the same.

Data: contains all the user data for the application including settings, configuration and other data that would usually be stored within APPDATA for a locally installed application. The applications released by PortableApps.com typically contain the settings in a settings subdirectory, profiles for Mozilla apps in a profiles subdirectory. No application components (binary files, etc) should be contained within the Data directory. The launcher or application must be able to recreate the Data directory and all required files within it if it is missing.

Other: contains files that don't fit into the other categories. The additional images and other files used by help.html included in the main AppNamePortable are included in a Help subdirectory in the Other directory. Images for the help file would be included in an Images subdirectory within the Help subdirectory.

Any source code or source code licensing as well as the source files for the PortableApps.com Installer are included within the Source subdirectory. This typically includes the source for the AppNamePortable.exe launcher, a readme.txt file detailing the usage of the launcher, license information and other files.

2. APPINFO

The portable app makes available its configuration information to the PortableApps.com by way of the AppInfo details. Within the AppNamePortable\App directory, an AppInfo directory contains an appinfo.ini file as well as any icons used within the menu (explained in Section 3). The appinfo.ini file consists of the following:

[Format]
Type=PortableApps.comFormat
Version=0.9.8

[Details]
Name=AppName Portable
Publisher=App Developer & PortableApps.com
Homepage=PortableApps.com/AppNamePortable
Category=Utilities
Description=AppName Portable is a tool that does something.

[License]
Shareable=true
OpenSource=true
Freeware=true
CommercialUse=true

[Version]
PackageVersion=1.2.3.4
DisplayVersion=1.2 Revision 3

[Control]
Icons=1
Start=AppNamePortable.exe

Within the appinfo.ini file, the entries are as follows:

Within the [Format] section:
Type is the type of configuration file this is (only PortableApps.comFormat is valid at this time).
Version is the version of this format the file is in (currently 0.9.8 ).

Within the [Details] section:
Name is the name of your app as it appears in the PortableApps.com Menu
Publisher is the name of the app publisher as it appears in a hover tip in the next PortableApps.com Platform release and within the app details screen. If you are repackaging an app written by someone else, they should also be listed.
Homepage is the homepage of the portable app (not the base app)
Category is the category that the application falls into within the PortableApps.com Platform. Valid entries are: Accessibility, Development, Games, Graphics & Pictures, Internet, Music & Video, Office, Operating Systems or Utilities. Only these *exact* entries are supported and should be used regardless of the default language of the base app (even if this is a German application, it should still use the English translation of the category).
Description is a brief description of what the application is. Maximum of 512 characters.

Within the [License] section: (all values are either true or false)
Shareable is whether the app is allowed to be copied from one drive to another (without the Data directory)
OpenSource is whether the app is fully open source under an OSI approved license
Freeware is whether the app is free (no cost)
CommercialUse is whether the app is allowed to be used in a commercial environment

Within the [Version] section:
PackageVersion is the version of the package itself. This must be in 1.2.3.4 format with no other characters and must be incremented with each public release.
DisplayVersion is the user-friendly version that is generally used to describe the version. So, a released app may have a DisplayVersion of 2.4 Revision 2 but a PackageVersion of 2.4.0.2.

Within the [Control] section:
Icons is the number of icons that the app has in the PortableApps.com Menu
Start is the command line to execute to start the app relative to the AppNamePortable directory. This will typically be AppNamePortable.exe.

Sometimes, an application will have multiple icons, as is the case with OpenOffice.org Portable. In this case, the last section of the appinfo.ini file will look like:

[Control]
Icons=2
Start=AppNamePortable.exe
Start1=AppNamePortable.exe
Name1=AppName Portable
Start2=AppNamePortable2.exe
Name2=AppName Portable Other Part

Icons is still the number of icons to be shown in the PortableApps.com Menu
Start is the command line to execute for the main application
Start1 is the command line for the first icon (often the same as Start)
Name1 is the name to show in the menu for the first icon
Start2 is the command line for the second icon
Name2 is the name to show in the menu for the second icon

3. ICONS

Within the AppNamePortable\App\AppInfo directory, the icons used by the PortableApps.com Installer and within the PortableApps.com Menu are located. The main icon is called appicon.ico. If the application also uses multiple icons (as detailed above), these additional icons are named as appicon1.ico, appicon2.ico, etc. The numbers correspond to Start1, Start2, etc within the Control section.

All icons are in Windows ICO format and contain the following 6 formats:

• 16px - 256 color
• 32px - 256 color
• 48px - 256 color
• 16px - 32-bit True Alpha (aka XP format)
• 32px - 32-bit True Alpha (aka XP format)
• 48px - 32-bit True Alpha (aka XP format)

4. PORTABLEAPPS.COM INSTALLER

All apps in PortableApps.com Format must use the most recent PortableApps.com Installer (currently version 0.9.9.0) along with the current PortableApps.comInstaller.bmp graphic. Only the sections marked with ;=== BEGIN: BASIC INFORMATION, ;=== BEGIN: PRE-INSTALL CODE and ;=== BEGIN: POST-INSTALL CODE and their corresponding END comments may be altered.

If a larger application is being compiled that has a longer development and testing time, and a new version of the PortableApps.com Installer is released during testing of a release the version of the installer the app is currently using may be kept provided that the new Installer version is less than 30 days old on the day the application using the older version is released.

5. HOST PC MODIFICATIONS

During use, a portable app is permitted to modify registry entries and files on the local drive, however the registry and local files must be returned to their pre-run state on exit. This will often involve backing up and then restoring the settings for a local copy of an application on start and exit.

Updates to this file:
2008-05-01: DRAFT 2: Added DefaultData description as we use it in many apps and the installer will be supporting it as well (handy for language setups) and the fact that the Data directory must be recreated by the app if missing, which is new but done by all released apps but one.