Getting Started with the NHibernate Source Code

Whether you want to customize NHibernate to add a custom feature, or you want to fix a bug that you needed yesterday for your own project, or you just want to give something back to the NHibernate community, NHibernate, being open source, its source code is right there for anyone who has the desire to dive into. However, it is often asked that, "how do I get started?" This short article is created to help you do just that.

Tools required

The following are the tools that you will need if you wish to follow the instructions in this article:

• Visual Studio 2005
• NAnt (http://nant.sourceforge.net/)
• NUnit (http://nunit.org)
• A Subversion client such as the svn command line tool (http://subversion.tigris.org/) or TortoiseSVN (http://tortoisesvn.tigris.org/).

Set up the environment

Check out a working copy of the source code

As of the time of this writing, the trunk is located at https://nhibernate.svn.sourceforge.net/svnroot/nhibernate/trunk/nhibernate/. Check out a copy using the svn command line tool or TortoiseSVN.

Run nant

IMPORTANT: Before opening up one of the Visual Studio solutions, you must run nant visual-studio on the command line in the nhibernate directory (i.e. where default.build is located). Doing so generates a few files, including the AssemblyInfo.cs files in each project.

NOTE: If the complete build fails, which can happen from time to time on the trunk, it is quite possible that you can still proceed. The developers at NHibernate try hard to not break the build; at least not the core project (NHibernate.csproj) and the core tests (NHibernate.Test.csproj). If the piece of work that you are planning on doing is in the core set of features, there is a good chance that the broken pieces will not affect what you want to work on.

Configure NHibernate for your test environment

The default test configuration of NHibernate connects to a database named "nhibernate" on the default instance of Microsoft SQL Server 2000 running on the localhost using Integrated Security. If your configuration is different, create a file named hibernate.cfg.xml under src\NHibernate.Test and customize your connection there. DO NOT change App.config. There are a few templates located in src\NHibernate.Config.Templates; you may copy one of these as the starting point for your set-up.

Open up the Visual Studio solution

Under the src directory, you can open either the NHibernate-2.0.sln or NHibernate.Everything-2.0.sln solution. The NHibernate-2.0.sln consist of only the NHibernate-2.0, NHibernate.Test-2.0, and NHibernate.DomainModel-2.0 projects. The NHibernate.Everything-2.0.sln solution consist of, well, those projects and everything else. You are recommended to use the NHibernate.Everything-2.0.sln solution so as to ensure everything at least still compiles after any changes that you will make. If building NHibernate.Everything-2.0.sln fails because the build is broken (which should rarely happen), then use the NHibernate-2.0.sln solution; it should always be buildable.

Configure the NHibernate.Test-2.0 project

If you want to be able to just press F5 and debug NHibernate, do the following:

1. Right-click on the NHibernate.Test-2.0 project and choose "Properties"
2. Under the "Start Action" section, choose the "Start external program" option
3. Enter the path to the NUnit GUI executable as the program to start (nunit-gui.exe for NUnit 2.2.x, or just nunit.exe for NUnit 2.4.x)
4. Under the "Start Options" section, enter "NHibernate.Test.dll" as the command line arguments
5. [Optional] Tag on any other nunit command line option that you want to use. A particularly useful one is /fixture:Fully.Qualified.Name.Of.Fixture.

Set NHibernate.Test-2.0 as the start-up project

Just right-click on the NHibernate.Test-2.0 project and select "Set as StartUp Project".

Run the tests before you start

Press "F5" and run the tests in NHibernate.Test before you change anything. You really don't want to spend hours trying to make a test green, then realize the test was broken before you even started.

Write tests

Now that your environment is all set up, it is time to write some code. To be precise, it is time to write a test. The instructions that follows assumes you are doing this to investigate a JIRA issue. If you are building a new feature or doing something else, the process is similar, just look at the tests that are already written to learn how it has been done. If you are confident enough to dive into the NHibernate source code, we assume that you are competent enough to understand code written by others.

Create a folder for your the JIRA issue

In the NHibernate.Test project Under the NHSpecificTest folder, create a subfolder named NHnnn where nnn is the issue number (e.g. NH1234). By creating this folder, you are also creating a namespace specific for your test(s).

It is actually better to give tests a descriptive name, otherwise one can't tell at a glance what each test is for. I believe that my original idea to name the test cases by JIRA issues was a mistake on my part. -- Sergey Koshcheyev

Create a test fixture

Under the NHnnn folder, create a class and name it Fixture. Make the Fixture class inherit from BugTestCase. Do so gives you a few conveniences; which will be explained later.

Create the mapping file(s)

Create a mapping file under the NHnnn folder; and do not forget to change it to an "Embedded Resource". If you name the mapping file Mappings.hbm.xml, the BugTestCase base class automatically loads it when the fixture is executed. Otherwise, you will have to override the Mappings property to return an IList of mapping file resource names as in the following:

    protected override IList Mappings
    {
        get
        {
            return new string[]
                {
                    "NHSpecificTest.NH1234.Person.hbm.xml",
                    "NHSpecificTest.NH1234.Address.hbm.xml",
                    "NHSpecificTest.NH1234.Phone.hbm.xml",
                };
        }
    }

Create the model -- the mapped class(es)

Create the classes that you need in the same folder (e.g. the Person, Address, and Phone class in the above example).

Create a test case

It is obvious that you will need one or more test. Without much explanation, here is what a typical test (including the fixture) may look like:

using NUnit.Framework;

using System;
using System.Collections.Generic;

namespace NHibernate.Test.NHSpecificTest.NH1234
{
    [TestFixture]
    public class Fixture : BugTestCase
    {
        protected override void OnSetUp()
        {
            // Whatever set up you need to do
        }
        
        protected override void OnTearDown()
        {
            // Clean up anything that may got left behind.
            // Otherwise, the test will fail.
            // The easiest way may be like this:
            using (ISession s = OpenSession())
            {
                s.Delete("from Phone");
                s.Delete("from Address");
                s.Delete("from Person");
            }
        }
        
        [Test]
        public void SomeSensibleName()
        {
            using (ISession s = OpenSession())
            using (ITransaction tx = s.BeginTransaction())
            {
                // Test what you need to test here
                tx.Commit();
            }
            
            // You may use more than one "using (ISession ...)" block
            // like the one above.
        }
    }
}

Press "F5", start debugging, and go green

At this point, it is all standard .NET development things that you should already know -- like setting breakpoints and stepping through the code. It is important that patch you submit is "green"; that is, before you create the patch, please run all the tests in NHibernate.Test and make sure you have not broken any tests (at least not any tests that were not broken before).

Give back

If you have been following the instructions in this article to fix an issue in JIRA or implement a new feature the the community, first let me thank you for making an effort to contribution to NHibernate.

Now you have a working copy with a fixed issue, run the full suite of tests to ensure you have not broken anything by running the following command in the "nhibernate" directory:

% nant test-all-frameworks

If all goes well, just open a command prompt at the root of your working copy and create a patch there:

% svn diff > NH1234.patch

Conclusion

This article showed you how to get started with the NHibernate source code; be able to press F5 and start debugging the inards of NHibernate. I have purposefully gloss over a lot of details, but I hope there is enough information here to get you started. If you have any suggestion or wish me to expand on certain details, please send me an email (address given below). It is my hope this article will help you get started on your first effort to contribute to NHibernate. Cheers.

Karl Chu [kchu(at)koah.net]

NEW COMMENT