Creating a package for OSGeo4W

06.05.2011 19:23 ·  GIS  ·  osgeo4w, howto

OSGeo4W is a special installer focused on the distribution of various free and open-source GIS software on Windows operating systems (XP, Vista, etc.). With OSGeo4W you can install GDAL/OGR, GRASS, MapServer, OpenEV, uDIG, QGIS and many other packages (see the full list).

Installing OSGeo4W requires only a few simple steps:

After installation, desktop applications can be started from the “Start → Programs → OSGeo4W” menu. Command line utilities can be run from the OSGeo4W Shell, and web applications will be available at http://localhost/.

In this post, I will go through the main steps needed to prepare and add a new package to OSGeo4W, based on my experience of creating packages for matplotlib and TinyOWS, and information from the OSGeo4W Wiki.

Preparation

No matter how large the OSGeo4W package list is, there are always some useful programs or libraries that are not available in the installer. This was the case with matplotlib and TinyOWS.

So you have decided to add a new package to OSGeo4W. First, you need to get approval from the developers and maintainers. Practice shows that if the proposed package has no exotic dependencies, is free software, and you are willing to support it, there will be no objections. After approval, you should prepare the package and upload it to the server.

Package format and directory structure

Each OSGeo4W package is a bzip2-compressed tar archive, which is unpacked into the OSGeo4W root directory during installation. All packages have their own setup.hint file with a description and a list of package dependencies.

The structure of the OSGeo4W directory tree is described on a separate wiki page, so I will not repeat it here. Before creating the package, you should have a look at the directory structure and decide in which directories your files should be located. All paths in the archive should be relative to the OSGeo4W root directory.

Prepared packages are uploaded to the server (usually each package in a separate directory):

upload.osgeo.org:/osgeo/download/osgeo4w/release/<arch>/<package>

The current directory layout for each of the supported architectures can be found at https://download.osgeo.org/osgeo4w.

Each package has its own directory containing the setup.hint file and one or more versions of the package as tar.bz2 archives. The name of the archive must follow certain conventions: the base name of the package, followed by the version of the packaged software, and finally the version of the package itself.

Structure of the OSGeo4W package name
Structure of the OSGeo4W package name

Note that the base name of the package and the directory name in the OSGeo4W directory tree must match, i.e. the tinyows directory must contain the files with the names like tinyows-<version>-<revision>.tar.bz2.

Sometimes a single program is split into several packages (e.g., GDAL). In this case, the individual components are located in subdirectories of the package base directory. For example, the Oracle 10g driver for GDAL will be in the release/gdal/gdal-oracle10g directory, and the package will be gdal-oracle10g-1.5.0-1.tar.bz2.

The setup.hint file with a short and long description of the package and a list of its dependencies must be present in the package directory. For example, here is setup.hint for TinyOWS:

sdesc: "High performance WFS-T server"
ldesc: "High performance Web Feature Service (WFS-T) server"
category: Web
requires: apache msvcrt iconv fcgi libxml2 regex

Packaging web-applications

When creating the directory layout for the web application, it is necessary to adhere to the following guidelines:

The filename must follow the pattern packagename.pkg.html (note the double extension!).

Post-install actions

The package can perform post-install actions, most commonly to update configuration files (updating paths relative to the installation directory) and to create shortcuts. A .bat file in the package’s /etc/postinstall directory is responsible for performing post-install actions. The name of this file must match the name of the package, for example: /etc/postinstall/tinyows.bat. The command file is executed after unpacking the archive with the environment variables OSGEO4W_STARTMENU, OSGEO4W_HOME and OSGEO4W_HOME_MSYS set and the directory OSGEO4W_HOME/bin added to the PATH variable.

Text replacement

