Setup of Development Environment for Windows

From OpenPetra Wiki
Jump to navigation Jump to search

Overview

All the development tools we use are open source themselves, so developers do not need to spend money to be able to partly or fully join the openPETRA development!

If you already have some or all of the software installed that is listed here, please make sure it is the same version that we specify before skipping the relevant section on this page!


Development Hardware Needed

Any PC that you would otherwise use for serious software development should suffice.

  • As a rough guide, a PC with a processor speed of more than 2GHz and at least 1 GB of RAM should be OK.
    • If your PC is below that specification, development will probably be possible, but rather slow and cumbersome.
    • On the other hand: Timotheus works with a Acer One Netbook, N280 CPU 1.6 Ghz, 2 GB RAM; speed is fine.
  • More than 2GB of RAM is not necessary if the only applications that you run simultaneously are the ones which are used for developing openPETRA.
  • The faster the processor, the better.
    • When compiling, it all comes down to processor speed, number of cores of the processor, and the architecture of the processor.
      • We have seen quite a boost in compilation speed with the new "i" series of Intel processors.
  • A multi-processor PC has its advantages.
    • The SharpDevelop IDE can do parallel compilations of Projects that aren't interdependent - that can speed up compilation notably (we saw an average of 20%-40% speed gain when comparing compilation of all the Client Projects on two processor cores compared to compiling on one processor core). We have verified this to scale very well on up to four processors (we don't have PC's with more processors than that...).
    • NAnt (our build system) can do parallel compilations of Projects that aren't interdependent - that can speed up compilation notably. We have verified this to scale very well on up to four processors (we don't have PC's with more processors than that...).
  • A 64-bit Operating System (e.g. Windows 7 64-bit) has no advantages for the purposes of developing openPETRA.

Time required for setting up an openPETRA development environment

Depending on the speed of your PC, and of course the speed of your Internet connection and the speed of the respective download servers, the setting of up of a development environment for openPETRA on Windows can take something between 40-80 minutes. Usually, there is only restart of the PC required (after installing TortoiseGit).

Required software

Microsoft .NET 3.5

Download and install the two Microsoft .NET dependencies. They allow execution of and development for .NET applications (such as openPETRA).

Microsoft recommends to run 'Windows Update' before installing those two dependencies. It might also be a good idea to run 'Windows Update' after installing those two dependencies to check whether any updates or security patches are available.

Note: Both the Redistributable and the SDK are needed! (We currently only use .NET 2.0 for openPETRA, but the SharpDevelop IDE requires .NET 3.5 SP1 Redistributable and SDK)


SharpDevelop 3

SharpDevelop is the IDE (Integrated Development Environment) we use for developing openPETRA.


PuTTY / Plink

PuTTY is a SSH and telnet client for the Windows platform. Plink is a command-line interface to the PuTTY back ends, which is used by Git and TortoiseGit (see below).

PuTTY and Plink are needed for 'developer access' only, i.e. if you intend to feed your changes back to the openPETRA Git source code repository at some point. They are not needed for 'anonymous access'.


Free download: PuTTY Download Page

  • In the section 'Binaries', choose the installer under the heading 'A Windows installer for everything except PuTTYtel', e.g. putty-0.60-installer.exe
  • Run the installer and remember the path where you install PuTTY into - you need to specify the path during the installation of Git and TortoiseGit (the installers need to be pointed to the file 'plink.exe' in that directory when they ask for it).


Git and TortoiseGit

The Git Source Code Management System is a distributed source code versioning system (as opposed to central source code versioning systems, such as CVS and SVN). We use Git for the maintenance of the openPETRA source code repository.

TortoiseGit is a Windows client for Git which integrates nicely into the context menu of the Windows Explorer.


Step 1: Git on Windows

Free download: Git on Windows

Note: use the official git installer from that site, eg. Git-1.7.0.2-preview20100309.exe, labelled 'Full installer for official Git', not the packages that have 'fullinstall' or 'netinstall' in their name, or any other packages.

Installation options

  • 'Select Components' page of the installer: leave everything as it is.
  • 'Adjusting your PATH environment' page of the installer: leave the radio button on 'Use Git Bash only'.
  • 'Choosing the SSH executable' page of the installer: Set the radio button to 'Use (Tortoise)Plink' and specify the path to the 'plink.exe' executable by using the '...' button (this is the path that you installed PuTTY into).
  • 'Configuring the line ending conversions' page of the installer: leave the radio button on 'Checkout Windows-style, commit Unix-style line endings'.

