Welcome to the developer documentation for Portable GIS¶

Portable GIS is a set of open source GIS programs designed to be run from a USB stick, in windows, with no installation or configuration. It’s hosted at portablegis.xyz, where you will also find details of the latest versions of the packages included. This documentation describes how to set up your own build environment for Portable GIS, from the repository at gitlab.com/archaeogeek/portable-gis. Note that currently there are only instructions for building a development environment in windows.

Warning¶

This documentation is a work in progress, as is the source repository.

For problems with the documentation, please submit an issue at gitlab.com/archaeogeek/portable-gis-docs/issues
For problems with the source code then please submit an issue at gitlab.com/archaeogeek/portable-gis/issues.

Getting Started¶

This document will show you how to set up the build environment for creating an edition of Portable GIS from the component software. Unfortunately at present it’s windows only but if that changes, so much the better!

Required Programmes¶

Git
AutoIT (to build menu)
Universal Extractor (to extract executables)
7-zip (for when Universal Extractor doesn’t work)
NSIS (to build installer)

Folder Structure¶

|-- raw_docs
        |-- pgis_docs.odt
|-- usbgis
        |-- apps
                |-- ...
        |-- data
                |-- ...
        |-- docs
                |-- changelog.txt
                |-- license.txt
                |-- pgis_docs.pdf
|--your.ico
|--your.bmp
|--portablegis_readme.txt
|--yourinstaller.nsi
|--yourmenu.au3
|--yourmenu.exe
|--yourinstaller.exe

App Preparation¶

Apps that require the portable version¶

Geany¶

Download a copy of Portable Geany from portableapps.com/apps/development/geany_portable and place the executable into the apps/geany folder.

Firefox¶

Download a copy of Portable Firefox from portableapps.com/apps/internet/firefox_portable and place the executable into the apps/firefox folder.

PDF Reader¶

Download a copy of Portable Foxit Reader from portableapps.com/apps/office/foxit_reader_portable and place the executable into the apps/pdfreader folder.

Apps that can be included without modification¶

ms4w¶

Download the zip file of ms4w from ms4w.com. Extract the ms4w folder from within the download and place it in the apps folder of your Portable GIS installation.

ogr2osm¶

Download the zip file of ogr2osm from github.com/pnorman/ogr2osm. Extract the resulting folder into the apps folder of your Portable GIS installation, ensuring it is named ogr2osm. See wiki.openstreetmap.org/wiki/Ogr2osm for usage. The python bindings are included.

Loader¶

Download a zip file of Loader from github.com/AstunTechnology/Loader. Place the Loader folder into the apps folder in your Portable GIS directory.

Apps that require minor modification¶

Geoserver¶

Download the Platform Independent Binary (version 2.8.3) from ‘geoserver.org’_ and extract the contents into the apps folder, in a directory called geoserver. Copy the contents of the geoserver directory from the Portable GIS repository into the same folder, overwriting as necessary.

Python 2.7¶

Portable Python is no longer being developed so simply take the python27 folder from the Portable GIS repository.

Apps that require a bit more work¶

PostgreSQL and PostGIS¶

UNTESTED!!!

PostgreSQL¶

Download the zip file (32bit) for PostgreSQL 9.3 from postgresql.org (the section for “Advanced Users”).

Extract this to the apps folder and rename it postgresql93.

Create a user on your pc called pgis with the password pgis and open a command prompt as that user. Change directory to the apps\postgresql93\bin directory and initialise the db in the following manner:

> initdb.exe --pgdata=..\PGDATA --username=pgis --locale=UTF8 --xlogdir=..\..\..\data\pg93_log

Copy the files from the postgresql93 folder in the Portable GIS repository into your postgresql93 folder, overwriting as necessary.

(At this point you should probably transfer your build to an actual USB stick so you can start postgresql using the batch file start_pgsql.bat and deal with any error messages)

PostGIS¶

Download the zip file (currently the 2.1 version) from download.osgeo.org and extract the contents into the postgresql93 directory, overwriting if needed.

Create a new template database (called, eg template_postgis) and run spatial_ref_sys.sql and postgis.sql on that database to make it spatial.

QGIS¶

Download 32bit stand-alone qgis installer (version 2.14) from the QGIS Download Site and extract the executable using uniextract or similar. Extract the contects of $OUTPUTDIR into the qgis2 folder, and then apply the files from the qgis2 folder in the Portable GIS repository to the same location, over-writing as necessary.

Java 8 jdk¶

Oracle’s jdk8 is provided in the Portable GIS repository but if you wish to build your own follow the instructions below. These instructions originally came from brucalipto.org and are reproduced here in case that site is no longer available.

Download a copy of the Windows 32bit (X86) jdk version 8 executable from oracle
Open the downloaded executable with 7-zip, and the extract the tools.zip file inside to a tools folder.
At this point you should have the following folder structure jdk_8\tools
Open a command prompt inside the tools directory and run the following command, substituting the correct drive letter:
```
> for /r %x in (*.pack) do C:\jdk_8\tools\bin\unpack200 "%x" "%x.jar"
```

