Windows Install Package

The TerraLib binary and source code distribution packages for Windows are created from a set of scripts built with NSIS (Nullsoft Scriptable Install System). These scripts can generate packges containing binaries and libraries with their dependencies, sample code, unit test code, headers, configuration files and documentation.

The set of scripts provided can be used to create general packages or specific platform packges. The following platforms are already supported by the install scripts:

Microsoft Visual C++ 2010:
- for 32 bit architecture (x86)
- for 64 bit architecture (x64)
- for both architecture (x86 and x64)
MinGW:
- for 32 bit architecture (x86)
- for 64 bit architecture (x64)
- for both architecture (x86 and x64)

This section explains in detail the design and how to customize the install scripts.

Design

Explicar

TeComponents

Script for TerraLib components manipulation. Contains macros that make the insertion of all TerraLib modules in the installer separately, besides the configuration files and modules description that appears in the installer.

TeConfig

Script that contains the macro that applies the general settings, such as the project name, version, installation types, TerraLib path, platform and other settings.

TeDependencies

Script for TerraLib dependencies manipulation. Contains macros that make the insertion of all TerraLib dependencies in the installer.

TeDocumentation

Script for TerraLib documentation manipulation. Contains macros that make the insertion of all TerraLib API documentation in the installer, besides the creation of some shortcuts to facilitate the user's access to the documentation after installed.

TeExamples

Script for TerraLib examples manipulation. Contains macros that make the insertion of all TerraLib examples source code in the installer.

TeHeaderFiles

Script for TerraLib header files manipulation. Contains macros that make the insertion of all TerraLib header files in the installer.

TeInstallerUtils

Script that contains some installer configurations, such as functions that execute when the intaller starts (.onInit), star menu shortcuts, system registry end other configurations.

TeMinGWConfig

Script that contains specific configurations for TerraLib installers for MinGW.

TeMsvcConfig

Script that contains specific configurations for TerraLib installers for Visual Studio 2010.

TeMuiConfig

Script that contains configurations about the modern user interface, that defines the icons path, the installer pages (welcome, licence, components, directory), installer languages and other configurations.

TePlugins

Script for TerraLib plugins manipulation. Contains macros that make the insertion of all TerraLib plugins in the installer.

TeSections

Script for TerraLib installer sections manipulation. This sections appear in the components page of the installers and contains the installations options where the user can unselect a specific module or documentation sections for example.

TeUninstallerUtils

Script that contains some uninstaller configurations, such as the informations that the uninstaller must remove.

TeUnittest

Script for TerraLib unit tests manipulation. Contains macros that make the insertion of all TerraLib unit tests source code in the installer.

TeMinGW-bin-x64

Contains all specific configurations to generate a TerraLib 64 bit installer for MinGW.

TeMinGW-bin-x86

Contains all specific configurations to generate a TerraLib 32 bit installer for MinGW.

TeMinGW-bin-x86-and-x64

Contains all specific configurations to generate a TerraLib 32 and 64 bit installer for MinGW.

TeMSVC2010-bin-x64

Contains all specific configurations to generate a TerraLib 64 bit installer for Visual Studio 2010.

TeMSVC2010-bin-x86

Contains all specific configurations to generate a TerraLib 32 bit installer for Visual Studio 2010.

TeMSVC2010-bin-x86-and-x64

Contains all specific configurations to generate a TerraLib 32 and 64 bit installer for Visual Studio 2010.

Windows Registry

During the installation, the TerraLib installer insert some informations on Windows uninstaller registry. These informations inform Windows about de TerraLib, such as system name, version and especially the uninstaller path. With this registry, the Windows insert TerraLib informations on Windows uninstall manager, found in Control Panel/Programs and Features.

<color red>documentar: as chaves do registro do windows que devem ser alteradas; a questão de sistemas que são multiusuário; variáveis de ambiente; estruturas de diretórios</color>

Explicar quais são os scripts e o que cada um deles faz. justificar o porque!

Building the Install Packages

Software Requirements

Install NSIS 2.46 or above
- Download NSIS
Instal HM NIS Edit 2.0.3¹⁾
- Download HM NIS Edit

Building the Scripts