Step 2: TortoiseGit

  • Free download: TortoiseGit
    • Note: There are installers for 32bit and 64bit Windows. Choose the correct one according to your operating system architecture.
    • TortoiseGit is still work in progress, but works fine on Windows (we have encountered some minor hiccups, though).
    • Please install "Git on Windows" before installing TortoiseGit (see above)!

Installation options

  • 'SSH Configuration' page of the installer: Choose 'Use TortoisePLink coming from Putty, which integrates better with Windows'.

Alternative Windows Client

You also might want to have a look at Git Extensions, which is also a fully functional git GUI for Windows.


Setting up the Git repository

After installing Git and TortoiseGit (or Git Extensions), please follow our Notes about Git to configure your local git repository for openPETRA use!

NAnt

NAnt is our build system. It is used for ongoing compilation, for creation of Builds/Releases of openPETRA, and for the automation of quite a few tasks in the development lifecycle of openPETRA - including auto-generation of source code and Forms.

  • download NAnt 0.91-alpha2
    • please use this version as it works for us. Some of the released alpha or beta versions do not work (Example: 0.86-beta1; it breaks with message: Property 'sdkInstallRoot' has not been set.)
  • unzip the files to e.g. c:\program files\nant
  • open a Text Editor (e.g. Notepad, Notepad++) and create a new file with the file name c:\windows\nant.bat. It needs to have the following content:
@echo off
"C:\Program Files\NAnt\bin\NAnt.exe" %* -t:net-2.0

See also our Notes about NAnt.

Database systems

openPETRA works with a number of Database Management systems.

  • Choose one (or more) of the following Database Management systems. (If you want to start development quickly, SQLite is sufficient, so there is no immediate need to install PostgreSQL or MySQL. PostgreSQL is recommended for serious development, however).

Optional Software

  • For the editing of YAML files (which we use for defining the layout of screens, the main menu entries, and code hierarchy) we use Notepad++, which has syntax highlighting support for YAML files.
    • Download Notepad++
    • Once the software is installed, it needs to be set up once to accept our file extension, '.yaml', in addition to the one is built in, '.yml' for the syntax highlighting to work:
      • Menu 'Settings' -> 'Style Configurator'. Select 'YAML' in the 'Language' list and enter 'yaml' in the 'User ext.' field. Choose 'Save & Close'. (You might need to close and re-open any .yaml file that you already have open to get the syntax highlighting working.)
  • The following pieces of software are only required when you want to build releases of OpenPetra:


Configuration of the development environment and downloading of source code

The recommended way of installing OpenPetra.org for development is to somewhere map a 'fake' network drive, using the DOS command subst.

Alternative 1: Open a Command Window (a.k.a 'DOS Box') and enter for example:

mkdir c:\development
subst u: c:\development

Alternative 2:

  • Create a directory in Windows Explorer, c:\development.
  • Share the folder c:\development on the network and call it some name (YOUR SHARE), make sure you give write permissions to yourself.
  • Then connect a network drive (drive letter u:) to \\localhost\<YOUR SHARE>
  • careful: you need to set permissions for .net to allow running code from a network drive. see Giving a Mapped Drive .NET FullTrust

The Git repository should be 'Cloned' into the 'u:\openpetraorg\' directory by following one of the steps mentioned below. After cloning, that directory will contain the .git subdirectory, the OpenPetra.build NAnt script (U:\openpetraorg\OpenPetra.build) and a few more files. All the source code of openPETRA will be placed in various subdirectories.

Get the source code

The source code is managed with the Git source code versioning system.

Please understand that we will provide write permissions only to the core members of the development team, just to keep the project on one track (refered to as 'developer access' below). We very much need your contributions though, and we will aim to quickly deal with submitted patches and code. Please see our document on submitting patches and features!

You can get the openPETRA source code in several ways:

  • see the Git instructions at Sourceforge
    • that page describes how you can download from the openPETRA Git repository on sourceforge
  • you can also browse the Git repository online, and you can download a tar.gz snapshot of each version there
  • for developer access: more detailed instructions how to create the SSH key with the puttygen.exe program and where to upload it to Sourceforge: https://sourceforge.net/apps/trac/sourceforge/wiki/SSH%20keys
  • The recommended way for 'cloning' the openPETRA source code repository on Windows is by using TortoiseGit (see next section)!

