Setup of Development environment: Difference between revisions

From OpenPetra Wiki
Jump to navigation Jump to search
 
(84 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Windows Development environment ==
== Update April 2020 ==
=== Required software ===
We now have a development environment for CentOS/Fedora, Ubuntu and Debian.
* Git (see also some [[Notes about Git]]); recommended: TortoiseGit
* Microsoft .Net 3.5 Redistributable and SDK (we only use .Net 2.0 for OpenPetra, but SharpDevelop requires .Net 3.5)
* SharpDevelop 3.0
* NAnt (see also some [[Notes about NAnt]])
* one of the following Database Management systems:
** PostgreSQL (recommended) [[Notes about PostgreSQL]]
** MySQL [[Notes about MySQL]]
** no installation effort at all is required for SQLite [[Notes about SQLite]]
* Poedit (for translation) (see also [[Notes about I18N]])
* Mono (for translation)
* Inno Setup 5 for building setup files


== Linux Development environment ==
See instructions at [[Quick Setup of Development environment]]
=== Install required software ===
Please add information for other distributions that you are working with!
==== Git ====
* on Ubuntu/Debian: apt-get install git-core
==== MonoDevelop 2.x ====
* on Ubuntu/Debian: apt-get install mono-2.0-runtime monodevelop
==== NAnt ====
* on Ubuntu/Debian: apt-get install nant
** Problem: NAnt 0.85 (Build 0.85.2478.0; release; 10/14/2006) does not seem to support the task "solution" on Linux? <code>Invalid element &lt;solution&gt;. Unknown task or datatype.</code>
** Problem: exec spawn is not supported in 0.85
** Solution: copy binary zip from sourceforge, unzip, and change /usr/bin/nant to point at the latest NAnt.exe
** to avoid all the warnings "Could not load file or assembly" run: apt-get install libmono-microsoft-build2.0-cil
** Also you need to make a symbolic link:
ln -s /usr/lib/mono/2.0/Microsoft.CSharp.targets /usr/lib/mono/2.0/Microsoft.CSharp.Targets


==== SQLite or PostgreSQL ====
The following information stays for a while because the friends at OM are still working on Windows.
* on Ubuntu/Debian:
** apt-get install sqlite3 (requires 3.6.1 or higher; might need to use another repository, eg testing)
** or apt-get install postgresql


== Get the source code ==
== Overview and Introduction ==
The source code is managed with Git.
'''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!'''


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. We very much need your contributions though, and we will aim to quickly deal with submitted patches and code via the forum. This still has to be worked out how this works best to submit code that way.
The openPETRA developers in OM work on Windows, but all the tools (including the DB systems) are available on various operating systems (supported on Windows, on a number of Linux distributions and on MacOS), with the exception of the IDE (Integrated Development Environment). A very powerful open source IDE, [http://www.icsharpcode.net/OpenSource/SD/ SharpDevelop], is available only for Windows and this is the IDE we use at OM. Another open source IDE, [http://monodevelop.com/ MonoDevelop], is cross-platform and possibly not that powerful (yet). The openPETRA developers in OM haven't tried using MonoDevelop, but it should work, at least as the C# code editor. We do have a fully-fledged build system which is based on NAnt (similar to Ant, but for .NET and not Java), which is cross-platform and that is what we mostly use for compiling anyways.


You can get the source code in several ways:
== Setup by Operating System ==
* see the [https://sourceforge.net/scm/?type=git&group_id=260632 Git instructions at Sourceforge]
Please follow the Link for the operating system of your choice. You are more than welcome to add your own instructions here if the OS of your choice isn't listed here yet and you have found out how to set the development tools up on this OS!
** that page describes how you can download anonymously from Git
* you can also browse the [http://openpetraorg.git.sourceforge.net/git/gitweb.cgi?p=openpetraorg Git repository online], and you can download a tar.gz snapshot there
* the latest release should also provide a download of the source files, see [https://sourceforge.net/project/showfiles.php?group_id=260632&package_id=320122 Download section]


=== Configuration of Windows Development Environment ===
* [[Setup of Development Environment for Windows]]
The recommended way of installing OpenPetra.org for development is to somewhere map a network drive, using the DOS command <code> subst</code>
* [[Setup of Development Environment for Debian]]
* [[Setup of Development Environment for Ubuntu]]
* [[Setup of Development Environment for OpenSuSE]]
* [[Setup of Development Environment for CentOS]]
* [[Setup of Development Environment for Mandriva]]
* [[Setup of Development Environment for MacOS]]


For example:
== Source Code and Database Configuration Architecture ==
mkdir c:\development
Once you have the development tools installed, it will help if you have an overview of how they all fit together.
subst u: c:\development
download the git repository into u:\OpenPetra (it contains the .git directory, and the OpenPetra.build: U:\OpenPetra\OpenPetra.build, etc)
URL of the git repository:
    anonymous access: git://openpetraorg.git.sourceforge.net/gitroot/openpetraorg
    developer access: ssh://USERNAME@openpetraorg.git.sourceforge.net/gitroot/openpetraorg
      make sure that you set your username and email address in your git client


* you need to make a copy of the file OpenPetra.build-sample-windows.config and call it OpenPetra.build.config
* [[Source Configuration Architecture]]
copy OpenPetra.build-sample-windows.config OpenPetra.build.config
* [[Database Configuration Architecture]]


=== Configuration of Linux Development Environment ===
== quick setup of development environment ==
for anonymous access:
* see also [[Quick Setup of Development environment]] if you don't actually need a branch on Launchpad, etc
cd ~
git clone git://openpetraorg.git.sourceforge.net/gitroot/openpetraorg
cd openpetraorg
cp OpenPetra.build-sample-linux.config OpenPetra.build.config


for developer access (with write permissions):
== Use another database system ==
cd ~
The development environment is initially set up using SQLite as the default database system. This is the easiest way to get a quick start as no RDBMS needs to be installed for that. For serious development on OpenPetra it makes more sense to use either the PostgreSQL or MySQL RDBMS because...
git clone ssh://USERNAME@openpetraorg.git.sourceforge.net/gitroot/openpetraorg
* Unless somebody installs OpenPetra for demo purposes, OpenPetra would be running off the PostgreSQL RDMBS or off the MySQL RDBMS in a production environment, so we want to check the codebase we are working with against the production RDBMS as we are developing;
git config user.name "YOUR NAME"
* Another aspect is that when we are using the PostgreSQL RDBMS or MySQL RDBMS for development, the performance of the RDBMS we use is more comparable to a deployed OpenPetra installation.
git config user.email "USERNAME@users.sourceforge.net"
cd openpetraorg
cp OpenPetra.build-sample-linux.config OpenPetra.build.config


== NAnt ==
To switch to another database system, please follow these steps:
There is a central NAnt script that is able to generate a lot of code and is able to do all automated tasks in the OpenPetra project.
 
* Change resp. in the first use create your [[https://sourceforge.net/apps/mediawiki/openpetraorg/index.php?title=User_defined_configuration_parameters_with_OpenPetra.build.config OpenPetra.build.config]] file
** Change the value of DBMS.Type to 'postgresql' or 'MySQL'
** Enter the username and password of the user you created (for Postgres: see [[Notes about PostgreSQL#Creating_a_user | this wiki page]]) in DBMS.Password and DBMS.Password.
 
* If you haven't yet performed the tasks mentioned in [[Setup of Development environment#initial steps | initial steps]] then please skip the next steps and continue with the next section of this wiki page instead.
* ''Otherwise'' you can run <code>nant recreateDatabase</code> and <code>nant resetDatabase</code> which will create the database and load the base and demo data, respectively.
** Run <code>nant startPetraServer</code> (if you get a Windows Firewall message at this point see [[Setup of Development environment#Starting_OpenPetra |here]]), which will copy the correct .config file and start the OpenPetra Server. The switch to the other database system succeeded if no error is shown when the server starts up.
** Optional: Run <code>nant startPetraClient</code> to start up the OpenPetra Client to verify that the login to the OpenPetra Server works.
 
== Compiling (NAnt script info) ==
After completing all the steps that are involved in the setup of your development environment on the operating system of your choice, you are ready for the compiling and starting of openPETRA!
 
Our NAnt files are split up in several pieces. A small NAnt file is located in most directories. It will include a central NAnt file according to what is needed. The central NAnt files are located in ''inc/nant''. Most targets are available in all directories of our code base.
 
=== Local Configuration (required) ===
 
see [[User_defined_configuration_parameters_with_OpenPetra.build.config]]


=== get help ===
=== get help ===
To see the available commands, just run on the command line:
To see the available commands, just go to the root directory of the checked out openPetra and run the command line:
cd OpenPetra
  nant help
  nant help
or
nant -projecthelp
Be aware, that nant -projecthelp only shows the help information of targets, which are directly defined in the build file, but not in the imported buildfile!
=== Initial steps ===
====Generation Solution and Project Files====
First one needs to generate the C# Project and Solution files and do a full compile of the OpenPetra source code. This is done by issuing a single command (which will take a while to run):
nant generateSolution


=== initial steps ===
It is recommended to send the nant output to a file because the program otherwise sends >1 MB text output to the console, which is a time consuming process (indeed it is a PC-blocking process if you have only one CPU). When sending the output to a file one has to use a text editor to check the last line of the file to see whether the command was successful or not and one needs to delete the file afterwards, but it's still faster than having the output scrolling on the console.
First you need to compile the PetraTools which is a set of programs for creating databases and more:
nant compileCommon
nant compilePetraTools


Now you need to create a database. If you don't change the config file, the SQLite database system will be used.
[[File:Create-A-Project-0.JPG]]
 
Note: The <code>nant generateSolution</code> command can only generate the C# Project and Solution files if all the source code compiles. This should be the case with a fresh checkout of the code from trunk, but in case it isn't, use
<code>nant generateSolutionNoCompile</code> to get the C# Project and Solution files.
 
<code>nant generateSolution</code> or <code>nant generateSolutionNoCompile</code> each create C# Project and Solution files in specific directories (see [[Build system with our own NAnt tools and tasks|nant generateProjectFiles]]). These directories each contain all C# Project and Solution files (more than 180 files!) in the respective IDE format.
 
====Opening a Solution in the IDE of your choice====
The best and easiest way to open a Solution is to use the respective IDE command for opening a Project or Solution. Navigate to the path where <code>nant generateSolution</code> or <code>nant generateSolutionNoCompile</code> put the project and solution files (see last paragraph), click into the listbox that lists all the files and start typing the characters "op". This causes the Solutions to be scrolled into view (OpenPetra.Client.sln, OpenPetra.Server.sln, OpenPetra.sln, OpenPetra.Testing.sln and OpenPetra.Tools.sln). <code>OpenPetra.sln</code> contains all C# Project files and is therefore the one that gives one the best overview of the OpenPetra source code.
 
Note: The Solution and Projectfile generation process can be speeded up a bit by specifying one specific IDE, the effect is that only Solution and Projectfiles in one IDE format are generated. See [[here]] for how to do this.
 
====Creating a Database====
Now one needs to create a database. The SQLite RDBMS will be used if one does not add a nant configuration file called ''OpenPetra.build.config'' containing a Property named ''DBMS.Type'' before one issues the <code>nant recreateDatabase</code> command. See [[User defined configuration parameters with OpenPetra.build.config]] for more details on how to create and populate this configuration file or if you get a "we do not support sqlite databases with passwords" error (see example for using SQLite on page linked above).
 
Creating the Database:
  nant recreateDatabase
  nant recreateDatabase


Then you want to load the database with base data:
After creation of the database one needs to load base (demo) data into the database to be able to use it (a login to OpenPetra isn't possible if this isn't done!):
  nant resetDatabase
  nant resetDatabase


You should compile OpenPetra.org this way:
====Starting OpenPetra====
nant compilePetra
 
Start the OpenPetra.org Server:
Start the OpenPetra.org Server:
  nant startPetraServer
  nant startPetraServer


Start the OpenPetra.org client:
When you start the OpenPetra server for the first time you will see a Windows Firewall message that says that it has blocked some features. Put a tick into the 'Domain networks, such as a workplace network' CheckBox and then choose 'Allow access' in this dialogue.
 
Start the OpenPetra.org Client:
  nant startPetraClient
  nant startPetraClient


With the base database, there is the user '''demo''' with password '''demo''' that you can use to login to your installation of OpenPetra.org.
The base database contains user '''demo''' with password '''demo''' (ICT Version: '''DEMODEMO1''') that one can use to login to OpenPetra.org. Logging in with user '''sysadmin''' and password '''CHANGEME''' (capital letters!) (ICT Version: '''CHANGEME1''') allows one to create more users, to backup the database, to restore a database, etc.


See [[Preview: Current functionality]] for information what is actually working already.
See [[Basic Tutorial]] for an overview of some basic functionality of OpenPetra.


Stop the OpenPetra.org Server:
====Stopping OpenPetra====
Stopping the OpenPetra.org client is as easy as closing the Main Menu.
 
To stop the OpenPetra.org Server issue the following command:
  nant stopPetraServer
  nant stopPetraServer


Generate the translation files:
=== further steps ===
  nant translation
 
==== Targets in source directories ====
 
'''clean''': Remove generated files and output files
 
'''uncrustify''' or '''indent''': re-formats the source files in the directory according to programming guidelines
 
'''depend''': find out dependencies in sub-project and generates nant files in the source directories
 
'''compile''': Compiles the source files in this directory
 
'''generateCsproject''': Generate the project file for this directory
 
 
==== Creating a new source sub-directory ====
 
Just add the directory and put the source files into it. Run
  nant generateSolution
will regenerate the project files and add it to the solution. (In case this doesn't work, try to run <code>nant quickClean</code> and then <code>nant generateSolution</code>.)
 
Based on the directory ICT\Petra\Server\lib\MFinance\GL I've created ICT\Petra\Server\lib\MFinance\GL\Test and I've inserted a initializing file Test.GL.Revaluation.cs containing the ''namespace Test.Ict.Petra.Server.MFinance.GL'' and some other followed by an empty bracket (or some content) and some using commands. The file has been found and integrated into a project.
 
If the new directory contains yaml files, you need to add the new directory in the file <code>csharp\ICT\Petra\Client\Ict.Petra.Client.build</code> to the property "directories-with-yaml".
 
==== Adding new files to an existing project ====
Careful: when you add a new cs file directly in SharpDevelop, the file will be stored in <code>delivery\projects\sharpdevelop4</code>, and that is the wrong place. So the best is to create the file manually in the directory in eg csharp\ICT\Common\IO, where it should live, and then on the command line:
cd csharp\ICT\Common\IO
  nant generateCsprojectNoCompile
 
==== Adding a new Third Party Dll ====
We have some third party dlls in csharp/ThirdParty. They are published with a license that is compatible to the GPL, so we are allowed to use them with OpenPetra. There is usually a readme file which refers to the sources of that dll, and instructions how to build it or which things we have modified. Sometimes we have added small patches to the directory.
 
When adding a new third party dll, you also must add a reference to the file <code>csharp/ThirdParty/ThirdParty.build</code>, in the section 3rdPartyPattern.
 
== Testing ==
 
see [[Working with NUnit tests]]

Latest revision as of 04:41, 16 March 2023

Update April 2020

We now have a development environment for CentOS/Fedora, Ubuntu and Debian.

See instructions at Quick Setup of Development environment

The following information stays for a while because the friends at OM are still working on Windows.

Overview and Introduction

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!

The openPETRA developers in OM work on Windows, but all the tools (including the DB systems) are available on various operating systems (supported on Windows, on a number of Linux distributions and on MacOS), with the exception of the IDE (Integrated Development Environment). A very powerful open source IDE, SharpDevelop, is available only for Windows and this is the IDE we use at OM. Another open source IDE, MonoDevelop, is cross-platform and possibly not that powerful (yet). The openPETRA developers in OM haven't tried using MonoDevelop, but it should work, at least as the C# code editor. We do have a fully-fledged build system which is based on NAnt (similar to Ant, but for .NET and not Java), which is cross-platform and that is what we mostly use for compiling anyways.

Setup by Operating System

Please follow the Link for the operating system of your choice. You are more than welcome to add your own instructions here if the OS of your choice isn't listed here yet and you have found out how to set the development tools up on this OS!

Source Code and Database Configuration Architecture

Once you have the development tools installed, it will help if you have an overview of how they all fit together.

quick setup of development environment

Use another database system

The development environment is initially set up using SQLite as the default database system. This is the easiest way to get a quick start as no RDBMS needs to be installed for that. For serious development on OpenPetra it makes more sense to use either the PostgreSQL or MySQL RDBMS because...

  • Unless somebody installs OpenPetra for demo purposes, OpenPetra would be running off the PostgreSQL RDMBS or off the MySQL RDBMS in a production environment, so we want to check the codebase we are working with against the production RDBMS as we are developing;
  • Another aspect is that when we are using the PostgreSQL RDBMS or MySQL RDBMS for development, the performance of the RDBMS we use is more comparable to a deployed OpenPetra installation.

To switch to another database system, please follow these steps:

  • Change resp. in the first use create your [OpenPetra.build.config] file
    • Change the value of DBMS.Type to 'postgresql' or 'MySQL'
    • Enter the username and password of the user you created (for Postgres: see this wiki page) in DBMS.Password and DBMS.Password.
  • If you haven't yet performed the tasks mentioned in initial steps then please skip the next steps and continue with the next section of this wiki page instead.
  • Otherwise you can run nant recreateDatabase and nant resetDatabase which will create the database and load the base and demo data, respectively.
    • Run nant startPetraServer (if you get a Windows Firewall message at this point see here), which will copy the correct .config file and start the OpenPetra Server. The switch to the other database system succeeded if no error is shown when the server starts up.
    • Optional: Run nant startPetraClient to start up the OpenPetra Client to verify that the login to the OpenPetra Server works.

Compiling (NAnt script info)

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

Our NAnt files are split up in several pieces. A small NAnt file is located in most directories. It will include a central NAnt file according to what is needed. The central NAnt files are located in inc/nant. Most targets are available in all directories of our code base.

Local Configuration (required)

see User_defined_configuration_parameters_with_OpenPetra.build.config

get help

To see the available commands, just go to the root directory of the checked out openPetra and run the command line:

nant help

or

nant -projecthelp

Be aware, that nant -projecthelp only shows the help information of targets, which are directly defined in the build file, but not in the imported buildfile!

Initial steps

Generation Solution and Project Files

First one needs to generate the C# Project and Solution files and do a full compile of the OpenPetra source code. This is done by issuing a single command (which will take a while to run):

nant generateSolution

It is recommended to send the nant output to a file because the program otherwise sends >1 MB text output to the console, which is a time consuming process (indeed it is a PC-blocking process if you have only one CPU). When sending the output to a file one has to use a text editor to check the last line of the file to see whether the command was successful or not and one needs to delete the file afterwards, but it's still faster than having the output scrolling on the console.

Create-A-Project-0.JPG

Note: The nant generateSolution command can only generate the C# Project and Solution files if all the source code compiles. This should be the case with a fresh checkout of the code from trunk, but in case it isn't, use nant generateSolutionNoCompile to get the C# Project and Solution files.

nant generateSolution or nant generateSolutionNoCompile each create C# Project and Solution files in specific directories (see nant generateProjectFiles). These directories each contain all C# Project and Solution files (more than 180 files!) in the respective IDE format.

Opening a Solution in the IDE of your choice

The best and easiest way to open a Solution is to use the respective IDE command for opening a Project or Solution. Navigate to the path where nant generateSolution or nant generateSolutionNoCompile put the project and solution files (see last paragraph), click into the listbox that lists all the files and start typing the characters "op". This causes the Solutions to be scrolled into view (OpenPetra.Client.sln, OpenPetra.Server.sln, OpenPetra.sln, OpenPetra.Testing.sln and OpenPetra.Tools.sln). OpenPetra.sln contains all C# Project files and is therefore the one that gives one the best overview of the OpenPetra source code.

Note: The Solution and Projectfile generation process can be speeded up a bit by specifying one specific IDE, the effect is that only Solution and Projectfiles in one IDE format are generated. See here for how to do this.

Creating a Database

Now one needs to create a database. The SQLite RDBMS will be used if one does not add a nant configuration file called OpenPetra.build.config containing a Property named DBMS.Type before one issues the nant recreateDatabase command. See User defined configuration parameters with OpenPetra.build.config for more details on how to create and populate this configuration file or if you get a "we do not support sqlite databases with passwords" error (see example for using SQLite on page linked above).

Creating the Database:

nant recreateDatabase

After creation of the database one needs to load base (demo) data into the database to be able to use it (a login to OpenPetra isn't possible if this isn't done!):

nant resetDatabase

Starting OpenPetra

Start the OpenPetra.org Server:

nant startPetraServer

When you start the OpenPetra server for the first time you will see a Windows Firewall message that says that it has blocked some features. Put a tick into the 'Domain networks, such as a workplace network' CheckBox and then choose 'Allow access' in this dialogue.

Start the OpenPetra.org Client:

nant startPetraClient

The base database contains user demo with password demo (ICT Version: DEMODEMO1) that one can use to login to OpenPetra.org. Logging in with user sysadmin and password CHANGEME (capital letters!) (ICT Version: CHANGEME1) allows one to create more users, to backup the database, to restore a database, etc.

See Basic Tutorial for an overview of some basic functionality of OpenPetra.

Stopping OpenPetra

Stopping the OpenPetra.org client is as easy as closing the Main Menu.

To stop the OpenPetra.org Server issue the following command:

nant stopPetraServer

further steps

Targets in source directories

clean: Remove generated files and output files

uncrustify or indent: re-formats the source files in the directory according to programming guidelines

depend: find out dependencies in sub-project and generates nant files in the source directories

compile: Compiles the source files in this directory

generateCsproject: Generate the project file for this directory


Creating a new source sub-directory

Just add the directory and put the source files into it. Run

 nant generateSolution 

will regenerate the project files and add it to the solution. (In case this doesn't work, try to run nant quickClean and then nant generateSolution.)

Based on the directory ICT\Petra\Server\lib\MFinance\GL I've created ICT\Petra\Server\lib\MFinance\GL\Test and I've inserted a initializing file Test.GL.Revaluation.cs containing the namespace Test.Ict.Petra.Server.MFinance.GL and some other followed by an empty bracket (or some content) and some using commands. The file has been found and integrated into a project.

If the new directory contains yaml files, you need to add the new directory in the file csharp\ICT\Petra\Client\Ict.Petra.Client.build to the property "directories-with-yaml".

Adding new files to an existing project

Careful: when you add a new cs file directly in SharpDevelop, the file will be stored in delivery\projects\sharpdevelop4, and that is the wrong place. So the best is to create the file manually in the directory in eg csharp\ICT\Common\IO, where it should live, and then on the command line:

cd csharp\ICT\Common\IO
nant generateCsprojectNoCompile

Adding a new Third Party Dll

We have some third party dlls in csharp/ThirdParty. They are published with a license that is compatible to the GPL, so we are allowed to use them with OpenPetra. There is usually a readme file which refers to the sources of that dll, and instructions how to build it or which things we have modified. Sometimes we have added small patches to the directory.

When adding a new third party dll, you also must add a reference to the file csharp/ThirdParty/ThirdParty.build, in the section 3rdPartyPattern.

Testing

see Working with NUnit tests