The scripts can be found in the TerraLib repository at the folder installer/nsis.
Before building the scripts, you should build TerraLib if you are intending to create a binary package distribution. This must be done according to the requirements of the installer to be created.
For example, to create a msvc2010 32 bit installer:
- the folders bin32/msvc2010 and lib32/msvc2010 must be present in the project directory tree.
- open the TeMSVC2010-bin-x86.nsi, for example, on HM NIS Edit
- select NSIS/Compile Script in the tool bar
The same steps can be used to generate the other installers from nsi files.

Customizing the Installer

You may want to modify the installer, removing some modules, removing the dependencies, and other options. We will see how to make these customizations.

Removing Some Modules

If you want to remove TerraLib modules of the installation, you can do with few steps.

For example:

If you want to remove all the modules section, simply comment (using “;”), the inclusion of the macro “TE_INSERT_COMPONENTS_SUBSECTION”. Doing this, none of the TerraLib dlls and libs will be inserted in the installer.
- You might comment the inclusion of the macro “TE_INCLUDE_CONFIG_FILES”, because this macro insert the “conf” dir.
- ```
...
!include "TeSections.nsh"
;!insertmacro TE_INSERT_COMPONENTS_SUBSECTION
 
!include "TeComponents.nsh"
;!insertmacro TE_INCLUDE_CONFIG_FILES
 
!insertmacro TE_INSERT_PLUGINS_SECTION
!insertmacro TE_INSERT_DOCUMENTATION_SECTION
...
```

If you want to remove only a specific module, you can do this comment the inclusion of the respective macro at macro “TE_INSERT_XXX_XXX_SECTION”²⁾ on TeSections.nsh file.

!macro TE_INSERT_MSVC_DEBUG_SECTION
  !insertmacro TE_MSVC_CONFIG
  SubSection "Debug" SEC_MSVC_DEBUG
 
    ;!insertmacro TE_MSVC_DEBUG_ANNOTATIONTEXT_SECTION
    !insertmacro TE_MSVC_DEBUG_COLOR_SECTION
    !insertmacro TE_MSVC_DEBUG_COMMON_SECTION
 
    ...

Adding New Dependencies

If you want to add a new TerraLib dependencie, you will:

Open the TeDependencies script

Add the dependecie path in the respective macro

!macro TE_INSERT_DEPENDENCIES_DEBUG_32
 
  SetOutPath "$INSTDIR\bin${PLATFORM}\${GENERATOR}"
 
    File /nonfatal "${TERRALIB_DIR}\bin${PLATFORM}\${GENERATOR}\boost_date_time-vc100-mt-gd-1_44.dll"
    File /nonfatal "${TERRALIB_DIR}\bin${PLATFORM}\${GENERATOR}\boost_filesystem-vc100-mt-gd-1_44.dll"
    .
    .
    .
    File /nonfatal "${TERRALIB_DIR}\bin${PLATFORM}\${GENERATOR}\terralib_new_dependencie.dll"

Adding New TerraLib Module

If a new module is created in TerraLib, to insert it into the installer we should:

Create new insert macros (for Debug and Release), and insert a description definition, at TeComponents.nsh

!macro TE_GET_COMPONENTS_DESCRIPTION
 
  !define TE_ANNOTATIONTEXT_DESCRIPTION "TerraLib Annotation Text Module"
  !define TE_NEWMODULE_DESCRIPTION "TerraLib New Module"
  ...
!macroend
 
!macro TE_INSERT_NEWMODULE_DEBUG
 
    SetOutPath "$INSTDIR\bin${PLATFORM}\${GENERATOR}"
    File /nonfatal "${TERRALIB_DIR}\bin${PLATFORM}\${GENERATOR}\terralib_NewModule_d.dll"
    SetOutPath "$INSTDIR\lib${PLATFORM}\${GENERATOR}"
    File /nonfatal "${TERRALIB_DIR}\lib${PLATFORM}\${GENERATOR}\terralib_NewModule_d.${LIB_EXTENSION}"
 
!macroend
 
