Building custom QGIS installers for Windows

A client wanted their own custom QGIS build which included some patches and a selection of additional python plugins that were to be available from point of installation. Additionally we wanted to brand the installer with their logo and the splash screen too so that users realise they are using a custom build. The actual build process under windows using msvc is fairly
straightforward (see the INSTALL document in the root of QGIS source tree) so I won’t discuss that here. Rather I am going to show you an approach for building such a custom installer.

Creating a branch

Since we live in git land now, the first thing I am going to do is create a branch for my client’s customisations. If any changes in that branch are useful to the master branch,  I will cherry pick them across later using git cherry-pick.

git checkout -b sansa-branch

Now apply all your code level customisations to the sources in your branch and go ahead and compile everything to make sure it builds, links and installs.

Customising the installer sidebars

The installer sidebars can be altered in the gimp – simply edit :

ms-windows/Installer-Files/sidelogomaster.xcf.bz2

You can open it directly (no need to untar it first). Then use the gimp project to create new versions of:

ms-windows/Installer-Files/WelcomeFinishPage.bmp
 ms-windows/Installer-Files/UnWelcomeFinishPage.bmp

Make sure to keep the image dimensions the same. Those can be commited to your local branch:

git commit -m "Customised sidebar images" \
ms-windows/Installer-Files/WelcomeFinishPage.bmp \
ms-windows/Installer-Files/UnWelcomeFinishPage.bmp

Our custom installer running with new sidebar images

Customising the Splash Screen

The splash screen master can be found here:

images/splash/splash.xcf.bz2

Once again, you can open this directly in the gimp and edit it according to your needs. When you are ready to save the final splash, resize it to 600×287 pixels first. Be careful to also preserve the
transparency in the corners properly or otherwise you will see artifacts when you start QGIS which won’t look nice. The saved splash should be saved as:

images/splash/splash.png

Making a splash: Our custom QGIS build's splash screen

Creating a package tree

There are two ways you can go here…

Way 1:

You can take an existing build of QGIS, extract it under windows, copy your build outputs from msvc over the apps/qgis or apps/qgis-dev  directory and then copy the whole lot over to linux. When it is in your linux box, place it under:

ms-windows/osgeo4w/unpacked

In this case the contents under unpacked should be what was originally under your c:\Program Files\Quantum GIS directory.

One important thing to note is that there are various batch files that are run after QGIS installs. After they are run they are renamed to have a .done extension after them. We need to remove this extension so that they get run after your custom QGIS installer has run. Here are a few lines of bash that do just that:

cd ms-windows
cd osgeo4w
cd unpacked
mv postinstall.bat.done
postinstall.bat
cd etc
for FILE in *.done; do mv $FILE \
$(basename $FILE .done); done
cd ../../../..

Way 2:

You can run the creatensis.pl script like this and specify a shortname e.g. qgis or qgis-dev.

cd osgeo4w
./creatensis.pl --shortname=qgis

It will take a while to run if you have a slow connection like I do, After it is done, place the build outputs from msvc into the file tree at:

unpacked/apps/qgis

So in my case, msvc installed the QGIS I built into c:\program files\qgis1.7.0 – which now becomes the unpacked/apps/qgis directory.

Understanding the batch files

Another important thing to understand is how the various batch files are called within your package tree. Immediately after installation, the postinstall.bat program is run. Its main job is to set a bunch of  environment variables and then call a some subsidiary scripts living in the etc/postinstall directory. One common issue is that you create your installer, install it on a windows machine, and then nothing happens when you click the icon. Usually this will be caused by a mismatch between you qgis launcher script name and the shortcut that was created to call it. The naming convention used in osgeo4w is to install the current stable version of qgis under apps/qgis and the latest development build under apps/qgis-dev. Typically you will only want to ship one or the other to your users – that is an installer based on the current stable release, or one based on the current QGIS trunk. Either way what is important is that everything gets named consistently. For this article, I will use a shortname of ‘qgis’ throughout. So you should check your postinstall.bat to make sure that its calling an appropriate qgis postinstall script. For example mine looked like this:

echo Running postinstall
qgis-dev.bat...

