[[TOC]]

= Setup Development =

== Background ==

The OSGeo4W GUI Installer is derived from the same code that the Cygwin installer uses (Cygwin is a Unix emulator on Windows).  More information about the original Cygwin code can be found at:

  http://cygwin.com/setup.html

== Building your own setup.exe ==

1. Download Cygwin installer

   http://www.cygwin.com/setup.exe

2. Install Cygwin

   * in the installer, no need to change anything (press <Next> until you must choose a download site)
   * in the '''Choose a Download Site''' window, highlight a URL that appears close to your country location, and press <Next>
   * in the '''Select Packages''' window, make sure to install the following packages (click on "Skip" until you see a version number beside the package name)
     * Devel
       * autoconf
       * automake
       * bison
       * flex
       * gcc-mingw-g++
       * libtool
       * make
     * Mingw
       * mingw-zlib
       * mingw-bzip2
     * Utils
       * upx
     * also install all packages that are dependencies of the above ones (the cygwin installer should have automatically selected them for you)
     * after selecting the required packages, press <Next> to begin installing
   * you should now have a Cygwin shortcut on your desktop
   * if you chose default locations, if you open Windows Explorer you will see that Cygwin exists at ''C:\cygwin''

3. If you don't have Subversion installed yet:

   * download and install a fancy GUI for SVN (such as http://tortoisesvn.tigris.org/), or 
   * use a commandline SVN client such as from [http://subversion.tigris.org/files/documents/15/45222/svn-win32-1.5.6.zip here]  
     * copy the contents of that zip into your Program Files directory
     * add 'C:\Program Files\svn-win32-1.5.6\bin' to your PATH environment variable
     * open a new Command/Cygwin window, and test that SVN is found by executing:
       {{{
         svn --help
       }}}

4. Checkout a local copy of the OSGeo4W setup code into your Cygwin home directory

   * using SVN commandline:
     * double click the "Cygwin" shortcut on your desktop
     * execute:
       * svn co https://svn.osgeo.org/osgeo4w/trunk/setup setup
     * you should now have a "setup" folder in your cygwin home directory, containing the OSGeo4W setup code
   * using SVN GUI:
     * checkout https://svn.osgeo.org/osgeo4w/trunk/setup to your Cygwin home directory (C:\cygwin\home\jeff)

5. Now you are ready to build the OSGeo4W setup.exe

   * double-click the Cygwin desktop shortcut to start Cygwin
   * execute the following:
     * cd setup
     * ./bootstrap.sh
     * ./fr_configure
     * make
       (this should produce a setup.exe executable in the setup directory, that is approximately 9 MB in size)
     * make clean (if necessary)   
   * if you are building a release version of osgeo4w-setup.exe (meaning it will be uploaded to the OSGeo [http://download.osgeo.org/osgeo4w/ download server]):
     1. remove debugging symbols with the cygwin command:
       {{{
           strip -s setup.exe
       }}}
       the file should now be around a MB in size
     2. compress the exe using the UPX utility, with the cygwin command:
       {{{
           upx -9 setup.exe
       }}}
       the file should now be around 400 KB in size
       * if the UPX command returns the following error:
         {{{
             CantPackException: TLS callbacks are not supported
         }}}
         * UPX does not support executables with .tls sections, and apparently for mingw-runtime version 3.18 TLS callbacks are default (see [http://www.cygwin.com/ml/cygwin-apps/2010-03/msg00075.html cygwin-apps discussion]
         * so the temporary workaround is:
           * use the cygwin installer to revert to the mingw-runtime version 3.17 (inside the /Libs section of the package installer)

== Debugging the Setup code ==

1. With the Cygwin installer, install the following package:
   * Devel
     * gdb (the GNU debugger)

2. Follow the steps in http://www.cygwin.com/cygwin-ug-net/gdb.html

   * make sure you right-click on the Cygwin shortcut and 'run as Administrator' before using gdb
   * make sure things are also built with ''-g'' and no optimization

== Uploading a new setup.exe to the Download Server ==

The fr_upload.sh and package.sh scripts should also be helpful to get the results to the OSGeo4W download server.  Note that the executable needs to be updated in two places when new versions are uploaded.  One is the http://download.osgeo.org/osgeo4w/osgeo4w-setup.exe binary and the other is the packaged copy in http://download.osgeo.org/osgeo4w/release/setup. 

== Adding Express Packages ==

To add a new express install package follow these steps:

 * Add a symbolic define for the new package in resource.h in the section at the end (IDC_PKG_OPENEV, etc). 
 * Add a new entry on the express package dialog defined in res.rc (search for IDC_PKG_OPENEV).  Make sure the positioning does not overlap other packages. 
 * Add the new package to the !PackageControlPair[] array in express_package.cc file, matching the IDC_PKG_ constant with the name of the package.