The current PortableApps.com Format Specification is available here:
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 Specification: Draft 4 (2009-02-12)
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
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.
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=184.108.40.206 DisplayVersion=1.2 Revision 3 [Control] Icons=1 Start=AppNamePortable.exe
appinfo.ini file, the entries are as follows:
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 ).
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, Education, 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.
[License] section: (all values are either
Shareable is whether the app is allowed to be copied from one drive to another (without the
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
PackageVersion is the version of the package itself. This must be in 220.127.116.11 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
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
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
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
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 required formats as well as the optional Vista format if desired:
- 16px - 256 color (8-bit)
- 32px - 256 color (8-bit)
- 48px - 256 color (8-bit)
- 16px - True Color + Alpha (32-bit / XP format)
- 32px - True Color + Alpha (32-bit / XP format)
- 48px - True Color + Alpha (32-bit / XP format)
- 256px - True Color + Alpha PNG (32-bit PNG / Vista format) *OPTIONAL
* The 256px alpha size is optional. It is used by Windows Vista to display large and extra large icon sizes. Some publishers may wish to use it to ensure that Vista users using larger icons get the best quality icon when looking at the installer.
4. PORTABLEAPPS.COM INSTALLER
All apps in PortableApps.com Format must use the most recent PortableApps.com Installer (currently version 0.13.3) along with the current PortableApps.comInstaller.bmp graphic. Only the PortableApps.comInstallerConfig.nsh and, optionally, PortableApps.comInstallerCustom.nsh files may be modified and only as indicated.
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:
2009-02-12: DRAFT 4: Added Education category and clarified installer modification notes
2008-08-05: DRAFT 3: Added Vista 256px icon (optional) and updated PortableApps.com Installer notes
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.