Find and rename all the .pack.jar files present in the tools folder and subfolders:

> dir /B /S *.pack.jar
C:\jdk_8\tools\jre\lib\charsets.pack.jar
C:\jdk_8\tools\jre\lib\deploy.pack.jar
C:\jdk_8\tools\jre\lib\javaws.pack.jar
C:\jdk_8\tools\jre\lib\jsse.pack.jar
C:\jdk_8\tools\jre\lib\plugin.pack.jar
C:\jdk_8\tools\jre\lib\rt.pack.jar
C:\jdk_8\tools\jre\lib\ext\jfxrt.pack.jar
C:\jdk_8\tools\jre\lib\ext\localedata.pack.jar
C:\jdk_8\tools\lib\tools.pack.jar

> ren C:\jdk_8\tools\jre\lib\charsets.pack.jar charsets.jar
> ren C:\jdk_8\tools\jre\lib\deploy.pack.jar deploy.jar
> ren C:\jdk_8\tools\jre\lib\javaws.pack.jar javaws.jar
> ren C:\jdk_8\tools\jre\lib\jsse.pack.jar jsse.jar
> ren C:\jdk_8\tools\jre\lib\plugin.pack.jar plugin.jar
> ren C:\jdk_8\tools\jre\lib\rt.pack.jar rt.jar
> ren C:\jdk_8\tools\jre\lib\ext\jfxrt.pack.jar jfxrt.jar
> ren C:\jdk_8\tools\jre\lib\ext\localedata.pack.jar localedata.jar
> ren C:\jdk_8\tools\lib\tools.pack.jar tools.jar

Test this has worked OK:

C:\jdk_8\tools\bin\java -version
java version "1.8.0-ea"
Java(TM) SE Runtime Environment (build 1.8.0-ea-b121)
Java HotSpot(TM) Client VM (build 25.0-b63, mixed mode)

Menu and Install File¶

Menu and Installer¶

Menu¶

The Portable GIS menu is built with AutoIT. Yes I know there are probably better things to use these days but if it ain’t broke…

Download AutoIT AutoIT and install on your local machine.

The Portable GIS menu source file (portablegis_xxx.au3) can be found in the in the Portable GIS repository and should be placed in the root of your Portable GIS installation, like so:

|-- raw_docs
|-- usbgis
        |-- apps
        |-- data
        |-- docs
|-- your.ico
|-- your.bmp
|-- portablegis_readme.txt
|-- yourinstaller.nsi
|-- yourmenu.au3 <-- Here
|-- yourmenu.exe
|-- yourinstaller.exe

The AutoIT syntax documentation can be found at www.autoitscript.com/autoit3/docs. Recent versions of the software include a syntax checker (Au3Check).

To use with Portable GIS the menu source code must be compiled into a standalone executable (.exe). Use Aut2Exe for this (available from your start menu) and supply an icon (.ico) file.

Compile for 32bit systems just to be on the safe side.

Installer¶

The Portable GIS installer is built with nsis. Download the latest version and install on your local machine.

The Portable GIS installer source file (nsis_installer_xxx.nsi) can be found in the in the Portable GIS repository and should be placed in the root of your Portable GIS installation, like so:

|-- raw_docs
|-- usbgis
        |-- apps
        |-- data
        |-- docs
|-- your.ico
|-- your.bmp
|-- portablegis_readme.txt
|-- yourinstaller.nsi <-- Here
|-- yourmenu.au3
|-- yourmenu.exe
|-- yourinstaller.exe

The nsis syntax documentation can be found at nsis.sourceforge.net/Docs. Ensure that you have a path to an icon (.ico) file and a bitmap image (.bmp) for the installer header. At various places within the installer source file it is necessary to define the version of the software and the uncompressed size of the install- this is used to calculate whether there is enough space on the various drives to do an installation. There are also various file locations throughout the installer- these should be changed to match your setup.

Building the installer takes ages. What can I say, it’s a big installation.

Documentation¶

The Portable GIS documentation is provided in the Portable GIS repository raw_docs folder as an open office document (.odt). This should be exported as a pdf file and saved in the usbgis\apps\docs folder of your Portable GIS installation. To ensure it is linked to correctly from the menu, it should be named pgis_docs.pdf.

The docs folder also contains the changelog and license text files (.txt) also linked to from the menu.

The readme file linked to from the installer should be placed in the root of your Portable GIS installation and named portablegis_readme.txt.

|-- raw_docs
        |-- pgis_docs.odt
|-- usbgis
        |-- apps
        |-- data
        |-- docs
                |-- changelog.txt
                |-- license.txt
                |-- pgis_docs.pdf
|-- portablegis_readme.txt
|-- ...