Making a local 'Clone' of the openPETRA Git Repository

We illustrate the necessary steps for TortoiseGit. If you use another Git client, you will need to figure out how to do similar steps for yourself. (See Notes about Git for how to do it with the Git Bash.)

Configuring TortoiseGit for first time use

  • Right-click the U: drive in Windows Explorer and choose 'TortoiseGit'->'Settings'.
  • Click on the 'Check now' button in the 'MSysGit' section of the 'General' settings to ensure that TortoiseGit is configured correctly to use your Git installation. If this is correct, the MSysGit version will be displayed left of the 'Check now' button.
  • If you want to Clone the openPETRA repository using 'developer access' (as opposed to 'anonymous access'), enter your username and email address in the 'Git' -> 'Config' settings.
    • Also, in the 'Network' settings, check that the 'SSH Client' setting is pointing to your PuTTY plink.exe (or TortoisePlink.exe) file.
  • Close the 'Settings' dialog by choosing 'OK'.

Cloning the openPETRA Git repository

  • Right-click the U: drive in Windows Explorer and choose 'Git Clone...'.
  • In the 'Url' field you need to enter one of the following two URLs:
  • for anonymous access, you can use this URL to clone the repository with TortoiseGit:
git://openpetraorg.git.sourceforge.net/gitroot/openpetraorg/openpetraorg
  • for developer access (with write permissions), use this URL to clone the repository with TortoiseGit:
ssh://USERNAME@openpetraorg.git.sourceforge.net/gitroot/openpetraorg/openpetraorg

- replacing USERNAME with your sourceforge username.

  • In 'Directory', the value 'U:\\openpetraorg' should be left as it is.
  • If you are cloning the Git repository with developer access, ensure that the 'Load Putty Key' checkbox is checked and select your Putty Key (this is the SSH key you used for creating developer access earlier on).
  • If you are cloning the Git repository with anonymous access, ensure that the 'Load Putty Key' checkbox is not checked.
  • Choose 'OK'.
  • If you are Cloning the openPETRA repository using 'developer access', you will be asked to enter the passphrase for your SSH Key (unless you are using pageant and the key is aleardy loaded there).
  • The Clone process will start. Depending on the speed of your internet connection and the speed of the sourceforge Git repository, this might take some time. Initially no progress bar will be shown, but after a while a progress bar shows the cloning process.

Creating a local Git Branch

For development, we strongly recommend that you create a local branch, and switch to it. Then you pull updates from the server ("master") into your local branch, and push your updates up to the server in the master branch. Otherwise you get all sorts of problems with pushing and pulling, so don't commit to master at all. See also Notes about Git.

We illustrate the necessary steps for TortoiseGit. If you use another Git client, you will need to figure out how to do similar steps for yourself. (See Notes about Git for how to do it with the Git Bash.)

Creating a local Git Branch with TortoiseGit

Immediately after the Cloning is finished, you will need to perform the following steps:

  • Open the U: drive in Windows Explorer.
  • Right-click the 'openpetraorg' folder and choose 'TortoiseGit' -> 'Create Branch...'.
  • Enter any name for your branch that is meaningful to you.
  • Leave the radio button in GroupBox 'Base On' on the 'HEAD (master)' setting.
  • Tick 'Switch to local branch' in the 'Options' GroupBox.
  • Choose 'OK'.


Creating the OpenPetra.build.config file

  • Make a copy of the file OpenPetra.build-sample-windows.config and call it OpenPetra.build.config, for example by using the Command Prompt (a.k.a. 'DOS Box'):
U:
cd U:\openpetraorg
copy OpenPetra.build-sample-win.config OpenPetra.build.config

Please check your OpenPetra.build.config file and make sure the paths are all adjusted to your system and the version numbers in the paths are correct.

Finally: Building openPETRA with NAnt

After completing all the steps that are involved in the setup of your development environment for openPETRA, you are ready for the compiling and starting of openPETRA!

We have a central NAnt script that is able to build openPETRA, to generate a lot of code and is able to do all automated tasks in the openPETRA project.

Please go to OpenPetra NAnt script for finishing your openPETRA development setup.