For example, let’s look how to correct paths in the TinyOWS configuration file. Initially the apps/tinyows/config.xml file looks like this

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<tinyows online_resource="http://127.0.0.1/cgi-bin/tinyows.exe"
   schema_dir="D:/package/apps/tinyows/schema/">

  <pg host="127.0.0.1" user="postgres" password="postgres" dbname="tinyows_demo" port="5432"/>

  <metadata name="TinyOWS Server"
      title="TinyOWS Server - Demo Service" />

  <layer retrievable="1"
   writable="1"
   ns_prefix="tows"
   ns_uri="http://www.tinyows.org/"
         name="world"
         title="World Administrative Boundaries" />

  <layer retrievable="1"
   writable="1"
   ns_prefix="tows"
   ns_uri="http://www.tinyows.org/"
         name="france"
         title="French Administrative Sub Boundaries (IGN - GeoFLA Departements)" />

</tinyows>

You can see that the path in the second line

schema_dir="D:/package/apps/tinyows/schema/"

is absolute and will point to a non-existent directory after installation. To make this path point to the correct location within the OSGeo4W directory after installation, we need:

The textreplace command has the following syntax:

textreplace -sf source_file -df destination_file -map old_text new_text

The httpd.d/httpd_tinyows.conf file is updated in the same way.

If you need to update paths in Python code, the following line should be added to the beginning of the postinstall.bat file

set OSGEO4W_ROOT=%OSGEO4W_ROOT:\=\\%

This will force textreplace to use double slashes, so instead of C:\OSGeo4W it will use C:\\OSGeo4W.

Creating shortcuts

Another post-installation action is to create shortcuts to run the software. As with string replacement, there is a utility called xxmklink.exe (part of the msvcrt package) for this purpose. This is a console application, running it without any parameters will give you a list of all the options it supports. Below are some usage examples.

Creating a folder and shortcut in the Start menu

mkdir "%OSGEO4W_STARTMENU%"
mkdir "%OSGEO4W_STARTMENU%\Apache"
xxmklink "%OSGEO4W_STARTMENU%\Apache\OSGEO4W-Apache-Install.lnk" %OSGEO4W_ROOT%\Apache\bin\httpd.exe " -k install -n \"Apache OSGEO4W Web Server\""

Creating a shortcut with a custom icon

xxmklink "%OSGEO4W_STARTMENU%\ttt.lnk" cmd.exe "" . "my_desc" 1 "%OSGEO4W_ROOT%\OSGeo4W.ico"

Creating a Desktop shortcut

xxmklink "%ALLUSERSPROFILE%\Desktop\OpenEV.lnk" "%OSGEO4W_ROOT%\bin\openev.bat" " " \ "OSGeo4W OpenEV" 1 "%OSGEO4W_ROOT%\apps\openev\icon.ico"

In addition to updating configuration files and creating shortcuts, you can run any DOS command and any installed application with the desired parameters from the post-install .bat files.

Environment variables

Some applications require specific environment variables to be set. Setting environment variables for the OSGeo4W command line is done using an initialisation file in the /etc/ini directory. These files are normal .bat files that set all required variables, e.g.

SET GDAL_DATA=%OSGEO4W_ROOT%\share\gdal

These files are executed randomly by the %OSGEO4W_ROOT%\OSGeo4W.bat script, which is responsible for creating the OSGeo4W command line environment. The OSGEO4W_ROOT variable is set automatically.

.bat files are used to run applications with a specific environment variables. So, to start the application foo.exe with a default set of environment variables, it is necessary to create a command file foo.bat.tmpl with the following content

@echo off
SET OSGEO4W_ROOT=@osgeo4w@
call "%OSGEO4W_ROOT%\bin\o4w_env.bat"
start "Foo window title" /B "%OSGEO4W_ROOT%\bin\foo.exe" %*
@echo on

This file should be in the bin directory of the package. And in the postinstall.bat file, make sure you update the OSGEO4W_ROOT value and rename foo.bat.tmpl to foo.bat. You can look at existing packages such as qgis for examples.

Uploading a package

Once the package directory structure is prepared and all the files are in their place, we need to create an archive

tar cjvf tinyows-1.0.0rc1-1.tar.bz2 apps/ bin/ etc/ httpd.d/

Using SSH, connect to the upload.osgeo.org server (you will need an OSGeo Id and appropriate access rights), create a directory for the new package, copy the setup.hint file and the package itself into it.

Then we need to check that the package is built correctly:

We also need to add the new package to the package list and create a link to the package page with the following information:

⮜ Prev
Next ⮞