PortableApps.com Launcher Manual

your PAL in making portable apps

The PortableApps.com Launcher is a generic launcher, configured by the developer with a simple INI file to make applications into portable apps. Learn more about PortableApps.com...

Make a Donation - Support PortableApps.com's Hosting and Development

Go to the PortableApps.com Launcher Homepage >>

Get portable apps at PortableApps.com

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

Documentation

The file name of the PortableApps.com Launcher, PortableApps.comLauncher.exe, should be changed to AppNamePortable.exe, generaly the AppID of the application.

The PortableApps.com Launcher gets its splash screen from App\AppInfo\Launcher\splash.jpg. For a development test release, this should be the black and white PortableApps.com Development Test Release splash screen. When an application goes on to Pre-Release or official, it gets its own splash screen.

The PortableApps.com Launcher depends on one file for its information and portablization: App\AppInfo\Launcher\AppNamePortable.ini, where AppNamePortable is the base file name of the launcher executable. This often quite complex file is the backbone of the portability which the PortableApps.com Launcher provides. It must be correctly configured to cover everything which the application uses. Only developers should ever modify the launcher INI file, as improper modifications may cause system damage, lose data or cause data to be left behind. In instances where more than one icon is required in the PortableApps.com Menu and merely passing an extra command line variable is not enough, you can place a second copy of PortableApps.comLauncher.exe, and give it a launcher configuration file in App\AppInfo\launcher-SecondLauncherName.ini, where SecondLauncherName is the file name of the second executable minus the ".exe" extension.

Here is the format for the launcher INI file. Where there is a list of possible values, the default value is bold.

[Launch]
AppName=App Name
ProgramExecutable=AppName\AppName.exe
ProgramExecutableWhenParameters=AppName\AppName.exe
CommandLineArguments=--data-directory=%PAL:DataDir%\settings
WorkingDirectory=%PAL:AppDir%\AppName
RunAsAdmin=force / try / none
CleanTemp=true / false
SinglePortableAppInstance=true / false
SingleAppInstance=true / false
CloseEXE=another_optional_app.exe
SplashTime=time (in ms) / 1500
LaunchAfterSplashScreen=true / false
WaitForProgram=true / false
WaitForOtherInstances=true / false
WaitForEXEN=another_optional_app.exe
RefreshShellIcons=before / after / both / none
HideCommandLineWindow=true / false
NoSpacesInPath=true / false

[Activate]
Registry=true / false
Java=find / require / none

[LiveMode]
CopyApp=true / false

[RegistryKeys]
appname_portable=HKEY_CURRENT_USER\Software\Pub\lisher\AppName

[RegistryValueWrite]
HKEY_CURRENT_USER\Software\Pub\lisher\AppName\Value=REG_DWORD:0

[RegistryCleanupIfEmpty]
1=HKEY_CURRENT_USER\Software\Pub\lisher
2=HKEY_CURRENT_USER\Software\Pub

[RegistryCleanupForce]
1=HKEY_CURRENT_USER\Software\Pub\lisher
2=HKEY_CURRENT_USER\Software\Pub

[RegistryValueBackupDelete]
1=HKEY_CURRENT_USER\Software\Pub\lisher\AppName\Value

[FileWriteN]
Type=ConfigWrite / INI / Replace
File=%PAL:DataDir%\settings\data.conf
Entry=<config id="home_directory"> (for Type=ConfigWrite)
Section=Paths (for Type=INI)
Key=home_directory (for Type=INI)
Value=%PAL:DocumentsDir:ForwardSlash%</config> (for Type=ConfigWrite / INI)
Find=file:///%PAL:LastDrive%/ (for Type=Replace)
Replace=file:///%PAL:Drive%/ (for Type=Replace)
CaseSensitive=true / false (for Type=ConfigWrite / Replace)
Encoding=UTF-16LE / ANSI (for Type=Replace)

[FilesMove]
settings\file.txt=%PAL:AppDir%\AppName

[DirectoriesMove]
settings=%APPDATA%\Pub\lisher\AppName

