mono/doc/class-library

* The Class Library

	The Class Library should be compatible with Microsoft's .NET
	implementation.

	Please see the <a href="class-status.html">Class Status</a>
	page for a status of who is working on which classes.
	
	We will write as much code as possible in C#. We may need to
	interface with code written in C to gain access to the
	functionality of libraries like libart, Gtk+, and libc.

** Contributing

	We welcome contributions to the the Class Library.  To get
	started, check the status page for information about which
	APIs are being worked on, and how to get in touch with 
	individual maintainers.  

	If you want to work on a class, first check the <a
	href="download.html">Classes Distribution</a> to see if it is
	not implemented yet, if not, check the <a
	href="class-status.html">Class Status</a> to see if someone is
	already working on it, and maybe contact them.

	If nobody is working on it, mail <a
	href="mailto:[email protected]">[email protected]</a>
   	with the class you want to implement and CC <a
	href="mailto:[email protected]">[email protected]</a>.

	You can also track live the activities of the Mono CVS module
	by subscribing to the <a
	href="http://mail.ximian.com/mailman/listinfo/mono-cvs-list">mono-cvs-list</a>



** Layout

	The Class Library resides in the `mcs' module in the directoy
	`class'.
	
	Each directory in the directory represents the assembly where
	the code belongs to, and inside each directory we divide the
	code based on the namespace they implement.

	There are two cases when we should consider portability: when
	we are dealing with a couple of classes only that differ from
	system to system (Consider System.Net and System.IO for Win32
	and Unix).  In those cases we will just place the files for
	example on <t>corlib/System/System.IO/Unix-Console.cs</t> and
	<t>corlib/System/System.IO/Win32-Console.cs</t>.

	For classes that might differ more (for example, the
	implementation of Windows.Forms), we might have different
	directories altogether: <t>System.Windows.Forms/Win32</t>,
	<t>System.Windows.Forms/Gtk+</t> and
	<t>System.Windows.Forms/Cocoa</t>.

** Using existing components from GNOME.

	Our current plan is to implement the GUI tools on top of
	Gtk+.  The only obstacle here is that applications from Windows
	might expect to be able to pull the HWND property from the
	widgets and use PInvoke to call Windows functions.

** Class Library and Win32 dependencies.

	There are a few spots where the Win32 foundation is exposed to
	the class library (for example, the HDC and HWND properties in
	the GDI+). Casual inspection suggests that these can be
	safely mapped to Gdk's GC and GdkWindow pointers without
	breaking anything.

	The only drawback is that support for PInvoke of Win32 code
	won't be available.  An alternate solution would be to use
	portions of Wine, or even to use Wine as our toolkit.

*** Initial GDI+ and WinForms implementation

	The initial implementation will use Gtk+ as the underlying
 	toolkit. Since GTK+ has already been ported to many windowing
	systems other than X (including frame buffer, Win32, and BeOS)
	its use should cover most applications for most users. 
	
*** Database access

	We will implement ADO.NET functionality by reusing <a
	href="http://www.gnome-db.org">GNOME-DB</a>. This is an ideal
	choice, since GNOME-DB was implemented precisely to provide an
	ADO-like system for GNOME.

*** Component Integration

	We will provide a new namespace to use GNOME specific features
	as well as a namespace to host Bonobo interfaces and classes
	in Mono.  

** Licensing

	The class library will be licensed under the terms of the GNU
	LGPL.  Some people have pointed out that the plain LGPL is
	troublesome for embedded use of the Mono class libraries.  So
	we are considering to use the GPL with a special exception
	(like the <a
	href="http://www.gnu.org/software/classpath/classpath.html">GNU
	Classpath</a> project did.

	The exception to the GPL would be:

	<i>The library is distributed under the terms of the GNU General
   	Public License with the following exception:

   	If you link this library against your own program, then you do not
   	need to release the source code for that program. However, any
   	changes that you make to the library itself, or to any native
   	methods upon which the library relies, must be re-distributed in
   	accordance with the terms of the GPL.</i>

	If you are going to contribute, please keep in mind that we
	might require you to agree that Ximian might adjust the
	license to enable the use of the class libraries on embedded
	systems or to develop proprietary applications using Mono.

	We suggest that you assign the copyright of your work to the
	GNOME Foundation or the Free Software Foundation to simplify
	defending the code in case it is used inappropiately. 

** Class Library testing

	We need to write regression tests that will verify
	the correctness of the class library, compiler, and JIT
	engine.

	Please write your regression tests using <a
	href="http://nunit.sourceforge.net">NUnit</a>

** Coding conventions

	Please follow the conventions on the ECMA specification (On
	the Annex Partition) for your coding your libraries. 

	Use 8 space tabs for writing your code (hopefully we can keep
	this consistent).  If you are modifying someone else's code, try
	to keep the coding style similar.

	For a rationale on 8 space tabs, read Linus Torvald's Coding
	Style guidelines in the Linux kernel source for a rationale. 

*** Missing implementation bits

	If you implement a class and you are missing implementation bits,
	please put in the code the word "TODO" and a description of what
	is missing to be implemented.

*** Tagging buggy code

	If there is a bug in your implementation tag the problem by using
	the word "FIXME" in the code, together with a description of the 
	problem.

	Do not use XXX or obscure descriptions, because otherwise people
	will not be able to understand what you mean.

*** Tagging Lame specs

	Sometimes the specification will be lame (consider Version.ToString (fieldCount)
	where there is no way of knowing how many fields are available, making the API
	not only stupid, but leading to unreliable code).

	In those cases, use the keyword "LAMESPEC".

** FAQ

Frequently asked questions about the class library:

Q: I am writing a new class that overrides one of the system classes,
   and I am getting a 1595 warning from the compiler.  Should we use a
   different namespace?

A: There is a quick solution to the problem, you can pass the command
   line argument /nowarn:1595 and this will effectively let you use
   your implementation of the code, while overriding the ones from the
   system assemblies.