%COMSPEC% /c
etc\postinstall\qgis-dev.bat>>postinstall.log 2>&1
ren etc\postinstall\qgis-dev.bat
qgis-dev.bat.done>>postinstall.log 2>&1

But I am standardising on using apps/qgis for my qgis directory, so I need to change it to look like this:

echo Running postinstall
qgis-dev.bat...

%COMSPEC% /c
etc\postinstall\qgis.bat>>postinstall.log 2>&1
ren etc\postinstall\qgis.bat
qgis.bat.done>>postinstall.log 2>&1

Similarly you need to check in etc/postinstall to make sure that the qgis.bat scrip referred to here exists:

[unpacked] ls etc/postinstall/

grass.bat  msvcrt.bat msys.bat  openssl.bat  pyqt4.bat  qgis-dev.bat
qt4-libs.bat  sip.bat

You can see once again the name doesn’t gel, so I will rename mine to ’qgis.bat’:

mv etc/postinstall/qgis-dev.bat
etc/postinstall/qgis.bat

Lastly, are the actual contents of that batch file consistent?

textreplace -std -t
bin\qgis-dev.bat
mkdir "%OSGEO4W_STARTMENU%"

xxmklink "%OSGEO4W_STARTMENU%\Quantum GIS (1.7.0).lnk"  ...
"%OSGEO4W_ROOT%\bin\qgis-dev.bat"
" " \ "Quantum GIS - Desktop GIS (1.7.0)"  ...
 1 "%OSGEO4W_ROOT%\apps\qgis-dev\icons\QGIS.ico"

xxmklink "%ALLUSERSPROFILE%\Desktop\Quantum GIS (1.7.0).lnk" ...
"%OSGEO4W_ROOT%\bin\qgis-dev.bat"
" " \ "Quantum GIS - Desktop GIS (1.7.0)" ...
1 "%OSGEO4W_ROOT%\apps\qgis-dev\icons\QGIS.ico"

set O4W_ROOT=%OSGEO4W_ROOT%
set OSGEO4W_ROOT=%OSGEO4W_ROOT:\=\\%

textreplace -std -t
"%O4W_ROOT%\apps\qgis-dev\bin\qgis.reg"

"%WINDIR%\regedit" /s
"%O4W_ROOT%\apps\qgis-dev\bin\qgis.reg"

They are not so I will update them to correct that:

textreplace -std -t bin\qgis.bat
 
mkdir "%OSGEO4W_STARTMENU%"

xxmklink

"%OSGEO4W_STARTMENU%\Quantum GIS (1.7.0).lnk"   ...
"%OSGEO4W_ROOT%\bin\qgis.bat" " " ...
"Quantum GIS - Desktop GIS (1.7.0)" 1  ...
"%OSGEO4W_ROOT%\apps\qgis\icons\QGIS.ico"

xxmklink "%ALLUSERSPROFILE%\Desktop\Quantum GIS (1.7.0).lnk" \
"%OSGEO4W_ROOT%\bin\qgis.bat" " " ...
 "Quantum GIS - Desktop GIS (1.7.0)" ...
1 "%OSGEO4W_ROOT%\apps\qgis\icons\QGIS.ico" 

 
set O4W_ROOT=%OSGEO4W_ROOT%
set OSGEO4W_ROOT=%OSGEO4W_ROOT:\=\\%

textreplace -std -t
"%O4W_ROOT%\apps\qgis\bin\qgis.reg"
"%WINDIR%\regedit" /s
"%O4W_ROOT%\apps\qgis\bin\qgis.reg"

Whether or not you actually need to tweak these scripts is largely dependent on your starting point. I can only say I had lots of issues because I had mismatches between references to qgis and qgis-dev to it is useful to understand the sequence of events. The last script we edited will ultimately create the shortcut icon on the users desktop and menu system.

You also need to check that the preremove scripts are similarly consistent, so check these scripts are there and internally correct:

preremove.bat
etc/preremove/qgis-dev.bat

Lastly you should remove bin/qgis.bat if it is present and check that bin/qgis.bat.templ is there. If it is named as qgis-dev.bat.templ rather than qgis then rename accordingly to qgis.bat.templ. Now check inside this script to make sure everything is consistent there too. The following diagram describes these processes visually.