!macro TE_INSERT_NEWMODULE_RELEASE
 
    SetOutPath "$INSTDIR\bin${PLATFORM}\${GENERATOR}"
    File /nonfatal "${TERRALIB_DIR}\bin${PLATFORM}\${GENERATOR}\terralib_NewModule.dll"
    SetOutPath "$INSTDIR\lib${PLATFORM}\${GENERATOR}"
    File /nonfatal "${TERRALIB_DIR}\lib${PLATFORM}\${GENERATOR}\terralib_NewModule.${LIB_EXTENSION}"
 
!macroend

Create the sections on TeSections.nsh, for Msvc Debug and Release, and MinGW Debug and Release

!macro TE_MSVC_DEBUG_NEWMODULE_SECTION
  Section "NewModule" SEC_MSVC_DEBUG_ANNOTATIONTEXT
    SectionIn 1 2 4
    !insertmacro TE_INSERT_NEWMODULE_DEBUG
 
    !ifdef x86-and-x64
      !undef PLATFORM
      !define PLATFORM "64"
      !insertmacro TE_INSERT_NEWMODULE_DEBUG
      !undef PLATFORM
      !define PLATFORM "32"
    !endif
  SectionEnd
!macroend

Call insert the new macro at TE_INSERT_XXXX_XXXX_SECTION (MSVC/MINGW; DEBUG/RELEASE)

!macro TE_INSERT_MSVC_DEBUG_SECTION
  !insertmacro TE_MSVC_CONFIG
  SubSection "Debug" SEC_MSVC_DEBUG
 
    !insertmacro TE_MSVC_DEBUG_ANNOTATIONTEXT_SECTION
    !insertmacro TE_MSVC_DEBUG_NEWMODULE_SECTION
    ...

Chage Icons and Images

To change the icons at installer and uninstaller icon, edit TeMuiConfig.nsh:

  ...
  !define MUI_ICON "${TERRALIB_DIR}\images\icons\64x64\terralib_install_icon.ico"
  !define MUI_UNICON "${TERRALIB_DIR}\images\icons\64x64\terralib_uninstall_icon.ico"
  ...

The images must be .ico type.

To change the image that appears in the installer windows, edit the line:

  ...
  !define MUI_HEADERIMAGE_BITMAP "${TERRALIB_DIR}\images\bmp\logo\terralib_installer_logo_150x57.bmp"
  ...

The image must me a .bmp type

Adding More Languages Suport

To add a new language suport, just edit the TeMuiConfig.nsh near the lines:

; Language files
  !insertmacro MUI_LANGUAGE "English"
  !insertmacro MUI_LANGUAGE "PortugueseBR"

The full list of suported languages you can see in NSIS path at Contrib\Language files.

Final Remarks

Pending Scripts
- TerraLib source code installer scripts
- TerraLib plugins installer scripts

References

OLD DOCUMENTATION

A partir daqui precisamos rever o que pode ser aproveitado!!!!!!

NSIS

In order to generate the install packages one will need to install NSIS:

Download: NSIS 2.46
Add nsis bin dir to the path

The compiler program - makensis - compiles scripts like the following example into executable installation programs.

# Example script
Name "Example1"
OutFile "example1.exe"
InstallDir "$PROGRAMFILES\Example1"
Page Directory
Page InstFiles
Section
  SetOutPath $INSTDIR
  File ..\makensis.exe
SectionEnd

The script full reference can be found here.

HM NSIS Edit

HM NSIS Edit is an editor/IDE for Nullsoft Scriptable Install System (NSIS). Its useful for experts and beginners in the creation of Setup programs with the NSIS. Its Script Wizard will help you to create standard Setup programs with only few clicks, also its InstallOptions designer will help you to create your own custom pages with a friendly drag and drop interface.

Download: HM NIS Edit 2.0.3

Installation Example

The HM NSIS Edit has used to create the first TerraLib Installer.

The following script is the skeleton to generate a TerraLib Installer. More details, see the file on TerraLib repository: ./terralib5/installer/nsis/terralib.nsis.

# TerraLib Installer Script Skeleton
 
