Updated

[mono.git] / web / class-library

diff --git a/web/class-library b/web/class-library
index 53d264c2aea7e5c59fbc9037131c334e167d0267..2819ff8ba4321b6b76e4db0af7caf7a86aeae5da 100644 (file)
--- a/web/class-library
+++ b/web/class-library
@@ -1,52 +1,93 @@
 * The Class Library
 
        The Class Library should be compatible with Microsoft's .NET
 * The Class Library
 
        The Class Library should be compatible with Microsoft's .NET

-       implementation.  
+       implementation.

 
 

-       Ideally as much code as possible should be written using C#.
-       In some cases we might either need to interface with code
-       written in C for large chunks of functionality (libart and
-       Gtk+ for example) or we would need to interface to the system
-       libraries (libc on Unix for networking functions for
-       example).  
+       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:mono-list@ximian.com">mono-list@ximian.com</a>
+       with the class you want to implement and CC <a
+       href="mailto:miguel@ximian.com">miguel@ximian.com</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
 
 ** Using existing components from GNOME.
 
        Our current plan is to implement the GUI tools on top of

-       Gtk+.  The only problem is that applications from Windows
+       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
        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 (the HDC and HWND properties in the GDI+).
-       It seems from casual inspection that these can be safely
-       mapped to Gdk's GC and GdkWindow pointers without breaking anything.
+       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
 
        The only drawback is that support for PInvoke of Win32 code

-       wont be available.  If this is necessary it could be possible
-       in the future by reusing pieces of Wine, and probably using
-       Wine as our toolkit, but we think that this is not as
-       important as we will wrap GNOME elements in the meantime. 
+       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
 
 *** Initial GDI+ and WinForms implementation
 
        The initial implementation will use Gtk+ as the underlying

-       toolkit, but implementations for other windowing systems
-       should be possible (particularly thinking about PDA devices
-       here).
-
-       Since Gtk+ 2.0 has been ported to other windowing systems
-       other than X (frame buffer, Win32 and BeOS implementation
-       exist) it should cover most uses for most users.
-
+       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
 
 *** Database access
 

-       Implementing the ADO.NET functionality can be done through
-       reusing <a href="http://www.gnome-db.org">GNOME-DB</a> as
-       GNOME-DB was implemented precisely to provide an ADO-like
-       system for GNOME.
+       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
 
 
 *** Component Integration
 


@@ -57,7 +98,28 @@
 ** Licensing
 
        The class library will be licensed under the terms of the GNU
 ** Licensing
 
        The class library will be licensed under the terms of the GNU

-       LGPL.
+       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
 
        We suggest that you assign the copyright of your work to the
        GNOME Foundation or the Free Software Foundation to simplify


@@ -65,15 +127,57 @@
 
 ** Class Library testing
 
 
 ** Class Library testing
 

-       We need to write regression tests that would excercise the
-       class library to verify that the class library is correct,
-       that our compiler is correct and that our JIT engine is
-       correct. 
+       We need to write regression tests that will verify
+       the correctness of the class library, compiler, and JIT
+       engine.

 
 

-** Contributing
+       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:

 
 

-       We welcome contributions to the the Class Library, you can
-       check the status page.  Our status page describes which APIs
-       are being worked on and the contact information for the
-       contributor.
+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.
\ No newline at end of file