Portable Application Template ============================= Copyright (c) 2007 Karl Loncarek (for the template) Latest version of this template could be downloaded at: http://www.loncarek.de/downloads/PortableApplicationTemplate.zip ABOUT Portable Application Template =================================== This template is intended to help developers or interested users to easily create launchers for applications to make them portable. Those applications could be open source or shareware or even commercial applications. The two latter ones may be interesting for personal use. Thus almost every application could be run from e.g. USB drive no matter what drive letter is used, i.e. without leaving any information or traces on the host PC. HOW TO ADAPT THE TEMPLATE TO YOUR NEEDS ======================================= The key problem of "normal" applications is that they leave traces on the computer that they are running on. Those traces could be registry keys, directories with files, or setting files (e.g. .INI files) themselves. This template is a NSIS source. It uses the same technique as all the applications that could be found on http://portableapps.com . First of all you have to trace what changes are done on your system when installing an application. Personally I use the freeware version of Total Uninstall, but you can use any other tracing software you like. You could also use Sysinternals Filemon or Regmon application for this task. Then list the changed/created folders, files, registry keys in the constants REGKEYS, SETTINGSFILES, SETTINGSDIRS. Separate multiple entries with "||". When you set USEREGKEYSFILE to "TRUE" (default) an existing file e.g. "TestApp.reg" within the data directory will override the settings done in REGKEYS. In this case the parent registry keys within "TestApp.reg" will be processed recursively (all subkeys of the parent keys are saved automatically). Child registry keys are ignored for processing. The file "Registry.reg" has to be of windows regedit format. Also UNICODE format created by regedit version 5 will be read. You could create it with regedit.exe itself or with any other application that saves monitored registry keys in that format (e.g. Total Uninstall). The launcher itself creates files in regedit (version 4) format. Not only the registry keys are used but also the saved settings which then will be the actual portable registry settings. Just take care that the parent registry keys within "TestApp.reg" are directly followed by their child registry keys. Two byte characters within the file registry values are not supported! (But I haven't seen then yet in the registry, therefor no big deal.) The registry values will always be saved within a file "TestApp.reg" within the Data directory. If your application requires write access to the registry (REGKEYS or USEREGKEYSFILE are set) and for some reason you are not allowed to write to it the portable app will abort. If you disabled (or commented) REGKEYS and USEREGKEYSFILE no write checking to teh registry will happen. Folders or files written to the users profile directory are automatically redirected if the constant REDIRECTUSERPROFILE is set to true. So there is no need to add them in the above lists. Beware of applications that launch other applications. Those applications started by your portable program will also use the changed user profile folder. In such a case it is recommended to comment out REDIRECTUSERPROFILE or set it to something different than "TRUE". Then automatic redirection is disabled. If the application to launch does not create those files on the first start then they have to be copied manually into the "UserProfile" directory. The "UserProfile" could be found within your data directory depending on your directory structure (see below). You could hand over some additional default command line parameters to your application to launch. Simply set them within EXEPARMS. Those settings will be overridden by command line parameters given in an INI file. The highest priority have command line parameters given to the launcher when running it. All other settings within the INI or defined in EXEPARMS will then be ignored. On some applications additional changes in e.g. configuration files have to be done, mainly regarding path settings. You have to check if you could use relative paths (the easiest thing as you don't have to do anything else) or if you have to change a drive letter each time you start the launcher. This has to be configured manually and should be done only by intermediate/advanced users who have some knowledge on NSIS. If you want to create a launcher for a commercial/shareware application you have first to take care whether the license of that application allows it. This is in your responsibility. Do not create a package which contains the commercial files as this would be illegal in most cases. Since version 1.9 this template integrates some functions that help you achieving that task. You can simply share the EXE created from this source. All the application and data directories are created automatically. Even if your portable application folder is empty (or at least does not contain the EXE) you will be prompted for a folder that holds your locally installed application and copies all the files wihtin it (inculding subdirectories). When you have set the constant UPXPARMS all .exe and .dll files will be compressed using UPX. You will be prompted for the location of upx.exe. Use the most current version of UPX. Existing settings (defaults files) will be copied when the launcher runs for the first time. You should not uninstall the local application before that. If you want to share your sources with your launcher simple set the constant INSTALLSOURCES to "TRUE". Then those files will be packed into the launcher. The launcher then acts as launcher and installer! The source files will then be copied automatically into the appropriate folders. An existing "readme.txt" will be copied also to the sources. If it does not exist a warning will occur when compiling. Do not worry about this warning, it's more a kind of an information. The same is done with the constant INSTALLDEFAULTS. The only diffrence: It copies some default settings (currently only the file e.g. "TestApp.reg") into the appropriate folders. Also an existing "TestApp.reg" will be installed into the data directory. To enable the application to be used with future versions of portableapps.com menu set the constant PAFCOMPATIBILITY to "TRUE". Then a special directory AppInfo and DefaultData is created automatically if it does not exist yet. In the directory DefaultData the default settings are copied. The icon in AppInfo will be the same as the one used for this launcher. Additionally a file "appinfo.ini" will be extracted. If you haven't included one when compiling this script it will be created out of some constants you could define at the beginning (following directly after PAFCOMPATIBILITY). Filling those constants is optional. Some values are set by default. Beware also of settings which are only possible with administrator rights. It might happen that you don't have adminstrator rights on the host computer. In such a case the application might not run. But you have the possibility to check whether the local user has administrator rights (necessary when e.g. writing to the HKLM registry key). Simply set ADMINREQUIRED to "TRUE". If not required comment it out or set it to something different than "TRUE". With GTKVERSION you could set the version number of the GTK installation your portable application requires. With USEJAVAVERSION you could do the same for JAVA. Java and/or GTK could also be installed into a common files folder which allows multiple applications to use the same or several JAVA/GTK versions. See below at the directory structure on mor information. For your reference: List of possible root keys for the registry value (use short version as much as possible to save space. The list is taken from the NSIS help) HKCC or HKEY_CURRENT_CONFIG HKCR or HKEY_CLASSES_ROOT HKCU or HKEY_CURRENT_USER HKDD or HKEY_DYN_DATA HKLM or HKEY_LOCAL_MACHINE HKPD or HKEY_PERFORMANCE_DATA HKU or HKEY_USERS SHCTX or SHELL_CONTEXT LICENSE OF TEMPLATE =================== Copyright© 2006-2007 Karl Loncarek All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. REQUIREMENTS ============ In order to compile this script with NSIS you need the following Plugins: - NewAdvSplash (http://nsis.sourceforge.net/NewAdvSplash_plug-in) - Registry (http://nsis.sourceforge.net/Registry_plug-in) - FindProc (http://nsis.sourceforge.net/Find_Process_By_Name) - Dialogs (http://nsis.sourceforge.net/Dialogs_plug-in) And of course you need NSIS (http://nsis.sourceforge.net) INSTALLATION / DIRECTORY STRUCTURE ================================== This template uses the same directory structure as John T. Haller did with most of the packages at http://www.portableapps.com to keep some kind of uniformity. Below is used for your applications name. By default the program expects one of these directory structures: (The first version is default and should be preferred for PAF compatibility) +-\CommonFiles\ (optional) | +-\GTK\ | | +-\\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ | +-\\ (optional, files/directories of JRE installation (bin, lib, ...) +-\ <--- Directory with Portable.exe +-\App\ | +-\AppInfo\ (optional, contains configuration for portableapps.com platform, needed for PAF compatibility) | +-\DefaultData\ (optional, contains default settings, needed for PAF compatibility) | +-\\ <--- All files and directories of a local installation | +-\GTK\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ (optional, files/directories of JRE installation (bin, lib, ...) +-\Data\ (optional, will be created automatically when needed) | +-\Settings\ (optional, will be created automatically when needed) | +-\UserProfile\ (optional, will be created automatically when needed) +-\Other\ (optional) <--- contains additional information +-\Source\ (optional) +-\PortableSource\ (optional) <--- contains source of launcher OR +-\ <--- Directory with Portable.exe +-\CommonFiles\ (optional) | +-\GTK\ | | +-\\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ | +-\\ (optional, files/directories of JRE installation (bin, lib, ...) +-\Portable\ +-\App\ | +-\AppInfo\ (optional, contains configuration for portableapps.com platform) | +-\DefaultData\ (optional, contains default settings) | +-\\ <--- All files and directories of a local installation | +-\GTK\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ (optional, files/directories of JRE installation (bin, lib, ...) +-\Data\ (optional, will be created automatically when needed) | +-\Settings\ (optional, will be created automatically when needed) | +-\UserProfile\ (optional, will be created automatically when needed) +-\Other\ (optional) <--- contains additional information +-\Source\ (optional) +-\PortableSource\ (optional) <--- contains source of launcher OR +-\ <--- Directory with Portable.exe +-\PortableApps\ +-\CommonFiles\ (optional) | +-\GTK\ | | +-\\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ | +-\\ (optional, files/directories of JRE installation (bin, lib, ...) +-\Portable\ +-\App\ | +-\AppInfo\ (optional, contains configuration for portableapps.com platform) | +-\DefaultData\ (optional, contains default settings) | +-\\ <--- All files and directories of a local installation | +-\GTK\ (optional, files/directories of GTK installation (bin, lib, ...) | +-\JAVA\ (optional, files/directories of JRE installation (bin, lib, ...) +-\Data\ (optional, will be created automatically when needed) | +-\Settings\ (optional, will be created automatically when needed) | +-\UserProfile\ (optional, will be created automatically when needed) +-\Other\ (optional) <--- contains additional information +-\Source\ (optional) +-\PortableSource\ (optional) <--- contains source of launcher Which directory will be scanned for the JAVA/GTK version that will be used (highest priority first): A. "App\JAVA" or "App\GTK" B. "CommonFiles\JAVA\" or "CommonFiles\GTK\" C. "CommonFiles\JAVA" or "CommonFiles\GTK" D. on the host computer installed JAVA or GTK Remarks: When there is no version within A or B the version within C will be used. It is highly recommended to use B as far as possible if you want to share it with other portable applications. If your application does not require a special GTK/JAVA version it is recommended to use C with the newest available version of GTK/JAVA. should be only the version number e.g. "1.6.0_01", otherwise it won't be found. A message will appear when the hosts JAVA/GTK will be used. It can be used in other directory configurations by including the Portable.INI in the same directory as the launcher Portable.EXE. Details for the configuration settings in the INI files could be found below. The INI file may also be placed in the subdirectories "Portable", "PortableApps\Portable", "Apps\Portable", or "Data\Portable". Those directories are relative to the location of the Portable.EXE file. All paths given in the INI-file should be relative to the location of Portable.EXE. .INI FILE CONFIGURATION OPTIONS =============================== The launcher will look for an .INI file within it's directory. If you are happy with the default options, you won't need it. The INI file is formatted as follows (Below is used for your applications name.): [Portable] ProgramExecutable=.exe ProgramParameters= ProgramDirectory=App\ DataDirectory=Data SplashScreen=enabled ExtractSources=TRUE JAVAVersion=1.6.0_01 Required entries are ProgramDirectory and DataDirectory. If others are missing or empty the default values will be used. All paths provided should be RELATIVE to the "Portable.exe". ProgramExecutable: Allows to launch a different EXE file of your application ProgramParameters: Additonal parameters that should be used when launching the application. This setting overrides te defaults. ProgramDirectory: The path to the EXE file of your application that should be launched. But this is only the path, thus must not contain a filename. DataDirectory: The path where all settings should be stored (registry keys and the above subdirectories) SplashScreen: Controls whether the splash screen is showed upon start of the launcher if one is defined by default. Anything but "enabled" disables it. ExtractSources: Controls whether the launcher acts also as installer, i.e. will install sources and readme.txt (or other files) if they do not exist yet. Anything else than TRUE will not install/extract any files GTKVersion: Tells the launcher which version of GTk should be used. See above for version handling. JAVAVersion: Tells the launcher which version of JAVA should be used. Well in fact it's the JRE version. See above for version handling. CURRENT LIMITATIONS =================== WRITE ACCESS REQUIRED - The data directory must be writeable on your drive (e.g. USB drive) as all the settings and configurations are saved there. HISTORY ======= 1.0 - First release: Based on Quickport NSIS template developed by Deuce added capability to backup multiple files/registry keys 1.1 - INI files and some default directory structures are supported now. 1.2 - added sleep time when deleting registry keys; adopted new directory structure as recently used by John (AppPortable instead of PortableApp) 1.3 - fixed a bug 1.4 - added handling for second launch; some bugfixes 1.5 - complete rewrite for easier understanding of the source; original files/directories are now renamed instead of copied; error message when backup files/folders exist; Readme now included at end of the script 1.6 - no need to define any folder/file within SETTINGSFILES or SETTINGSDIRS that is normally stored within the users profile folder. Those folders/files will now be stored on the portable drive automatically (i.e. redirected)! 1.7 - added creation of other (maybe missing) data folders; made user profile redirection switchable, documentation updates 1.8 - added check whether user has local administrator rights; removed "Unused WordFunc" warning during compile time; optimized compiling when commenting out some constants was forgotten ( to get smallest EXE you should really comment out); bugfixes 1.9 - when no directories are found a default directory structure is created; when no EXE is found you are asked to select a folder from which to copy the files; added possibility to integrate the sources if you want to distribute only the exe, e.g. when creating commercial/shareware applications launchers -> launcher is an installer at the same time; added switch for INI file to disable that behaviour; optimzed source code 2.0 - registry keys are now stored in one single file even with multiple registry keys (not compatible to previous versions); Overrides setting of REGKEYS if USEREGKEYSFILE is "TRUE" and reads registry keys to process from file "Registry.reg"; Added "Registry.reg" to source installation; Added default command line parameters; removed one possible directroy structure (which did not make sense); added GTK and JAVA (or better JRE) support, adjustable via INI; automatic detection of a "CommonFiles" directory; some code cleanup 2.1 - minor bugfixes; Added option to delete registry keys before applying own (saved) registry keys; set default Execution Level to user (for VISTA) 2.2 - fixed newadvsplash DLL being left in the temp directory (forgot cleanup); changed way of restoring the registry keys (now uses "regedit /s"); removed sleeps again (commented them out, just in case...); removed /D=2 switch when saving registry keys 2.3 - added a lot of "" around the variables to avoid errors when leaving variables empty instead of commenting them out; Cleaned also errors before doing regsitry stuff; added error messages when something goes wrong when saving registry keys 2.4 - added extraction/creation of AppInfo folder and content to be PAF compatible (see portableapps.com); added some error handling; added capability to read also Registry.reg in UNICODE format; added more options for creating a standalone launcher/installer 2.5 - changed cleanup of newadvsplash to reflect changes to newest version; fixed some wording in docs; fixed commandline parameters being given as one string 2.6 - added additional LONGAPP constant for descriptive fields; Changed generation of file appinfo.ini to be compliant to draft 2 of PAF spec; added checking of registry writing capabilities and abort if not possible; registry keys are now stored into file ".reg"; added some missing freeing of registry dll;