Version 20 (modified by ibboard, 8 years ago) (diff)

--

Getting Started

The following instructions should help you get started with the WarFoundry source code so that you can explore it and start working with it.

There is also a shorter Quick Start version of this page.

Required Tools

There are only really two main tools needed for developing WarFoundry, a Mercurial client and a development environment. You also need a suitable framework and, for development work, the unit testing libraries.

Note: Originally, we started with Subversion for version control, but as of August 2011 we've moved to Mercurial. While Mercurial may not be instantly familiar to everyone, it makes multi-developer experimentation and contribution easier and more flexible.

.Net Framework/Mono

As WarFoundry is built using C# 2.0 you'll also need a .Net 2.0 compatible framework such as Mono (which may already be installed on some Linux distros) or Microsoft's .Net framework (which may already be installed on some versions of Windows). This is because it includes useful features like Generics without the huge framework download.

Unit Testing

We use NUnit for unit testing. The project was started under MonoDevelop and so uses the version bundled with MonoDevelop (currently 2.4.8), but this should be compatible with a number of earlier versions as well.

When using Visual Studio, you'll need to download and install NUnit v2.4.8. Later versions may not work as the NUnit team restructured their namespace.

Development Environment

All of the WarFoundry projects use Visual Studio 2010 project files. In theory this could be compatible with other versions of Visual Studio, as MonoDevelop can handle all formats, but Microsoft force an update when using the new tools.

For System.Windows.Forms development (Windows-based applications), using Visual Studio 2010 is recommended. Microsoft make versions of Visual Studio 2010 Express available for free. Although they're not as feature complete as the full version and don't (officially) support plugins, they seem more than adequate for the current WarFoundry work.

For GTK# and other non-System.Windows.Forms development, using MonoDevelop is recommended. MonoDevelop is constantly improving and has more features than Visual Studio 2010 Express, as well as a plugin architecture (including SVN and Git support) and a GTK GUI editor.

Other development environments may also be suitable, depending on taste, (e.g. Eclipse with a Mono/.Net plugin, or SharpDevelop) but Visual Studio Express 2010 and MonoDevelop have been adequate and useful for all current development.

Mercurial Client

The easiest way to work with Mercurial is when source control is integrated in to your development environment. Unfortunately, Mercurial plugins for Visual Studio normally come with a price tag and aren't compatible with Visual Studio Express (which leaves you with an even bigger price tag on Visual Studio). If you don't know how to use Mercurial in your chosen IDE or on your chosen desktop then the Mercurial clients page has more information.

Getting the source code

Exact details of how to get the source code will vary by client, but the following are the required projects to work with WarFoundry. You will need to check out all of the required projects for a given GUI from Mercurial to be able to compile and use WarFoundry.

Some projects also have companion "Test" projects. These can be identified by having the same project name, except that ".Tests" is appended. It is recommended that you also download the tests and run them regularly as you make changes to make sure that nothing is broken. Everything should also have unit tests added as/before it is written, although up until now this hasn't been the case.

Note: Mercurial will show you the "default" branch straight after a clone, but your local copy includes all of the history for the repository. To work on a different branch you can just switch branches within your existing copy.

WarFoundry WinForms

WarFoundry API projects, plus:

Project nameMercurial locationDescription
IBBoard.Windows.Forms http://dev.ibboard.co.uk/repos/IBBoard.Windows.Forms Custom System.Windows.Forms controls
IBBoard.WarFoundry.GUI.WinForms http://dev.ibboard.co.uk/repos/IBBoard.WarFoundry.GUI.WinForms System.Windows.Forms interface for WarFoundry

WarFoundry GTK#

WarFoundry API projects, plus:

Project nameMercurial locationDescription
IBBoard.GtkSharp http://dev.ibboard.co.uk/repos/IBBoard.GtkSharp Custom GTK# controls and helper methods
IBBoard.WarFoundry.GUI.GTK http://dev.ibboard.co.uk/repos/IBBoard.WarFoundry.GUI.GTK GTK# interface for WarFoundry

WarFoundry Qt# (Qyoto)

WarFoundry API projects, plus:

Project nameMercurial locationDescription
IBBoard.WarFoundry.GUI.QtSharp http://dev.ibboard.co.uk/repos/IBBoard.WarFoundry.GUI.QtSharp Qt#/Qyoto interface for WarFoundry

WarFoundry API

Project nameMercurial locationDescription
IBBoard http://dev.ibboard.co.uk/repos/IBBoard Core IBBoard utils
IBBoard.Tests http://dev.ibboard.co.uk/repos/IBBoard.Tests Tests for core IBBoard utils (optional - only necessary if you modify the utils library)
IBBoard.NUnit http://dev.ibboard.co.uk/repos/IBBoard.NUnit Extra NUnit methods (optional - currently only required if you get IBBoard.Tests)
IBBoard.WarFoundry.API http://dev.ibboard.co.uk/repos/IBBoard.WarFoundry.API Core API for WarFoundry
IBBoard.WarFoundry.API.Tests http://dev.ibboard.co.uk/repos/IBBoard.WarFoundry.API.Tests Tests for the core WarFoundry API
SharpZipLib http://dev.ibboard.co.uk/repos/SharpZipLib Custom build of SharpZipLib because of bug #311

Contributing

Once you've got the code then you can build and run it. You can also make changes and make local commits, but they won't be visible to anyone else until you share them.

With the move to Mercurial, we are now much more flexible about how developers can contribute to the project. You now do not need to request an account, but can instead fork and update your own copy through our Repository Manager before asking for your changes to be included in the Master copy.

For more details on how to contribute, read the Contributing instructions.