How batch files are used in QGIS windows edition

Customising what gets shipped.

Here is the opportunity to add some customisations to the installer contents. For example I wanted to include ecw and sid support in my  installer, as well as a bunch of the nicer python plugins that are out there. Simply copy the files you need into the correct place in the unpacked directory tree. For example, I took a range of python plugins from my ~/.qgis/python/plugins/ directory and placed them in:

unpacked/apps/qgis/python/plugins/

e.g.

cd unpacked/apps/qgis/python/plugins/
cp -r ~/.qgis/python/plugins/bcccoltbl1/ .
cp -r ~/.qgis/python/plugins/cadtools/ .
cp -r ~/.qgis/python/plugins/metatools/ .
cp -r ~/.qgis/python/plugins/numericalDigitize/ .
cp -r ~/.qgis/python/plugins/numericalVertexEdit .
cp -r ~/.qgis/python/plugins/openlayers .
cp -r ~/.qgis/python/plugins/openlayersov .
cp -r ~/.qgis/python/plugins/postgis_manager .
cp -r ~/.qgis/python/plugins/QGISFileBrowser .
cp -r ~/.qgis/python/plugins/qgsAffine .
cp -r ~/.qgis/python/plugins/rawrasterfileimport .
cp -r ~/.qgis/python/plugins/shadedrelief .
cp -r ~/.qgis/python/plugins/tablemanager .
cp -r ~/.qgis/python/plugins/topocolour .
cp -r ~/.qgis/python/plugins/valuetool .

Building an installer

Now we get to the part you have been waiting for – building an installer. There is a convenience script here that will do most of the work for you:

<qgis source tree root>/ms-windows/quickpackage.sh

Before you run the script, you should check that the shortname inside this file matches the one we used in the steps above (in this case ’qgis’ rather than ‘qgis-dev’).

makensis \
-DVERSION_NUMBER='1.7.0' \
-DVERSION_NAME='Wroclaw' \
-DSVN_REVISION='0' \
-DQGIS_BASE='Quantum GIS' \
-DINSTALLER_NAME='QGIS-1-7-0-Sansa-Edition-Setup.exe' \
-DDISPLAYED_NAME='Quantum GIS 1.7.0' \
-DBINARY_REVISION=1 \
-DINSTALLER_TYPE=OSGeo4W \
-DPACKAGE_FOLDER=osgeo4w/unpacked \
-DSHORTNAME=qgis \
QGIS-Installer.nsi

You can also use the opportunity to customise the name of the installer and the name of the version and release number of QGIS if you like  (though I don’t recommend that latter two much as they provide a good point of reference to users). When you are finished, simply run the quickpackage script and wait a while:

 ./quickpackage.sh

After a few minutes the script will come to an end and you should have a nice shiny new QGIS-1-7-0-Sansa-Edition-Setup.exe (or whatever you called it) created in the ms-windows directory. Now its simple a matter of installing it in a clean windows machine to test it, running it through a virus checker and then putting it online for people to enjoy.

Our custom QGIS showing the modified version name in the title bar

Ethics

With all the flexibility that QGIS offers, being open source and ‘out there’ for anyone to hack on, its easy to take what the project provides and rebrand it substantially:

• you can create a custom icon theme
• you can remove unwanted user interface elements
• you can replace help text, about text etc
• you can rename the application itself to something else
• you can change the application icon

and so on and so on. One thing you may not do is claim the fundamental work to be your own. Any time you make a publically available custom version of QGIS, be sure to remember that you need to redistribute the full source code (including all your customisations) with it in order to comply with the letter and spirit of the GPL.

One final thing to mention is that at the Lisbon hackfest, Martin Dobias and Radim Blazek demonstrated a really slick and easy to use framework for creating stripped down versions of the QGIS user interface. It introduces the idea of profiles that you can nominate at application start up. So a school teacher may for example provide her students with just the few icons and tools they need to complete a particular exercise. Look out for that in a future version of QGIS I guess…..

If anyone is interested in having custom branded versions of QGIS for use within their organisation, we (linfiniti) will be happy to help - just pop us an email.