Developer's Guide - climsoft/Climsoft GitHub Wiki

Developer's Guide

Summary of developer tools

Required

CLIMSOFT 4.x development has the following required software dependencies:

  • Microsoft Windows 7 service pack 1 or above
  • Visual Studio Community
  • MySQL Community Server (or MariaDB Server 10.0+)

Preinstalled

The following dependencies are already included in the Climsoft code on GitHub

  • MySQL for Visual Studio
  • R.Net Community 1.6

Recommended for developing Climsoft 4.3

The following dependencies may be required for working on Climsoft Products.

  • R (+ additional packages, see below)
  • R-Instat

Optional

Depending on the development activities you are undertaking, the following software may be required or useful:

  • Multilingual App Toolkit
  • HelpMaker
  • RStudio

Useful

The following software is currently used by the core developers, but you may have alternative tools that you prefer to use instead:

  • MySQL Workbench / HeidiSQL
  • GitHub extension for Visual Studio

Installing required tools

Note: all installations should use default options unless otherwise stated.

Microsoft Windows

All developers are currently using Windows 7 service pack 1 or above for software development. Microsoft provide free versions of the different versions of Windows for developers to use to test software on a clean installation in a virtual machine. Note that these free installations are time limited to a 30 day period (but it may be possible to extend this).

http://dev.modern.ie/tools/vms/

Visual Studio

Visual Studio Community

https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx. When installing Visual Studio 2015 or above select the option to install the GitHub extension for Visual Studio.

MySQL Community Server & MySQL for Visual Studio

The MySQL Installer provides an easy to use, wizard-based installation for all MySQL software on Windows. This included MySQL Server, MySQL for Visual Studio and also MySQL Workbench. When installing we chose the Developer Default option.

http://dev.mysql.com/downloads/windows/

e.g. mysql-installer-web-community-5.6.25.0.msi

Note: Both the 32-bit (x86) and 64-bit (x64) versions of MySQL Server appear to need the 32-bit (x86) version of Visual C++ Redistributable Packages for Visual Studio 2013.

Note: If MySQL for Visual Studio will not install through MySQL Installer (because it cannot detect your copy of Visual Studio) try installing it separately.

Note: If the installion for MySQL server hangs at "Starting MySQL as a service" then try the solution here. If there are still problems check the logs (note that your ProgramData folder may be hidden by default). If necessary, uninstall and try again with a previous version of the installer, e.g. 5.6 (although, don't use the web installer as the links may no longer exist). If you're installing in Bootcamp on a MacBook Pro see here.

Update: It is also possible to use MariaDB in place of MySQL, and to continue to use MySQL for Visual Studio to connect to MariaDB.

Note: MySQL for Visual Studio is currently not installed and managed using Visual Studio's NuGet package manager, instead the required MySql.Data.dll file has been manually included in the project's resources.

Installing recommended tools

R

The R programming language is used by CLIMSOFT 4.1+ to create some products at run time. CLIMSOFT will automatically find the R software if it is installed to the default location.

http://cran.rstudio.com/

e.g. R-3.2.0-win.exe

Note: The expected location of R is currenly hard-coded in the CLIMSOFT codebase as C:\Program Files\R\R-3.2.1

See: https://github.com/opencdms/Climsoft/blob/master/ClimsoftVer4/ClimsoftVer4/clsClimsoftSettings.vb#L109

The following additional packages, along with their respective dependencies, are also required:

  • reshape
  • Reshape2
  • lubridate
  • rtf
  • (ggplot2)
  • RMySQL
  • SweaveListingUtils

Packages can be installed from the R command prompt ...

install.packages(c("reshape2", "lubridate", "rtf", "ggplot2"))

or in RStudio by navigating to Tools > Install Packages ...

If you receive the following error installing packages then see the solution here: http://stackoverflow.com/a/23167680

Unable to install packages (default library 'C:/Program Files/R/R-3.2.0/library' is not writable)

R.Net Community 1.6

R.Net Community is part of the CLIMSOFT 4 visual studio project and therefore should be retrieved automatically by the NuGet package manager as necessary. If you need to install R.Net manually, the open the CLIMSOFT 4 project in Visual Studio and navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution.

Note: The R.Net package also installs a dependancy (Dynamic Interop)

The reference documentation for R.Net can be found via https://rdotnet.codeplex.com/

R ClimateObject

The R ClimateObject is used to create products from CLIMSOFT data. Developers are currently using different versions of the ClimateObject depending on the date on which the code is checked out

Clone a copy of the ClimateObject from: https://github.com/StatisticalServicesCentre/ClimateObject

Note: Currently CLIMSOFT 4 expects the ClimateObject repository to be located in C:/ClimateObject/ This path is hard-coded in the clsRInterface.vb file. See: https://github.com/opencdms/Climsoft/blob/master/ClimsoftVer4/ClimsoftVer4/clsRInterface.vb#L26

Installing optional tools

Multilingual App Toolkit

An extension for Visual Studio to enable simpler translations.

https://visualstudiogallery.msdn.microsoft.com/6dab9154-a7e1-46e4-bbfa-18b5e81df520

HelpMaker

Instructions for installing HelpMaker will be added here. Alternatively, a modern free/open source alternative will be suggested, see list of possible alternatives here: http://alternativeto.net/software/win-chm/?license=free

RStudio

To develop R software, RStudio is recommended

http://www.rstudio.com/products/rstudio/download/

e.g. RStudio-0.99.441.exe

Installing useful tools

MySQL Workbench

See MySQL Installer above

GitHub Desktop / GitHub extension for Visual Studio

The core developers are currenly using either GitHub Desktop or the GitHub extension for Visual Studio.

https://windows.github.com/ or https://visualstudio.github.com/

Note: GitHub extension for Visual Studio is an option when installing Visual Studio 2015+. If the download above does not install the software successfully then it can be installed from within Visual Studio 2015 by selecting Tools - Extensions and Updates - Online. You may need to restart VS after installing.

Manual development setup

The following steps will be automated by the future CLIMSOFT install process. However, currently developers must perform these installation steps manually.

Setup CLIMSOFT database

Currently the CLIMSOFT 4 software does not create a corresponding CLIMSOFT database (but this is created if to run the Climsoft installer). Follow the instructions at https://github.com/opencdms/Climsoft/tree/master/Climsoft_V4_dbase

In addition a minimal set of sample data is provided for testing forms and products. To import the sample data follow the instructions at https://github.com/opencdms/Climsoft/tree/master/Climsoft_V4_dbase/climsoft_v4_sample_data