The current PortableApps.com Format Specification is available here:
https://portableapps.com/development/portableapps.com_format
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 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, 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.
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 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.
Visit the Community page
Join our forums
Subscribe to our email newsletter
Subscribe with RSS
Follow us on Facebook
Follow us on LinkedIn
Follow us on Twitter
Follow us on Mastodon
Follow us on BlueSky
THANK YOU FOR DOING THIS!
this might clear up some issues that new developers are having. Good Job.
An eye for an eye makes the whole world blind.
Mahatma Gandhi,
Indian political and spiritual leader (1869 - 1948)
No offense John, but I thought Hell was going to freeze over first. We NEEDED this!
Quick question, though... most apps here have AppSource.txt in Other/Source saying where to get the source for the app... but what about self-made apps that include the source? I can't just throw all my .cpp and .hpp files in Other/Source, that would be a huge mess...
If it's big, have it be a sep download and direct people to it from a text file (like we do). If it's small, zip it up and include it.
Sometimes, the impossible can become possible, if you're awesome!
I'll prepare a better template!!!!!
Insert original signature here with Greasemonkey Script.
You might want to note that AppName is to be replaced with the actual name of the app. It may seem obvious, but some people might miss that distinction.
"If you're not part of the solution, you're part of the precipitate."
You might want to include the detailed version numbering scheme you posted in another thread.I think it would make it clearer.
"What about Love?" - "Overrated. Biochemically no different than eating large quantities of chocolate." - Al Pacino in The Devils Advocate
Bookmarked!
THANK YOU
This weekend i'll make sure all my Dev Tests are up to these specs and update anything that needs it.
The developer formerly known as ZGitRDun8705
Thank you!
cowsay Moo
cowthink 'Dude, why are you staring at me.'
I was thinking that the installer should have a 'run appname' on it.
I mean we didn't install it just because we had the time and space, we installed it to use it...
Oh, just an opinion, but if we let the base app modify the host, then the launcher basically is a macro to move files and regkeys around w/ a splash...
Insert original signature here with Greasemonkey Script.
John doesn't want 'Run Appname Portable' on the installers, and neither do I. With this many portable apps, most users download a bunch and just install 'em all at once. Maybe John has more reason, but he's verified he does not want that feature.
Does filename case matter, e.g. is it Help/images or Help/Images (you used both in the draft)? It doesn't matter in Windows since the OS doesn't care about case, but if we're looking at future cross-platform support, it will. Linux, for instance, is case-sensitive.
Perhaps we should just go all mixed case (Help, Images, etc) for folders. Thoughts?
Sometimes, the impossible can become possible, if you're awesome!
I think mixed. Help, Images, App\AppName, and what about Data\settings?
The settings directory isn't actually part of the actual spec. It's just something we use. And it's always been lowercase. As has profile.
Sometimes, the impossible can become possible, if you're awesome!
It's always been that way isn't really a reason... If everything else is mixed case, why buck the trend?
formerly rayven01
It'll help keep things consistent if we do. Obviously not all consistency is good, but in this case I think it is.
I made a template with the new Specs, found here.
I know John's gonna release the official vers too.
Insert original signature here with Greasemonkey Script.
How about an option in the [control] section to ignore an .exe file?
For example, if you install Cobian Backup under X:\PortableApps\Cobian, you get several executables, but you only want to execute cobian.exe by hand. Something similar happens with WinAmp (yes, I know... it's commercial. But I still love it).
Another suggestion: I think it would probably be better to describe what the installer must do/not do than force everyone to use the official installer, just in case someone develops (or adapts) an app that can fit into the portable format but has very peculiar installation needs... OTOH, I can't really think of an example, so perhaps this is just empty theory...
Both of these are already handled. Multiple EXE apps get placed in AppNamePortable\App\AppName and just need a simple shortcut launcher in AppNamePortable for folks launching manually. We may actually drop that as a requirement and make it a recommendation in which case, for winamp, it could just have Start=App\AppName\winamp.exe in the appinfo.ini and no shortcut launcher needed. But this will have to wait until more folks are on the new menu.
As for the installer, you have the option of including custom code and we'll even be doing that with many of the apps done by PortableApps.com just as you can in the launcher now. If something has more peculiar installation needs than that, then it probably doesn't qualify as a portable app anyway.
Sometimes, the impossible can become possible, if you're awesome!
The installer is GPL with the exception for non-GPL apps applying only if the app is released on PA.com. What if a commercial developer wants to PAF their app themselves? Then they have to make their own installer, otherwise violate the GPL...
The 1.0 release of the PortableApps.com Installer will allow that as well.
Sometimes, the impossible can become possible, if you're awesome!
I was thinking of just doing something like:
And then those two files won't show in PAM, with no need to create a program that will fire up another program. I can do that quite easily, but there's a lot of people out there who haven't got a clue of what a compiler is. (Perhaps that's the healthy option.
)
However I do realize this would be a new feature... perhaps this belongs somewhere else, since it isn't a suggestion about the current format...
For your own stuff, you can do what I mentioned above and just have Start= point to the EXE you want. You just can't redistribute it and call it PortableApps.com Format right now.
Sometimes, the impossible can become possible, if you're awesome!
I started with a lot of files (including winamp.exe and other two needed but "not clickable" .exe's) in B:\PortableApps\Winamp
Here's what I did:
1) Created directories and an appinfo.ini file as outlined in the spec:
Contents of the AppInfo (I didn't bother to put real stuff in all the fields):
2) Restarted PAM Version 1.1 Beta 4
No Winamp icon
3) Created an empty (dummy, 0kb) file at B:\PortableApps\Winamp\Winamp.exe and restarted PAM again.
There's the icon. Clicking on it does nothing. Double clicking -or typing in Start|Run- B:\PortableApps\Winamp\App\Winamp\winamp.exe launches Winamp OK.
Am I missing something? I do need to write a real .exe to place in B:\PortableApps\Winamp\Winamp.exe that will fire up the real Winamp.exe, right?
The current releases don't yet support PortableApps.com Format INIs as they were created before the format had been finalized. They just scan for EXEs in each directory.
Sometimes, the impossible can become possible, if you're awesome!
So what I was doing was right, just won't work till the next release?
Well, looks like I'm going to have to write that launcher after all...
Thanks for the guidance, John. (not to mention the whole site
)
I added in DefaultData along with a description as the launcher will be handling this in an upcoming release. Also the fact that the launcher or app must be able to recreate the Data directory and contained files if needed.
Sometimes, the impossible can become possible, if you're awesome!
John T. Haller wrote:
--------------------
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)
--------------------
I agree on what I understand of the specs. But I'd like to propose one thing.
The new Windows Vista displays most icons at a default of 64px/128px size.
And the only versions of Windows that use 48px sizes are XP or up, and they support alpha channel. Windows 2000 (the version immediately before XP) doesn't have alpha channel, and neither shows option for 48px size unless by hacking it.
The icons have an actual max size limit of 48px. I think we should modify the sizes used on the icons for something like this:
I think it would be nicer. What do you think?
Blue is everything.
Just not 256, it seems to ridiculous to me.
You won't think it's ridiculous when 500dpi displays come out and you can't see your icons @ 96dpi (Vista won't stretch past 48x48 without a high res icon)...
There are instances when you may be stuck viewing something over a remote desktop connection or VNC in which cases alpha icons look horrendous. That's why the 256 color 48px icon is there.
On Vista, 48px icons is the default for just about everything with the exception of the lower status bar that shows drives. By clicking through views, you can get large icons which are 64px. And, you can manually select Extra Large icons (though it isn't in the rotation by just clicking through views) and those are 256px.
For the launcher, people will usually only see the 16s in the PortableApps.com Menu. Even if they browse in and click on them, the 48s are still there to see. Most software doesn't bundle anything above 48s including major stuff like Firefox (16, 32 and 48 in 16 color, 256 color and XP format) so Vista users are used to fuzzy icons if they set their system to large or extra large.
Adding the 64s would increase the size a bit. 128 is a non-standard size. 256 isn't bad for some icons depending as it's actually stored as a compressed PNG which can result it in taking up less space than a 64.
The bottom line is, for now, we'll stick with 16,32,48 as it covers all bases on all OSes but Vista and it covers the default on Vista. Once more software adds in 256s, we'll probably add that in (as I believe Vista will use that for other sizes if they aren't present).
Sometimes, the impossible can become possible, if you're awesome!
Vista was originally supposed to have vector icons, but they were dropped. So instead it scales the 256px icon to whatever size is needed.
So would it be within the spec to add a 256px icon to my own app? As long as I include the 6 required formats?
You can include it in your app itself within the App\AppName directory... which would just be a waste of space, really, since that will only appear in a titlebar... but appicon.ico expects only the formats listed.
We may eventually add it in, but for right now, no. We'd need to do testing of it on Windows 95/98/Me as well as Wine on multiple OSes to determine whether it has any effect on anything... something I highly doubt Microsoft has done since they dropped support for Win9x a while ago and don't support Wine.
Sometimes, the impossible can become possible, if you're awesome!
But you still didn't answer my question below, about the case of the images subdirectory...
It doesn't really matter as long as an app stays consistent within itself, as I already stated the last time it was asked. We'll say uppercase just so it says something.
Sometimes, the impossible can become possible, if you're awesome!
You didn't really state. All I see is you asking for thoughts.
Oops
Well, it's uppercase now, so we're good.
Sometimes, the impossible can become possible, if you're awesome!
You still didn't clarify on the case of the
imagesdirectory. The diagram shows "Images" but the spec itself says "images." Which is it?Are we going all mixed case, or not? Would be helpful to know before I convert my game to PAF...
You forgot to put stuff about standalone apps, trademarks, and copyrights(add your copyright, change legalcopyright to pa.com and contributors, etc.).
Insert original signature here with Greasemonkey Script.
And what about DefaultData, can it be left out if it isnt needed and thus empty?
"What about Love?" - "Overrated. Biochemically no different than eating large quantities of chocolate." - Al Pacino in The Devils Advocate
That will be required by the upcoming installer and platform.
Sometimes, the impossible can become possible, if you're awesome!
why?
What if its just an empty folder?
Too many lonely hearts in the real world
Too many bridges you can burn
Too many tables you can't turn
Don't wanna live my life in the real world
Then it's included, but empty. But it's part of the spec.
Actually, I spose it doesn't matter and can be marked as optional.
Sometimes, the impossible can become possible, if you're awesome!
That's the installer... nothing with the format at the moment until it is merged in. And that's discussed in the other topic.
Sometimes, the impossible can become possible, if you're awesome!
to prove to chrism that the readme.txt was required by the spec, but it's not in there...
Insert original signature here with Greasemonkey Script.
It's just best to throw in so curious users don't go messing things up. But it doesn't matter either way.
Draft 3 adds in the ability to optionally use a 256px Vista icon as well as updates to the new PortableApps.com Installer configuration.
Sometimes, the impossible can become possible, if you're awesome!
Thanks!
Yay! A new one. ^_^ Thanks John ^_^
iLike Macs, iPwn, However you put it... Apple is better ^_^
"Claiming that your operating system is the best in the world because more people use it is like saying McDonalds makes the best food in the world..."
Hi,
It would be nice if the launcher could also register environmental variables like PATH for running portable apps like MinGW, Mikitex, as well as file associations that will be restored when the portableapp is closed/or the portablemenu is closed.
Also there should be standardized the use of portable CommonFiles like java, gtk, python, perl, etc
But these things make way more sense if included into the menu (which is planned) than into one Launcher cause if included into the launcher, they are only there for the App launched by it.
"What about Love?" - "Overrated. Biochemically no different than eating large quantities of chocolate." - Al Pacino in The Devils Advocate
... to [Version]?
This will be a good solution in order to realize multilanguage launchers.
Paid for Software more or less?
What You need is OSS!
I'm not sure what you mean. Or do you mean an entry in appinfo.ini the launcher can check so it knows what language to come up as? If so, maybe. But it would be complicated with multilingual apps. Let me ponder it a bit in terms of the new installer and stuff as that would also be affected by appinfo.ini changes.
Have the OO.o Portable launchers single-language for now. There's no reason to change it.
Sometimes, the impossible can become possible, if you're awesome!
... and thats exactly what I mean.
Paid for Software more or less?
What You need is OSS!
"Education" is now a valid category, and needs adding to the categories list.
I am a Christian and a developer and moderator here.
“A soft answer turns away wrath, but a harsh word stirs up anger.” – Proverbs 15:1
Added in the Education category and clarified the PortableApps.com Installer modification notes.
Sometimes, the impossible can become possible, if you're awesome!