Windows Environment

Setting up Windows Environment

This small tutorial describes how to configure Windows environment in order to develop TerraME packages. Execute the following steps:

1. Install TerraME
2. Install PostgreSQL/PostGIS (only if working with databases)
3. Install ANSICON (optional)
4. Add links to packages
5. Creating projects
6. Testing
7. Checking source code
8. Creating documentation

Install TerraME

Download and install the latest version of TerraME here. After installing TerraME, add C:\TerraME\bin to your PATH environment.

Install PostgreSQL/PostGIS

PostGIS is a spatial database extension for PostgreSQL, a Database Management System (DBMS). TerraME allows working with PostGIS databases easily. This page describes how to install the PostGIS that is currently used for the automatic tests.

Install ANSICON

ANSICON provides ANSI escape sequences for Windows console programs. It provides much the same functionality as ANSI.SYS does for MS-DOS. Download ANSICON

Add x86 (if your OS is 32-bit) or x64 (if 64-bit) to your PATH, or copy the relevant files to a directory already in the PATH.

Alternatively, use option -i (or -I, if permitted) to install it permanently, by adding an entry to CMD.EXE's AutoRun registry value (current user or local machine, respectively).

Add links to packages

A junction (soft link) links directories located on the same computer. Any changes to that directory are instantly visible to applications that access it through the soft links that reference it. The code below is used to create a junction:

MKLINK /J "output directory" "input directory" 

Note that the 'output directory' must not exist on disk.

If you are going to develop TerraME, delete the following directories and create a link between installed TerraME and GitHub repository:

SET TERRAME_INSTALLATION=C:\TerraME
rmdir /s %TERRAME_INSTALLATION%\bin\lua
rmdir /s %TERRAME_INSTALLATION%\bin\packages\base
rmdir /s %TERRAME_INSTALLATION%\bin\packages\gis
rmdir /s %TERRAME_INSTALLATION%\bin\packages\luadoc

The following examples create a link between installed TerraME and GitHub repository:

SET MY_TERRAME=C:\Users\MyUser\terrame
SET TERRAME_INSTALLATION=C:\TerraME
MKLINK /J %TERRAME_INSTALLATION%\bin\lua %MY_TERRAME%\src\lua
MKLINK /J %TERRAME_INSTALLATION%\bin\packages\base %MY_TERRAME%\packages\base
MKLINK /J %TERRAME_INSTALLATION%\bin\packages\gis %MY_TERRAME%\packages\gis
MKLINK /J %TERRAME_INSTALLATION%\packages\luadoc %MY_TERRAME%\packages\luadoc

If you are going to develop add on packages, delete the package directory within TerraME (if it exists):

SET TERRAME_INSTALLATION=C:\TerraME
SET MY_PACKAGE=mypackagename
rmdir /s %TERRAME_INSTALLATION%\bin\packages\%MY_PACKAGE%

Then add a link from the package directory to TerraME:

SET TERRAME_INSTALLATION=C:\TerraME
SET MY_PACKAGE=mypackagename
SET GITHUB_PATH=C:\Users\MyUser\github
MKLINK /J %TERRAME_INSTALLATION%\bin\packages\%MY_PACKAGE% %GITHUB_PATH\%MY_PACKAGE%

Creating projects

If the package works with geospatial data and manipulates tview or qgs files, it is important to create the projects before running tests or documentation.

terrame -color -package pkg -projects

Tests

Config file

It is possible to run only part of the tests, or configure parts of its execution, using a file that might contain optional variables. The code below shows an example of a config file named test.lua:

lines = true

Databases

Database tests require external files or connections to a DBMS. When the tests use a database connection, they might use file config.lua through getConfig() (see Utils documentation in base package) to get information about how to connect to a database. Note that config.lua must be placed in the same directory TerraME will be executed for testing the package. Using this strategy guarantees that the tests could be run in different DBMSs or even in different machines without needing to change the test files. An example of config.lua is shown below:

user = "postgres"
password = "postgres"
drop = true

See TerraME tests for more details.

Executing tests

The command to test a package is:

terrame -color -package pkg -test

If package pkg is installed then TerraME runs its tests. If not, then TerraME checks if there is a local directory with this name storing the package. If directory tests does not exist, it is possible to create a sketch of the tests by running

terrame -color -package pkg -sketch

It fills each file with test functions, indicating where the tests must be implemented. The code below shows an example of the command to test TerraME base package using a config file named test.lua, note that if you do not specify the package to be tested, base package will be tested as default.

terrame -color -test test.lua

It is also possible to add -color in order to have a coloured output if Ansicon is running, which helps to find errors:

terrame -color -package pkg -test

Under Mac and Linux, such colors are shown automatically in the terminal. Under Windows, you must run ansicon -i before using -color. The following examples execute tests for base and gis packages:

terrame -color -package base -test test.lua
terrame -color -package gis -test test.lua

Checking source code

Luacheck executes several verifications to make the code clean. For example, it verifies if a variable is declared twice as local in the same scope, or if some arguments of declared functions are not used.

terrame -color -package pkg -doc

Creating documentation

The documentation of TerraME is written using a slightly changed version of LuaDoc. Every non-local function of the package must be documented. The code below shows an example of the command to create a package documentation:

terrame -color -package pkg -doc

The documentation of base and gis packages can be created, in the following way:

terrame -color -doc
terrame -color -package gis -doc

See TerraME documentation for more details.