Developer's Documentation

The first part of this article will teach you how-to build Cygwin Portable yourself. If you goal is to help with the development efforts, you should instead get the source code and run setup.exe as described in the ... section below. You will still need to setup a development environment if you want to be able to build installer for testing purposes.

Setting up a PortableApps development environment

It is optional but strongly recommanded to use virtualization software such as Virtual Box or VMWare Workstation and to use a Windows virtual machine for testing / development purposes. That will allow you to easily rollback to a previous state if anything goes wrong.

You will need the following tools for PortableApps development :

Resources

You should read and understand the PortableApps developer's litterature before attempting to build your first PortableApps. You will find the Portable Apps documentation and some tools here : http://portableapps.com/development.

A while ago, About.com published a series of hands-on tutorials teaching how to create portable applications. You can still get those tutorials using Internet WayBack Machine but be aware that they are probably outdated :

Install PortableApps.com Plateform

  1. Insert your USB flash drive in your PC
  2. Double-click on PortableApps.com_Plateform_Setup_10.x.x.exe application
  3. Select the installer language, then click OK
  4. On the welcome screen, click Next
  5. Read the license agreement, click I Agree to accept the terms or Cancel to refuse (and abort the installation)
  6. Choose your install location (it should be the root directory on your usb flash drive, ex: G:\). Then press Install.
  7. On last screen, uncheck "Lauch PortableApps.com Platform" if you don't want to launch the PortableApps menu. Otherwise, leave the default and click Finish

If you have selected the "Launch PortableApps.com Plateform", you should see the PortableApps menu appear shortly after the installer closes. Your USB Flash Drive is now ready to receive your first portable applications.

Preparing the directory structure

If you choose to build Cygwin Portable yourself instead of cloning the source code, there is some preparation steps to do before you can build a PortableApps.com Installer. The simpler way is to use PortableApps.com Application Template as a starting point. We suggest that you unzip the content inside a directory on a local hard drive (ex: C:\FAKE_USB) to speed up transfer and execution times during development.

Once you have extracted the Application Template, you should have a directory structure similar to this one :

  • Start the customization by renaming AppNamePortable directory into CygwinPortable
  • Inside the CygwinPortable directory, update help.html with Cygwin Portable info
  • Create a new directory called Cygwin inside the App directory
  • Download the latest setup.exe from Cygwin website inside the App\Cygwin directory
  • Copy appicon.ico into App\AppInfo directory
  • Customize the splash screen inside App\AppInfo\Launcher directory
  • Don't alter anything within the Other directory.

Setting up some .ini files

Before you can run the PortableApps.com Launcher Generator over the directory to build the launcher you have create three .ini files first :

  1. AppCompactor.ini : to give some instructions to the PortableApps.com Compactor
  2. AppInfo.ini : ...
  3. Installer.ini : need by PortableApps.com Launcher Generator to create a .paf installer

We will now present the content of each file.

AppCompactor.ini

[PortableApps.comAppCompactor]
FilesExcluded=msvcm90.dll|msvcp90.dll|mscvr90.dll
AdditionalExtensionsExcluded=pyd|irc
AdditionalExtensionsIncluded=example|beta

AppCompactor.ini file is optional. Under the PortableApps.comAppCompactor section, you will list the files the compactor must ignore : by filenames (FilesExcluded) or by extension (AdditionalExtensionExcluded). You can also force the AppCompator to process certain extensions (AdditionalExtensionsIncluded). For more details about PortableApps.com AppCompactor, visit: http://portableapps.com/appcompactor.

AppInfo.ini

[Formt]
Type=PortableApps.comFormat
Version=3.0

[Details]
Name=Cygwin Portable
AppID=CygwinPortable
Publisher=Symbiosoft & PortableApps.com
Homepage=Symbiosoft.net/CygwinPortable
Category=Utilities
Description=Cygwin Portable is a Unix-like command interface.
Language=Multilingual
Trademarks=
InstallType=

[License]
Shareable=true
OpenSource=true
Freeware=true
CommercialUse=true
EULAVersion=1

[Version]
PackageVersion=0.3.1.0
DisplayVersion=0.3 Release 1

[SpecialPaths]
Plugins=NONE

[Dependencies]
UsesJava=no
UsesDotNetVersion=

[Activate]
Registry = true

[RegistryKeys]
cygwin_portable=HKLU\Software\Cygwin

[Control]
Icons=1
Start=CygwinPortable.exe
ExtractIcon=App\Cygwin\Cygwin-Setup.exe

[Associations]
FileTypes=html,htm,xhtml,xhtm,xht,shtml
FileTypeCommandLine=/Open=%1
FileTypeCommandLine-extension=/OpenExtension=%1
Protocols=http,https,gtp,gopher
ProtocolCommandLine=--protocolhandler=%1
ProtocolCommandLine-protocol=--http:%1
SendTo=true
SendToCommandLine=-multiplefiles "%1" 
Shell=true
ShellCommand=/idlist,%I,%L

[FileTypeIcons]
swf=video
ttp=custom
qwe=app

Installer.ini

[Source]
IncludeInstallerSource=true

[DownloadFile]
DownloadURL=http://cygwin.com/setup.exe
DownloadName=setup.exe
DownloadFilename=setup.exe
DownloadMD5=9509465843121f48577d7476bc1f1e41
DownloadTo=App\Cygwin
AdditionalInstallSize=692

Installer.ini gives instructions to the PortableApps.com Launcher Generator on how to build CygwinPortable installer (aka: .paf installer).

Generating a Launcher EXE for setup.exe

NOTE: Work in progress.

The launcher generator needs an .exe at the top level directory of your portableapp structure to be able to run. We use the free application TBD to do this.

Run TBD and select the output .exe name to be : CygwinSetup.exe

For the command line, select the following :

.\App\Cygwin\setup.exe --download --site http://example.com --root .\App\Cygwin --quiet-mode --no-shortcuts --no-startmenu --no-desktop --local-package-dir .\Packages

TODO: Modify setup.exe source code to support relative path and to write in .ini file instead of the registry.

Installer creation using PortableAppls.com Launcher Generator

Insert your USB flash drive. You can also tart the PortableApps.com menu by running start.exe at your USB flash drive root (ex: G:\Start.exe) in case it doesn't autostart.

Launch the PortableApps.com Installer from the PortableApps.com menu.

  1. On the welcome screen, click Next
  2. Select the folder where you create the directory structure for Cygwin Portable (in our example : C:\FAKE_USB\CygwinPortable. Check the box Interactive Mode to be prompt about missing information. Then press Go.
  3. If any error occurs, you will see a dialog similar to the one below. Check the log and correct the error. Then rerun the installer again.
    #

app_template_dir_structure.png (3.5 kB) Etienne Savard, 05/01/2012 05:05 pm

appicon.ico (153.4 kB) Etienne Savard, 05/02/2012 05:14 pm

step1_folder_selection.png (15.5 kB) Etienne Savard, 05/04/2012 11:53 pm

step2_error_occured.png (29.5 kB) Etienne Savard, 05/04/2012 11:53 pm