[Mono-list] Setting up the build environment (FAQ)

Sun, 4 Nov 2001 08:48:47 -0600

This is a multi-part message in MIME format.

------=_NextPart_000_00A8_01C1650D.843B8D00
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit

Does this help?

----- Original Message -----
From: "Nicholas Hynes" <nhynes@ezysurf.co.nz>
To: "Mono" <mono-list@ximian.com>
Sent: Sunday, November 04, 2001 2:57 AM
Subject: [Mono-list] Setting up the build environment (FAQ)

> Hi All,
>
> Okay, I know real hackers would want to work this out for themselves, but
> I've got limited time, and configuration isn't my real strength. Besides,
> maybe this should be on the FAQ page.
>
> I'm looking at doing some work on the test harness, and I want to get
> straight into coding.
>
> Can someone give me an _outline_ of the basic steps involved in getting
the
> class library working...
>
> I think it goes something like this:
>
>     1/ Install the MS C# compiler (SDK option only?)
>     2/ Check out (the entire?) CVS source tree (from system. outwards) as
> per instructions on www.go-mono.org/.
>     3/ Sanity check?
>     4/ Anything else?
>
>
> P.S. I'll be using my Windows 2000 box for building the project, but will
> probably create a cvs repository on my linux box for managing updates etc.
>
>
> Cheers,
> - Nick Hynes.
>
>
>
> _______________________________________________
> Mono-list maillist  -  Mono-list@ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-list
>

------=_NextPart_000_00A8_01C1650D.843B8D00
Content-Type: text/plain;
	name="monotesting.txt"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
	filename="monotesting.txt"

** So you want to be a Mono tester?
** Getting Started
** The components of the Mono distribution
** What am I actually testing?
** What libraries should I write tests for?
** Understanding the MonoTests namespace
** How do I write a test?
** The test is written, now how do I run it?=20
** I've written a test and it seems to: work great/break =
something/reinvent the wheel/turn water to wine=85

** So you want to be a Mono tester?

Perhaps one of the most important pieces that will help the Mono =
movement is the authoring of test cases. When there is a successful test =
suite in place (a suite being a group of tests), the developers have the =
freedom to make changes and implement new code at a more rapid pace. =
They are able to do this because they can find out quickly if they have =
broken previous code by simply running the test suite.

You don't need to be an ace programmer to write test cases. Most of you =
should be able to go out and read some C# tutorials on the web and get =
started shortly thereafter. Once you pick a class to write cases =
against, you can then refine your knowledge of that class specifically =
and code tests that will be helpful and, usually, quite simple.

** Getting Started

First things first, you need to get some basic items installed. All of =
this work must currently be done in Windows.

1) The Microsoft =99 .NET Framework SDK: <a =
href=3D"http://msdn.microsoft.com/downloads/default.asp?URL=3D/code/sampl=
e.asp?url=3D/msdn-files/027/000/976/msdncompositedoc.xml">http://msdn.mic=
rosoft.com/downloads/default.asp?URL=3D/code/sample.asp?url=3D/msdn-files=
/027/000/976/msdncompositedoc.xml</a>
You need this installed for a couple of reasons. First it has the MSDN =
documentation including a C# reference and tutorial section which is =
invaluable. Second, the compiler for Mono isn't ready yet, so in order =
to compile the Mono class libraries and test cases you currently need =
the .NET SDK (more on this later)

2) Cygwin: <A =
HREF=3D"http://www.cygwin.com/setup.exe">http://www.cygwin.com/setup.exe<=
/A>

This is going to give you the tools you need to use the =93make files=94 =
and other shell utilities that assist in compiling Mono

3) The latest Mono snapshot: <A =
HREF=3D"http://www.go-mono.com/download.html">http://www.go-mono.com/down=
load.html</A>

Thanks to diligent work by the developers (and test case authors J ) the =
snapshots are usually very stable and reliable.
Follow the instructions on that page under the heading =93To install and =
work on the compiler and class libraries=94. This will build mcs and the =
class libraries (more on these later).=20

4) Nunit: <A =
HREF=3D"http://www.sourceforge.net/projects/nunit">http://www.sourceforge=
.net/projects/nunit</A>

This is the software you use to execute test cases. It is also included =
in the Mono distribution but it is useful to install it separately so =
that you get the excellent NUnit documentation. There is research under =
way to determine what it would take to get the console version of NUnit =
running under Linux, but for now it's only going to run on Windows.

** The components of the Mono distribution

This is where some people get lost, trying to figure out what's what and =
how the directory structure works. Some basics:

=93Mono=94 refers to the entire project including the compiler, =
runtime, and class libraries. However, currently the compiler, =
=93mcs=94, is located in a separate directory structure. This =
will change at some point in the future, so keep an eye out.

So after a default compile, you will have the following:=20

<B>/gtk-sharp</B>
- This contains the bindings for C# to the GTK libraries. I won't go =
into it because I haven't done anything with it myself

<B>/mono</B>
- This contains the files for building the runtime. You don't know what =
the runtime is? Go read some more about C# J

<B>/mcs</B>
- This is where the compiler and class libraries reside.=20

<B>/mcs/nunit </B>
- Contains the NUnit program, which you'll use to execute test cases.

<B>/mcs/class/corlib</B>
- This holds the source and tests for the core class libraries needed =
for C# compilation. Most of your work will be done in here.

Under the /mcs/class/corlib directory you will find the source code for =
all of the class libraries that have been--at least =
partially-implemented. You will also find a directory called Test which =
should contain-eventually-a corresponding directory for each class =
contained in the corlib directory. For example:

