Tutorial: Getting software released...
This Section describes the entire path from a software code to an installable program. This tutorial is also available on the OpenEarth website at the tutorial section.
As example, Detran (Delft Transport Analyzer) is used. This program is part of OpenEarth tools and can be used for calculating sediment transport rates through arbitrarily chosen transects on the basis of Delft3D output. Detran can be used both from the command line (as a toolbox) and as a program with a GUI.
Summarized, the path consists of the following seven steps:
Step 1 – Create the code
Step 2 – Testing
Step 3 – Documentation and support
Step 4 – Releasing the software
Step 5 – Creating an installer
Step 6 – Distribution of the product
Step 7 – Evaluation of the product by user-feedback
The steps are described below in more detail. The tools that are used in this tutorial can be downloaded from:
The files that have been created during the various steps can be download here. After downloading, extract the files to a local directory. The directory numbering corresponds to the steps that are described below.
1. Create the code
Detran is programmed in Matlab. The routines that the program uses are divided into two groups (see Figure 1). The first group are the 'engines'. This code performs the actual calculations and can also be used from the command line (without the GUI). The second group are the gui-routines, which perform the communication between the GUI and the engines. All code is created according to the guidelines provided in DM1.1 (i.e. description, help block as in Figure 2 copyright notice, etc). An easy way to do this is to use a template for a new m-file with the command 'oetnewfun'. For more information, check the OpenEarth website.
Put your code in the OpenEarth repository so that it is accessible for others to use and improve. Check this link for more information.
Figure 1Detran routines
Figure 2Help block in the code of the main engine of Detran
2. Testing
Ideally, each routine of the application code should be accompanied by a test routine as part of the quality control system. The guidelines for this have also been described by DM1.1. To create a test routine, it is recommended to use the template with the command "oetnewtest".
The test routines are automatically called by the TeamCity server (after a commit). If all tests are passed, the application has passed the quality control. At this stage, the software can be released by tagging the current state of the code.
In case of a compiled (standalone) program with a graphical user interface (such as Detran), it is not possible to test all routines in this way; some of the routines of Detran communicate with the user via the graphical user interface and are thus dependent on user input (i.e. a press on a button in the GUI) and this cannot be tested automatically. Therefore, only for those routines that perform the calculations and which can be called from the command line, test-routines have been written. Test results can be found on the Teamcity website (see Figure 3). All test-routines have passed the tests. Besides the code testing, the GUI must be tested also. This means that all options in the Detran GUI (buttons, selections, etc.) have been tested and also pressing cancel buttons and filling in erroneous input in the text input fields. If no errors occur, then the GUI has passed the test.
Both the results of the code testing and the GUI testing have been described in the Detran test document (see example here). In that way, the tests can be repeated easily once a new version is being released.
Figure 3Test results (all positive) of Detran routines
3. Documentation / tutorial
A Detran manual has been prepared. The manual describes the GUI of Detran, including all objects and their function. Besides, because Detran can also be used from the command line in Matlab, the manual contains instructions of how the use it that way. This part of the manual was created automatically by means of TeamCity which collects the help blocks of tools in a toolbox and puts it in a document [TO BE COMPLETED].
Besides the manual, some tutorials have been set up. First. a html-tutorial has been created for use of Detran from the command line. This was done by making a tutorial in matlab ('detran_tutorial.m'), which has been converted automatically to html by TeamCity. The tutorial can be found at [http://publicwiki.deltares.nl/display/OET/Matlab+Tutorials|http://publicwiki.deltares.nl/display/OET/Matlab+Tutorials] or click this direct link. Logically, all documentation will also be also included in the Detran installer. The html-tutorial is mainly intended to support command-line use of Detran.
Besides, a video tutorial was created for getting familiar with the Detran GUI using Wink video tutorial software. This tutorial shows the basic steps to load data into Detran and to show some transport patterns. This tutorial can be found on the Detran product page: http://publicwiki.deltares.nl/display/OET/Detran
4. Releasing the software
If the tests were all successful, the current version of the code can be released. First, commit and update the code using SVN to update the revision number. Then we export the current status of the code to a directory in the tag of the repository. A directory name must be specified and it is useful to use the program name followed by a version number. In case of this first release of Detran:
Detran_v1.00.2851
The version numbering is according to the guidelines mentioned in Section 1.4.
Next, the released code is converted to a standalone executable using the Matlab compiler. The compiled program was tested again (using the GUI tests described in the test document) in order to verify if the compilation process was correct. These results have also been added to the test document.
The released software is accompanied by a file 'releaseNotes.txt' which provides a brief change log with respect to the previous version (the svn log could be used as input).
5. Creating an installer
The installer for Detran has been created using Wix. The Wix installer software has been installed on a local pc and this pc is also used to create the installer. In corporation with Jan Kramer, the installer has been set up. Jan Kramer created a readme-document which describes the process (see Appendix A). For first-time users, the programs WIX and NANT should be installed first. Also, the bin directories of both programs must be added to your system environment variable PATH (see Figure 4).
Figure 4Adding bin directory of WiX to the environment variable 'Path'
Below, the steps are summarized.
- Create a local working directory, i.e. 'detran_installer'
- Create a directory 'source' in the working dir in which you should place the directories and files that should be installed. For the Detran case, four directories were placed in the source dir:
- 'bin', containing the actual program file(s) like the executable file, the about.txt file containing version information of the program and the releasenotes.txt file.
- 'manual', containing the manual files preferably in html-format
- 'tutorial', containing one or more (video) tutorial(s) of the program, preferably in html-format
- Create a directory 'resources' in the working dir in which you can place files that are necessary for the installer itself. In case of Detran, in this directory four sub-directories were present:
- 'banner', containing a 500x63 pixels bmp-file used as banner in the installer window.
- 'icon', containing a ico-file of the program to be installed that will be used as icon for the shortcuts to the program in the start menu and on the desktop.
- 'license', containing a rtf-file with the license agreement which users should accept before they can install the program.
- 'logo', containing a 493x312 pixels bmp used as background image in the first and last screen of the installer.
- Create/adjust the file 'build-variables.xml' to match the directories in the source dir and put this file in a directory called 'includes'
- Create/adjust the file 'harvest.build' to match the directories in the source dir.
- Open a DOS-box in your working directory and run the command: nant -buildfile:harvest.build This process will create *.wxs files for each of the sub-dirs in the source dir. The wxs-files are also placed in the source dir.
- Create/adjust the files global_detran.wxi and detran.wxl and put them in the directory 'includes'. Make sure that this directory also contains the file 'WixUI_en-us.wxl' (does not need changes). Don't forget to generate an upgrade code for your product, for example at http://www.guidgenerator.com (don't use the one in the example file!).
- Create/adjust the main wxs-file (i.e. detran.wxs) in the working directory. Remember to adjust the value of 'target' in the 'RemoveFolder' and 'Shortcut' entries to match the id of the executable of your program that is specified in the bin.wxs file. Also use an unique GUID for your specific product as product ID (at line 8).
- Create/adjust the file 'detran.build'. Specify the links to all wxs-files at the 'build-installer' section.
- Create the installer by running (in the DOS-box): nant -buildfile:detran.buildThe installer will appear in the dir: \build\Release\
6. Distribution of the product
Put the product on the OpenEarth website at the Products section:
http://publicwiki.deltares.nl/display/OET/OpenEarth+Product+Suite
For each product, a separate site must be created, see the Detran example:
http://publicwiki.deltares.nl/display/OET/Detran
At the product site, four sub-sections are available:
- Description: a short description of the product
- Download: download links to the available versions of the program
- Help and support: here you can find the manual and tutorial(s)
- Feedback: this contains a user forum and a link to the issue management system JIRA (see Step 7)
7. Evaluation of the product by user-feedback
At the JIRA section of OpenEarth (http://issues.openearth.nl), create a Detran entry.
work in progress
Further, a user forum has been opened for Detran using wiki infrastructure.
Both feedback systems are available at the Detran product page (http://publicwiki.deltares.nl/display/OET/Detran).