[DirectoriesCleanupIfEmpty]
1=%APPDATA%\Pub\lisher
2=%APPDATA%\Pub

[DirectoriesCleanupForce]
1=%APPDATA%\Pub\lisher
2=%APPDATA%\Pub

[Environment]
PATH=%PAL:AppDir%\AppName;%PATH%
HOME=%PAL:DataDir%\settings

[Language]
Base=%PortableApps.comLocaleglibc%
Default=en
CheckIfExists=%PAL:AppDir%\AppName\Languages\%PAL:LanguageCustom%\*.*
DefaultIfNotExists=en

[LanguageStrings]
en_US=en
zh_CN=zh

[ServiceN]
Name=ServiceName
Path=%PAL:AppDir%\AppName\service.exe
Type=service / driver-kernel / driver-file-system
User=LocalService / NetworkService  / none
Display=Display name
Dependencies=Foo/Bar
Description=Long description of the service
IfExists=skip / replace

Explanation of launcher INI options

There are some definite entries, which specify fixed values, and some arbitrary sections and values for custom entries. First here are the definite entries.

Below here are the arbitrarily specified entries. For all of these, you may specify as many as are needed, according to the formats specified. For those in the format "1Type=something, the numbering system starts at 1, and increments, as in 2, 3, 4. If there is a missing number, any after it will be lost.

Substitutions

Variable substitutions are done by environment variable expansion; this means that all of the local system environment variables are available for use. This applies to INI entries marked above as "substitutions apply".

Sample INI launcher configuration

Sample 7-Zip launcher

7-Zip stores its settings in the registry, in HKEY_CURRENT_USER\Software\7-Zip. In previous releases of 7-Zip Portable, it has stored this in Data\settings\7zip_portable.reg. 7-Zip itself can be run from a read-only location.

Here is a fully functional sample launcher file, configured correctly for 7-Zip:

[Launch]
ProgramExecutable=7-Zip\7zFM.exe

[Activate]
Registry=true

[RegistryKeys]
7zip_portable=HKEY_CURRENT_USER\Software\7-Zip

To outline what this actually does: in the registry, HKEY_CURRENT_USER\Software\7-Zip is backed up if necessary, and the contents of Data\settings\7zip_portable.reg are inserted into the registry, after updating the drive letter. Then App\7-Zip\7zFM.exe is run. After it is closed, the 7-Zip registry key is stored and deleted, and the backup of local 7-Zip settings is restored if it existed.

Sample Code::Blocks launcher

Code::Blocks stores its settings in the local user's application data directory, in %APPDATA%\codeblocks. However, this cannot just be redirected, as it also depends on %USERPROFILE%, which after testing has been demonstrated to not redirect safely. Thus data must be moved back and forth for running portably. Code::Blocks itself can be run from a read-only location.

Here is a fully functional sample launcher file, configured correctly for Code::Blocks:

[Launch]
ProgramExecutable=CodeBlocks\codeblocks.exe
CommandLineArguments=--no-check-associations --no-dde --no-splash-screen

[DirectoriesMove]
personalities=%APPDATA%\codeblocks\personalities
UserTemplates=%APPDATA%\codeblocks\UserTemplates
share=%APPDATA%\codeblocks\share

[DirectoriesCleanupIfEmpty]
1=%APPDATA%\codeblocks

[DriveLetterUpdate]
1=%DATADIR%\personalities\default.conf

To outline what this actually does: %APPDATA%\codeblocks\personalities is backed up if necessary, and the contents of Data\personalities are copied to %APPDATA%\codeblocks\personalities, after updating the drive letter in Data\personalities\default.conf. In the same way, the UserTemplates and share directories are backed up and copied. Then App\CodeBlocks\codeblocks.exe is run. After it is closed, the APPDATA directories are copied to the Code::Blocks Portable Data directory and deleted, and the backup of local Code::Blocks settings is restored if it existed. At the end, if %APPDATA%\codeblocks is empty, it is removed.

A note on Java applications

There are a few different ways of doing Java applications.