<B>corlib/System.Collections</B> - will contain the actual source code =
for the System.Collections class library
<B>corlib/Test/System.Collections</B> - will contain tests written for =
System.Collections
<B>corlib/lib</B> - contains the actual compiled .dll's that tests will =
be run against

Tests that you create will reside in the appropriate directory under =
corlib/Test/. So if you were creating a test against System.Collections, =
you'd put the test in corlib/Test/System.Collections. This keeps =
everything neat and ensures the tests you write get built properly.=20

** What am I actually testing?

You will be writing tests against the Mono versions of the C# class =
libraries. Don't know what class libraries are? Go read a quick tutorial =
on OOP=20

** What libraries should I write tests for?

Many factors come into play here including experience, desire, need.=20

Experience - Are you particularly adept with a certain class or =
mechanism of C#, for example Collections or Diagnostics?=20
Desire - Do you have an interest in a certain area of the language?
Need - Are there holes in the test suite so far? (empty or non-existent =
directories in the CVS indicate that test have not likely been written =
yet). This is true of almost all the classes, and will continue to be =
for the near future.

In all cases, look up the maintainer of the class library =
(<http://www.go-mono.com/class-status/index.html>) and drop them an =
email to make sure you're not duplicating something they've implemented =
but maybe haven't checked into CVS yet. In addition they may have =
specific tests they'd like to see, or hints on where you might be able =
to find holes in the code.

** Understanding the MonoTests namespace=20

As the test library grows it becomes quite important to be able to =
automate suites of tests. This is only possible when the tests follow a =
standardized set of namespace conventions. For a complete reference on =
namespaces consult the .NET framework documentation. However, it may be =
summarized as follows: a namespace is a way of grouping similar classes =
so that they can be easily imported, referenced and utilized.=20

The Mono project has implemented a structure to organize and automate =
test building and execution. It has been decided that all tests will =
reside in the MonoTests name space. To better organize the tests by the =
purpose they server, and the modules they test, subcategories of the =
MonoTests namespace will be used. For example a test for the System =
library would reside in the MonoTests.System namespace. So if you were =
implementing a test for the System class library called MyTest, you =
would declare as such:=20

<B>using NUnit.Framework;=20
using System;=20

namespace MonoTests.System {=20

    public class MySystemTest : TestCase {...}=20

        } </B>

and then it could be referenced MonoTests.System.MySystemTest.=20

The AllTests.cs file in the main Tests directory has been designed with =
a class called AllTests for each subdirectory of the Tests directory. =
This will allow someone to run all tests for a given class if so =
desired, such as MonoTests.System.Collections.AllTests.=20

Keep these guidelines in mind when designing your test classes.=20

** How do I write a test?

Rather than repeat something that's already been described wonderfully, =
I'll ask you to reference the =93Test Infected=94 document included with =
the NUnit distribution, and also available at nunit.sourceforge.net. =
Then, when it is time to write the case, include the class library you =
are going to test by utilizing the =93using=94 statement as describe in =
the C# documentation. For example:

<B>using System;
using NUnit.Framework;
{=85..test code here as described in the NUnit docs=85.}
</B>

Save the test as a .cs file in the proper subfolder under test. Then, =
make sure that you have nant in your PATH environment variable. Nant is =
located in <where you built mono>/mcs/nant . Switch to the =
corlib/Test directory and run:=20

<B>nant build</B>

This will compile all the test cases (including yours) into the =
<B>corlib_test.dll</B> in the <B>corlib/Test</B> directory.=20

** The test is written, now how do I run it?=20

With NUnit, tests must first be compiled into a DLL. Then when you =
reference the DLL (from the nunitconsole.exe) or open it (from the =
nunitgui.exe), you will be able to access the list of namespaces and =
classes inside.=20

All the work of compiling your tests into a DLL has been done for you. =
First make sure you have completed your test case, and stored it in the =
proper namespace and subdirectory of Test. Then, open Cygwin and cd to =
the mcs/class/corlib/Test folder and run:=20

../../../nant/nant build=20

(alternately you can add the mcs/nant/ directory to your PATH so you =
don't have to reference the ../../../).=20

This is going to create the corlib_test.dll in the Test directory. As =
mentioned, this is a DLL, or assembly, containing all of the tests =
written so far.=20
You will load/reference this DLL in order to specify which tests you =
want to run. The two methods by which you would do this vary slightly.=20

Let's assume you want to run the test suite MonoTests.System.AllTests. =
If you are using the console version of nunit, you'd want to cd to the =
directory containing corlib_test.dll and run:=20

../../../NUnitconsole MonoTests.System.AllTests,corlib_test.dll=20

If you are using the GUI version of NUnit, just browse to the =
corlib_test.dll in the Assembly input box. Then you will be able to =
choose the MonoTests.System.AllTests item from the Type Name input.=20

** I've written a test and it seems to: work great/break =
something/reinvent the wheel/turn water to wine=85

Great! You've just made a much appreciated contribution to the Mono =
project. If you think you've exposed an error, double check your work to =
make sure that you don't have bugs of your own. Check the MSDN =
documentation to verify you are trying to do something that is legal in =
the language. Once you're certain your test case is valid, it's time to =
send it off to the class maintainer. Clean up the code spacing and be =
sure to comment if you think it might not be clear what you are testing. 
------=_NextPart_000_00A8_01C1650D.843B8D00--