PortableApps.com Launcher Manual

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...

- 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.

• [Launch]
  • AppName
    This is used for the error message box provided to the user if there is already a copy of the application running. It should be like this: "Mozilla Firefox", or "Code::Blocks", or "7-Zip". In theory this field should never be used, as it defaults to the long name specified in appinfo.ini minus the string " Portable" or ", Portable Edition" at the end. Please consider changing the value in appinfo.ini rather than using this field.
  • ProgramExecutable
    This is the path to the application to launch, relative to the "App" directory. Generally, it should have no spaces or characters which cannot go in file names, and should be like this: "Firefox\firefox.exe", or "CodeBlocks\codeblocks.exe", or "7-Zip\7zFM.exe", or "gimp\bin\gimp-2.6.exe".
  • ProgramExecutableWhenParameters
    This is an optional override for ProgramExecutable for when a different executable needs to be launched if command line arguments are passed in. The general use case for this is when you want to launch a menu normally but if given a file directly, for example with a compiler, you want instead to bypass the menu. NSIS Portable is a good example of this.
  • CommandLineArguments
    This is used as command-line arguments to always pass to the executable, for example "--data-directory=%PAL:DataDir%\settings --music-directory=%PAL:MusicDir%". Due to some issues with INI parsing in Microsoft Windows, if you wish to quote a string you may need to put single quotes around the value otherwise parts of the parameters may be lost (i.e. CommandLineArguments='--data-directory="%PAL:DataDir%\settings"'). Substitutions apply.
  • WorkingDirectory
    This is used to change the working directory to start the application in. Only use this if absolutely necessary, as it will (at the moment) mess up relative files passed through the command-line. Example (normally all it'll ever need): "%PAL:AppDir%\AppName". Substitutions apply.
  • RunAsAdmin (values: force, try or none)
    If the application requires administrative privileges (for example for services or drivers, or if settings are stored in HKEY_LOCAL_MACHINE), set this value to force. If some features require administrative privileges, but are not essential, set this value to try. Otherwise, leave this value unset.
  • CleanTemp (values: true or false)
    If the application writes things to the TEMP directory and does not always clean them up, specify "true" here, and it will be given a subdirectory (in the format %TEMP%\AppNamePortableTemp) as its TEMP directory, which will be removed after the application is closed, thus not leaving anything behind. If WaitForProgram is set to false, this will still work, but it may be slower. The TEMP directory will be set to go in Data\temp, so that it is still functional. This may slow down some apps, and may also clutter up the running device. Additionally, this directory will not be deleted upon program completion, but it will be the next time the application is started.
  • SinglePortableAppInstance (values: true or false)
    If you only wish one instance of the portable version of the application to be run, set this to true. If it is set to true, if the launcher is started while another copy of the launcher is already running, the second instance will abort silently. If you wish to prevent a local and portable version of the application from running concurrently, look at SingleAppInstance.
  • SingleAppInstance (values: true or false)
    If you only wish one instance of the application, portable or local, to be run, set this to true or omit it. If it is set to true, if the launcher is started while another copy of the application, portable or local, is already running, it will abort with an error message.
  • CloseEXE
    If you wish to specify another executable to require to be closed before the portable application is started than the ProgramExecutable entry, enter the file name in here, e.g. "inkview.exe" for Inkscape.
  • SplashTime (value: time to show splash screen in milliseconds, default: 1500)
    If an application takes a long time to start you may wish to have the splash screen show for more than 1.5 seconds (1500ms). Specify the number of milliseconds (as an integer) here to change from it the default 1500.
  • LaunchAfterSplashScreen (values: true or false)
    With full-screen, resolution-changing applications, running the application while the splash screen is active can confuse the program. If you observe this behaviour in your application, set this to true. (Otherwise avoid it as it slows things down.)
  • WaitForProgram (values: true or false)
    If you don't need the launcher to wait for the conclusion of the application, set this to false. Note that you should only do this if you do not have registry entries to handle or files to move, for example if you can redirect all settings with command-line arguments or environment variables.
  • WaitForOtherInstances (values: true or false)
    If the application is single-instance (i.e. if you run another copy of it it won't run but will activate the first one), and the application can't restart itself, you can set this to false. If the application can restart itself at all, e.g. Firefox can, DO NOT set this to false, or else clean-up will start while the application is still running, which won't be good for it.
  • WaitForEXEN
    If the program that you run is a launcher program which launches another executable, and you need to wait for that as well as (or instead of) the original program, specify its file name here, as WaitForEXE1=whatever.exe. If you need more than one, use WaitForEXE2, WaitForEXE3, etc.
  • RefreshShellIcons (values: before, after, both or none)
    If the application does any registering of file type extensions which you handle or clean up, to make the new icon appear or to stop the portable one appearing, set this to one of the values. If it is just cleaning up at the end, after should be enough, but if you handle it with a RegistryKeys value, you will need both.
  • HideCommandLineWindow (values: true or false)
    If the application produces a command line window which you wish to hide (common in some open source games), you can set this to true to hide it.
  • NoSpacesInPath (values: true or false)
    If the application will not function if you try to run it in a directory with spaces in the path, you can set this to true to provide a useful error message to the user in this situation.
• [Activate]
  This section is for telling the launcher whether or not it should load certain things, for example Java and registry support.
  • Registry (values: true or false)
    If the base application uses the registry, set this to true. You MUST set this to true if you wish the registry sections to be parsed. Otherwise they will not be read at all.
  • Java (values: find, require, or none)
    If the application can use Java but does not depend on its being available, set this to "find", and a Java Runtime Environment (JRE) will be found if available, and %JAVA_HOME% will become available as a replacement variable. If the application is completely dependant on Java, set this to "require". Then you may set ProgramExecutable to "javaw.exe" (normal use) or "java.exe" (command line version which may be useful for testing and debugging) and it will use Java. Then mention the JAR file you need in CommandLineArguments (as -classpath).
    Caveat: With "require", if you can possibly help it, set WaitForProgram or WaitForOtherInstances to false if you use java.exe or javaw.exe. Otherwise you'll run into problems cleaning up if other Java applications get run, as it'll look for instances of the application, and find javaw.exe, even though it's another application's javaw.exe instance.
• [LiveMode]
  This section is relevant to running the portable application from a read-only location. As specified here, certain things are copied to the local hard drive, and then the application is run, and any things copied locally are deleted. This is called running locally, or "Live mode".
  • CopyApp (values: true or false)
    When run in Live mode, does the application need to be run from a writable location? If yes, specify "true".
  • CopyData
    This option has been removed due to issues with the %PAL:DataDir% replacement variable in file moving. Data will now always be copied. This may change back in the future.

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.

• [RegistryKeys]
  These are registry keys for which to manage portability. They come in the form file name=registry key location; the file name is the location of the place where it is saved, which is in Data\settings\file name.reg. If you wish to have drive letters updated inside this, look at [FileWrite] with Type=Replace.
  Example: appname_portable=HKEY_CURRENT_USER\Software\AppName
• [RegistryValueWrite]
  These are registry values to set for running the portable application, useful for things like disabling file association writing. They come in the form HKEY_ET\Cetera\Key\Value=REG_TYPE:value; the key name is the place in the registry, with the value appended to it after a final slash, and the value is of the form REG_TYPE:value; REG_TYPE: is optional, and defaults to REG_SZ (a string).
  Example: HKEY_CURRENT_USER\Software\AppName\Key\Value=REG_DWORD:16
• [RegistryCleanupIfEmpty]
  These are registry keys which get cleaned up after the application has run if they are empty. This is useful if there is a tree which will be left behind, for example, if something stores to HKEY_CURRENT_USER\Software\Publisher\AppName, when AppName is saved, Publisher will still be left, empty. Remove it with a line in here.
  Example: 1=HKEY_CURRENT_USER\Software\Publisher
• [RegistryCleanupForce]
  These are registry keys which get removed after the application has run. This is useful if there is a tree of useless information which will be left behind, for example, if something stores temporary data to HKEY_CURRENT_USER\Software\AppName\Temp. Remove it with a line in here.
  Example: 1=HKEY_CURRENT_USER\Software\Publisher
• [RegistryValueBackupDelete]
  These are registry values which get backed up before hand and restored later, but any value which may have been set while the portable application is running will be deleted. This can be useful for "dead" values which serve no purpose and so there is no point in saving them anywhere.
  Example: 1=HKEY_CURRENT_USER\Software\Publisher\AppName\Value
• [FileWriteN]
  For writing data to files. The values which must be set depend on the Type specified below.
  • Type (values: ConfigWrite, INI, Replace)
    Specify the type of file writing which is to be used.
    ConfigWrite: write arbitrary data to a file, the line on which to write being selected as one starting with the Entry.
    INI: write a string to an INI file.
    Replace: search for a string and replace it with another string in a file. This is particularly useful for updating drive letters and configuration paths (using %PAL:Drive% and %PAL:LastDrive%)
  • File (applies to all Types)
    Specify the file in which the modification will be made.
    Substitutions apply.
  • Entry (applies to Type=ConfigWrite)
    The Value will be written to a line starting with this value, or if it is not found, at the end of the file. This should be set to the text to search for at the start of a line. In an INI-style file, this would be "key=", and in an XML file it might be "    <config id="something">"; note that you must include any leading whitespace which will be in the file.
  • Section (applies to Type=INI)
    The INI section to write the value to.
  • Key (applies to Type=INI)
    The INI key to write the value to.
  • Value (applies to Type=ConfigWrite / INI)
    The value which will be written to the file. If dealing with Type=ConfigWrite, you should remember with things like XML files that you will normally need to close the tag, for example "%PAL:DataDir%\settings</config>"
    Substitutions apply.
  • Find (applies to Type=Replace)
    The string to search for.
    Substitutions apply.
  • Replace (applies to Type=Replace)
    The string to replace the search string with. If, after environment variable replacement, this is the same as the Find string, the replacement will be skipped (e.g. if you use it to update drive letters and it's on the same letter).
    Substitutions apply.
  • CaseSensitive (values: true or false, applies to Type=ConfigWrite / Replace)
    Case sensitive searches are somewhat faster than case-insensitive searches. If you can do a case-sensitive ConfigWrite or find/replace, do.
  • Encoding (values: UTF16-LE or ANSI, applies to Type=Replace)
    If you need to find and replace in a Unicode (UTF16-LE) file, set the encoding here as UTF-16LE; otherwise don't include this value.
• [FilesMove]
  These are files for which to manage portability. They come in the form file name=target directory; the file name is the location of the place where it is saved, relative to the portable data directory.
  Substitutions apply.
  Example: settings\file.txt=%PAL:AppDir%\AppName
• [DirectoriesMove]
  These are directories for which to manage portability. They come in the form directory=target location; the directory is the location of the source directory, relative to the portable data directory. The target location includes the directory you want it to go to, so %PAL:DataDir%\from\*.* gets copied to to\*.*.
  Substitutions apply.Example: settings=%APPDATA%\Pub\lisher\AppName
• [DirectoriesCleanupIfEmpty]
  These are directories which get cleaned up after the application has run if they are empty. This is useful if there is a tree which will be left behind, for example, if something stores to %APPDATA%\Publisher\AppName, when AppName is saved, Publisher will still be left, empty. Remove it with a line in here.
  The key names here are numbers.
  Example: 1=%APPDATA%\Publisher
• [DirectoriesCleanupForce]
  These are directories which get removed after the application has run. This is useful if there is a tree which will be left behind, for example, if something stores temporary data which can be safely deleted in %APPDATA%\AppName\Temp. Remove it with a line in here.
  The key names here are numbers.
  Example: 1=%APPDATA%\Publisher
• [Environment]
  Environment variables to modify, for example "PATH" or "HOME". To append or prepend to the variable place %(var name)% at the start or end of the value. Substitutions apply.
  Example: PATH=%PAL:AppDir%\AppName;%PATH% (this will prepend the executable's directory to the path.)
• [Language]
  This section is for constructing a custom language variable. The final output goes in the PAL:LanguageCustom environment variable.
  • Base
    The base string upon which languages are based. This should contain (and probably be) one of the language environment variables. Substitions apply.
  • Default
    If the base value is not found in the [LanguageStrings] section, it will be set to this value. If this value does not exist it will fall back to the base value. Substitions apply.
  • CheckIfExists
    Check if this file exists. To check for a directory add "\*.*" to the end. If the file does not exist it will fall back to the DefaultIfNotExists value. Substitions apply.
  • DefaultIfNotExists
    If the file in CheckIfExists did not exist, the custom language variable will be set to this value. Substitions apply.
• [LanguageStrings]
  Values in the [Language] Base will be looked up here and the values returned. Substitutions apply.
• [ServiceN]
  Services and drivers which are required or recommended by your portable application. There are various keys for each section:
  • Name
    The service name.
  • Path
    The execution string of the service.
  • Type (values: service, driver-kernel or driver-file-system)
    Specify whether you are dealing with a service, a service with desktop interaction or a driver.
  • User (values: LocalService, NetworkService or none)
    If the service needs to run as other than LocalSystem, i.e. as LocalService or NetworkService, specify it here (omit the leading NT AUTHORITY\).
  • Display
    The short display name of the service.
  • Dependencies
    A slash-separated list of dependencies
  • Description
    A description of what the service does for the services control panel applet (this should not be necessary)
  • IfExists (values: skip or replace)
    If the service already exists, you can either skip it or replace it with the portable version of the service (the original service will be restored afterwards).

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".

• %PAL:Drive% – the drive letter including a colon from which the portable application is running; in Live mode, this is the location of the portable device, not the application or data directory if CopyApp is set. e.g. "X:"
• %PAL:LastDrive% – the drive letter including a colon from which the portable application ran last; in Live mode, this is the location of the portable device, not the application or data directory if CopyApp is set. e.g. "X:"
• %PAL:DriveLetter% – the drive letter from which the portable application is running; in Live mode, this is the location of the portable device, not the application or data directory if CopyApp is set. Useful with FileWrite find and replace where the colon is not included in the path, e.g. file:////%PAL:DriveLetter%/ for file:////X/ or even %PAL:DriveLetter%\:/ for X\:/. e.g. "X"
• %PAL:LastDriveLetter% – the drive letter from which the portable application ran last; in Live mode, this is the location of the portable device, not the application or data directory if CopyApp is set. Useful with FileWrite find and replace where the colon is not included in the path, e.g. file:////%PAL:LastDriveLetter%/ for file:////X/ or even %PAL:LastDriveLetter%\:/ for X\:/. e.g. "X"
• Directory variables: with all of these variables, before the closing % can come one of four things: nothing, :ForwardSlash, :DoubleBackslash, or :java.util.prefs. These refer to the path type and directory separator to be used; if there is nothing there, it is a backslash. For example, %PAL:PortableAppsDir% is X:\PortableApps, %PAL:PortableAppsDir:ForwardSlash% is X:/PortableApps, and %PAL:PortableAppsDir:DoubleBackslash% is X:\\PortableApps. If unsure, use the default single backslash. java.util.prefs is a special type for registry keys with Java applications that use java.util.prefs to store their settings. It stores paths like this: %PAL:PortableAppsDir:java.util.prefs% will become /X:///Portable/Apps; all characters other than a colon (:) and lowercase letters are prefixed with a slash (/). The directory separator is a forward slash, which is then prefixed with another slash as per the rule stated.
  • %PAL:AppDir% – the location of the App directory (not including the AppName bit), e.g. X:\PortableApps\AppNamePortable\App
  • %PAL:DataDir% – the location of the Data directory (not including the settings or similar bit), e.g. X:\PortableApps\AppNamePortable\Data
  • %JAVA_HOME% – the location of the Java Portable directory (not including "bin"), e.g. X:\PortableApps\CommonFiles\Java. This variable will only be available with [CommonFiles]:Java equal to find or require, but if it is find, it may not exist (for require the launcher will abort if Java is not found).
  • %PAL:DocumentsDir% – the PortableApps.com Documents directory, e.g X:\Documents
  • %PAL:PicturesDir% – the PortableApps.com Pictures directory, e.g X:\Documents\Pictures
  • %PAL:MusicDir% – the PortableApps.com Music directory, e.g X:\Documents\Music
  • %PAL:VideosDir% – the PortableApps.com Videos directory, e.g X:\Documents\Videos
  • %PAL:PortableAppsDir% – the PortableApps.com applications directory, e.g. X:\PortableApps.
  • %USERPROFILE% – a local variable for copying to and from, e.g. C:\Documents and Settings\Username on XP and 2000, C:\Users\Username on Vista.
  • %ALLUSERSPROFILE% – a local variable for copying to and from, e.g. C:\Documents and Settings\All Users on XP and 2000, C:\ProgramData on Vista.
  • %LOCALAPPDATA% – a local variable for copying to and from, e.g. C:\Documents and Settings\Username\Local Settings\Application Data on XP and 2000, C:\Users\Username\AppData\Local on Vista.
  • %APPDATA% – a local variable for copying to and from, e.g. C:\Documents and Settings\Username\Application Data on XP and 2000, C:\Users\Username\AppData\Roaming on Vista.
  • %DOCUMENTS% – a local variable for copying to and from, e.g. C:\Documents and Settings\Username\My Documents on XP and 2000, C:\Users\Username\Documents on Vista.
  • %TEMP% – the temporary directory which the application will be given. If a contained temporary directory is assigned, this will be the assigned one.
  Other local variables are available but will not have forward slash etc. versions made available by the launcher.
• Language variables: these variables are for language switching. Particularly of interest is PAL:LanguageCustom.
  • %PortableApps.comLanguageCode% – e.g. "en-us", "pt", "pt-br"
  • %PortableApps.comLocaleCode2% – e.g. "en", "pt", "pt"
  • %PortableApps.comLocaleCode3% – e.g. "eng", "por", "por"
  • %PortableApps.comLocaleglibc% – e.g. "en_US", "pt", "pt_BR"
  • %PortableApps.comLocaleID% – e.g. "1033", "2070", "1046"
  • %PortableApps.comLocaleWinName% – e.g. "LANG_ENGLISH", "LANG_PORTUGUESE", "LANG_PORTUGUESEBR"
  • %PAL:LanguageCustom% – a custom variable constructed in the Language and LanguageStrings sections.

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.

• Eclipse-based applications: these seem to normally accept a command-line argument to the executable included, to specify the Java location to use. Try setting CommandLineArguments to -vm "%JAVA_HOME%\bin".
• Launch4J-based applications (seems to be most apps): these apps run an executable, which discovers Java from the registry, and run something which creates an executable in the JRE's directory, in a subdirectory launch4j-tmp, which will run the java application. Try running the base application (with a local JRE installation) and then use a program such as Microsoft/SysInternals Process Explorer to look at the command line arguments which it then gets started with. In Process Explorer, right-click on the executable and click "Properties", and copy the execution string.
• Other: panic! ;-) If you come up with any other techniques and/or circumstances where other techniques would be better, please suggest them.