; Defines
!define PRODUCT_NAME "TerraLib"
!define PRODUCT_VERSION "5.0"
!define PRODUCT_PUBLISHER "Instituto Nacional de Pesquisas Espaciais - INPE"
!define PRODUCT_WEB_SITE "www.terralib.org"
!define PRODUCT_UNINST_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\${PRODUCT_NAME}"
!define PRODUCT_UNINST_ROOT_KEY "HKLM"
 
; MUI 1.67 compatible
; Using the modern interface - http://nsis.sourceforge.net/Docs/Modern%20UI/Readme.html
!include "MUI.nsh"
 
; Installer UIs
; License page
!insertmacro MUI_PAGE_LICENSE "..\..\COPYING"
; Directory page - Enables the user select the installation directory
!insertmacro MUI_PAGE_DIRECTORY
; Instfiles page - Shows the extract files
!insertmacro MUI_PAGE_INSTFILES
; Finish page
!insertmacro MUI_PAGE_FINISH
; Uninstaller pages
!insertmacro MUI_UNPAGE_INSTFILES
; MUI end
 
; Installer definitions
Name "${PRODUCT_NAME} ${PRODUCT_VERSION}"
OutFile "install.exe"
InstallDir "$PROGRAMFILES\TerraLib"
ShowInstDetails show
ShowUnInstDetails show
BrandingText "TerraLib Development Team"
 
Function .onInit
; Init install commands.
FunctionEnd
 
; TerraLib Section
; The files that will be installed goes here.
; For example: the install directory will have a folder called 'bin' that contains some build TerraLib DLLs;  
Section "TerraLib"
  SetOutPath $INSTDIR
  CreateDirectory "bin"   ; Create the output directory
  SetOutPath $INSTDIR\bin ; Sets it as current directory
; Coping the files!
  File ..\..\bin\msvc2008\terralib_common.dll
; ...
 
Section -Post
; Post install commands. For example, writes the unistall file, writes reg keys, etc.
SectionEnd
 
Section Uninstall
; Uninstall commands. For example, delete the created directory, delete reg keys, etc.
SectionEnd

Installation Example

Nowadays, the script generates a installer that when executed, creates the following structure of directories with the following files:

bin - <color gray>contains some TerraLib Dlls</color>
- terralib_common.dll
- terralib_dataaccess.dll
- terralib_geometry.dll
- terralib_ogr.dll
- terralib_plugin.dll
- terralib_postgis.dll
- terralib_srs.dll
include - <color gray>contains the *.h files</color>
- terralib
  - common
  - dataaccess
  - geometry
  - ogr
  - plugin
  - postgis
  - srs
lib - <color gray>contains some TerraLib Libs that can be used to make dynamic links</color>
- terralib_common.lib
- terralib_dataaccess.lib
- terralib_geometry.lib
- terralib_ogr.lib
- terralib_plugin.lib
- terralib_postgis.lib
- terralib_srs.lib
uninst.exe - <color gray>the uninstall file</color>

If you installed the NSIS package, click with rigth button on file and select the option: Compile NSIS Script. It will be generated a executable called install.exe.

Remarks

¹⁾ The use of HM NIS Edit is not necessary, but makes the process more user-friendly

²⁾ Can be in the “TE_INSERT_MSVC_DEBUG_SECTION”, or TE_INSERT_MINGW_DEBUG_SECTION, or “TE_INSERT_MSVC_RELEASE_SECTION”

Table of Contents

Windows Install Package

Design

TeComponents

TeConfig

TeDependencies

TeDocumentation

TeExamples

TeHeaderFiles

TeInstallerUtils

TeMinGWConfig

TeMsvcConfig

TeMuiConfig

TePlugins

TeSections

TeUninstallerUtils

TeUnittest

TeMinGW-bin-x64

TeMinGW-bin-x86

TeMinGW-bin-x86-and-x64

TeMSVC2010-bin-x64

TeMSVC2010-bin-x86

TeMSVC2010-bin-x86-and-x64

Windows Registry

Building the Install Packages

Software Requirements

Building the Scripts

Customizing the Installer

Removing Some Modules

Adding New Dependencies

Adding New TerraLib Module

Chage Icons and Images

Adding More Languages Suport

Final Remarks

References

OLD DOCUMENTATION

NSIS

HM NSIS Edit

Installation Example

Installation Example

Remarks