projects / mono.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
[runtime] Avoid returning null from Marshal.AllocCoTaskMem () if size is 0. Fixes...
[mono.git] / README.md
diff --git a/README.md b/README.md
index b061956eee24f682e087c6d01b78bf1fad95dd74..3bbe9b4e176ef2a8d8977ce34b2a95e96880c7e4 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,186 +1,201 @@
-Mono is a software platform designed to allow developers to easily create cross platform applications.
-Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
+Mono is a software platform designed to allow developers to easily
+create cross platform applications.  It is an open source
+implementation of Microsoft's .NET Framework based on the ECMA
+standards for C# and the Common Language Runtime.
 
 
-[![Build Status](http://jenkins.mono-project.com/job/test-mono-mainline/badge/icon/)](http://jenkins.mono-project.com/job/test-mono-mainline/)
-
-1. [Installation](#compilation-and-installation)
+1. [Compilation and Installation](#compilation-and-installation)
 2. [Using Mono](#using-mono)
 3. [Directory Roadmap](#directory-roadmap)
 2. [Using Mono](#using-mono)
 3. [Directory Roadmap](#directory-roadmap)
-4. [Contributing to Mono] (#contributing-to-mono) 
-5. [Git submodules maintenance](#git-submodules-maintenance)
-6. [Reporting bugs](#reporting-bugs)
+4. [Contributing to Mono](#contributing-to-mono)
+5. [Reporting bugs](#reporting-bugs)
+6. [Configuration Options](#configuration-options)
+7. [Working with Submodles](#working-with-submodules)
+
+**Build Status**
+
+Officially supported architectures:
+
+| debian-amd64            | debian-i386            | debian-armel            | debian-armhf            | windows-amd64             |
+|-------------------------|------------------------|-------------------------|-------------------------|---------------------------|
+| [![debian-amd64][1]][2] | [![debian-i386][3]][4] | [![debian-armel][5]][6] | [![debian-armhf][7]][8] | [![windows-amd64][9]][10] |
+
+Community supported architectures:
+
+| debian-ppc64el              | centos-s390x              |
+|-----------------------------|---------------------------|
+| [![debian-ppc64el][11]][12] | [![centos-s390x][13]][14] |
+
+[1]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-amd64/badge/icon
+[2]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-amd64/
+[3]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-i386/badge/icon
+[4]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-i386/
+[5]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-armel/badge/icon
+[6]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-armel/
+[7]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-armhf/badge/icon
+[8]: http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-armhf/
+[9]: https://ci.appveyor.com/api/projects/status/1e61ebdfpbiei58v/branch/master?svg=true
+[10]: https://ci.appveyor.com/project/ajlennon/mono-817/branch/master
+[11]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=debian-ppc64el/badge/icon
+[12]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=debian-ppc64el/
+[13]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=centos-s390x/badge/icon
+[14]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=centos-s390x/
 
 Compilation and Installation
 ============================
 
 
 Compilation and Installation
 ============================
 
-a. Build Requirements
+Building the Software
 ---------------------
 
 ---------------------
 
-* On Itanium, you must obtain libunwind: http://www.hpl.hp.com/research/linux/libunwind/download.php4
-
-* On Solaris
+Please see our guides for building Mono on
+[Mac OS X](http://www.mono-project.com/docs/compiling-mono/mac/),
+[Linux](http://www.mono-project.com/docs/compiling-mono/linux/) and 
+[Windows](http://www.mono-project.com/docs/compiling-mono/windows/).
 
 
- 1. Make sure that you used GNU tar to unpack this package, as
- Solaris tar will not unpack this correctly, and you will get strange errors.
+Note that building from Git assumes that you already have Mono installed,
+so please download and [install the latest Mono release](http://www.mono-project.com/download/)
+before trying to build from Git. This is required because the Mono build
+relies on a working Mono C# compiler to compile itself
+(also known as [bootstrapping](http://en.wikipedia.org/wiki/Bootstrapping_(compilers))).
 
 
- 2. Make sure that you use the GNU toolchain to build the software.
-
- 3. Optional dependencies
+If you don't have a working Mono installation
+---------------------------------------------
 
 
-  * libgdiplus - Required for System.Drawing. This library in turn requires glib and pkg-config
+If you don't have a working Mono installation, you can try a slightly
+more risky approach: getting the latest version of the 'monolite' distribution,
+which contains just enough to run the 'mcs' compiler. You do this with:
 
 
-  * pkg-config - Available at: http://www.freedesktop.org/Software/pkgconfig
+    # Run the following line after ./autogen.sh
+    make get-monolite-latest
 
 
-  * glib 2.4 - Available at: http://www.gtk.org/
+This will download and place the files appropriately so that you can then
+just run:
 
 
-  * libzlib - This library and the development headers are required for compression
-file support in the 2.0 profile.
+    make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/basic.exe
 
 
- 4. Mono is required to build Mono. Use a system package or monolite (explained further below)
- 
- 5. If you have a system Mono (not monolite), you will need to read this: http://mono-project.com/Parallel_Mono_Environments#Setting_up_a_Build_Environment
+The build will then use the files downloaded by `make get-monolite-latest`.
 
 
-b. Building the Software
+Testing and Installation
 ------------------------
 
 ------------------------
 
-If you obtained this package as an officially released tarball,
-this is very simple, use configure and make:
+You can run the mono and mcs test suites with the command: `make check`.
 
 
-`./configure --prefix=/usr/local ; make ; make install`
+Expect to find a few test suite failures. As a sanity check, you
+can compare the failures you got with [https://wrench.mono-project.com/Wrench/](https://wrench.mono-project.com/Wrench/)
+and [http://jenkins.mono-project.com/](http://jenkins.mono-project.com/).
 
 
-Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390,
-S/390x, AMD64, ARM and PowerPC systems.   
+You can now install mono with: `make install`
 
 
-If you obtained this as a snapshot, you will need an existing
-Mono installation.  To upgrade your installation, unpack both
-mono and mcs:
+You can verify your installation by using the mono-test-install
+script, it can diagnose some common problems with Mono's install.
+Failure to follow these steps may result in a broken installation. 
 
 
-       tar xzf mcs-XXXX.tar.gz
-       tar xzf mono-XXXX.tar.gz
-       mv mono-XXX mono
-       mv mcs-XXX mcs
-       cd mono
-       ./autogen.sh --prefix=/usr/local
-       make
+Using Mono
+==========
 
 
-The Mono build system is silent for most compilation commands.
-To enable a more verbose compile (for example, to pinpoint
-problems in your makefiles or your system) pass the V=1 flag to make, like this:
+Once you have installed the software, you can run a few programs:
 
 
-` make V=1`
+* `mono program.exe` runtime engine
 
 
+* `mcs program.cs` C# compiler 
 
 
-c. Building the software from GIT
----------------------------------
+* `monodis program.exe` CIL Disassembler
 
 
-If you are building the software from GIT, make sure that you
-have up-to-date mcs and mono sources:
+See the man pages for mono(1), mcs(1) and monodis(1) for further details.
 
 
- * If you are an anonymous user: `git clone git://github.com/mono/mono.git`
+Directory Roadmap
+=================
 
 
- * If you are a Mono contributor with read/write privileges: `git clone git@github.com:mono/mono.git`
+* `data/` - Configuration files installed as part of the Mono runtime.
+
+* `docs/` - Technical documents about the Mono runtime.
 
 
-Then, go into the mono directory, and configure:
+* `external/` - Git submodules for external libraries (Newtonsoft.Json, ikvm, etc).
 
 
-       cd mono
-       ./autogen.sh --prefix=/usr/local
-       make
+* `man/` - Manual pages for the various Mono commands and programs.
 
 
-For people with non-standard installations of the auto* utils and of
-pkg-config (common on misconfigured OSX and windows boxes), you could get
-an error like this:
+* `mcs/` - The class libraries, compiler and tools
 
 
-       ./configure: line 19176: syntax error near unexpected token 'PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ...
+  * `class/` - The class libraries (like System.*, Microsoft.Build, etc.)
 
 
-This means that you need to set the ACLOCAL_FLAGS environment variable
-when invoking autogen.sh, like this: 
+  * `mcs/` - The Mono C# compiler written in C#
 
 
-        ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/local
+  * `tools/` - Tools like gacutil, ikdasm, mdoc, etc.
 
 
-where $acprefix is the prefix where aclocal has been installed.
-This will automatically go into the mcs/ tree and build the
-binaries there.
+* `mono/` - The core of the Mono Runtime.
 
 
-This assumes that you have a working mono installation, and that
-there's a C# compiler named 'mcs', and a corresponding IL
-runtime called 'mono'.  You can use two make variables
-EXTERNAL_MCS and EXTERNAL_RUNTIME to override these.  e.g., you
-can say:
+  * `arch/` - Architecture specific portions.
 
 
-       make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
+  * `cil/` - Common Intermediate Representation, XML
+definition of the CIL bytecodes.
 
 
-If you don't have a working Mono installation
----------------------------------------------
+  * `dis/` - CIL executable Disassembler
 
 
-If you don't have a working Mono installation, an obvious choice
-is to install the latest released packages of 'mono' for your
-distribution and running `autogen.sh; make; make install` in the
-mono module directory.
+  * `io-layer/` - The I/O layer and system abstraction for 
+emulating the .NET IO model.
 
 
-You can also try a slightly more risky approach: this may not work,
-so start from the released tarball as detailed above.
+  * `metadata/` - The object system and metadata reader.
 
 
-This works by first getting the latest version of the 'monolite'
-distribution, which contains just enough to run the 'mcs'
-compiler. You do this with:
+  * `mini/` - The Just in Time Compiler.
 
 
-       # Run the following line after ./autogen.sh
-       make get-monolite-latest
+* `runtime/` - A directory that contains the Makefiles that link the
+mono/ and mcs/ build systems.
 
 
-This will download and automatically gunzip and untar the
-tarball, and place the files appropriately so that you can then
-just run: `make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/gmcs.exe`
+* `samples/` -Some simple sample programs on uses of the Mono
+runtime as an embedded library.   
 
 
-That will use the files downloaded by 'make get-monolite-latest.
+* `scripts/` - Scripts used to invoke Mono and the corresponding program.
 
 
-Testing and Installation
-------------------------
+* `../olive/` - Incubation code from [Olive](https://github.com/mono/olive).
 
 
-You can run *(part of)* the mono and mcs test suites with the command: `make check`.
-All tests should pass.  
+  * If the directory ../olive is present (as an
+independent checkout) from the Mono module, that
+directory is automatically configured to share the
+same prefix than this module gets.
 
 
-If you want more *extensive* tests, including those that test the
-class libraries, you need to re-run 'configure' with the
-'--enable-nunit-tests' flag, and try: `make -k check`
+Contributing to Mono
+====================
 
 
-Expect to find a few test suite failures. As a sanity check, you
-can compare the failures you got with
+Before submitting changes to Mono, please review the [contribution
+guidelines](http://www.mono-project.com/community/contributing/).
+Please pay particular attention to the [Important
+Rules](http://www.mono-project.com/community/contributing/#important-rules)
+section.
 
 
-    https://wrench.mono-project.com/Wrench/
+Reporting bugs
+==============
 
 
-You can now install mono with: `make install`
+To submit bug reports, please use [Xamarin's
+Bugzilla](https://bugzilla.xamarin.com/)
 
 
-You can verify your installation by using the mono-test-install
-script, it can diagnose some common problems with Mono's install.
-Failure to follow these steps may result in a broken installation. 
+Please use the search facility to ensure the same bug hasn't already
+been submitted and follow our
+[guidelines](http://www.mono-project.com/community/bugs/make-a-good-bug-report/)
+on how to make a good bug report.
 
 
-d. Configuration Options
-------------------------
+Configuration Options
+=====================
 
 
-The following are the configuration options that someone
-building Mono might want to use:
+The following are the configuration options that someone building Mono
+might want to use:
 
 
-* `--with-sgen=yes,no` - Generational GC support: Used to enable or disable the
-compilation of a Mono runtime with the SGen garbage collector.
+* `--with-sgen=yes,no` - Generational GC support: Used to enable or
+disable the compilation of a Mono runtime with the SGen garbage
+collector.
 
   * On platforms that support it, after building Mono, you will have
 
   * On platforms that support it, after building Mono, you will have
-both a mono binary and a mono-sgen binary.  Mono uses Boehm, while
-mono-sgen uses the Simple Generational GC.
+both a `mono` binary and a `mono-sgen` binary. `mono` uses Boehm,
+while `mono-sgen` uses the Simple Generational GC.
 
 
-* `--with-gc=[boehm, included, sgen, none]` - Selects the default Boehm garbage
-collector engine to use.
+* `--with-gc=[included, boehm, none]` - Selects the default Boehm
+garbage collector engine to use.
 
 
-  * *included*: (*slighty modified Boehm GC*)
-This is the default value, and its
-the most feature complete, it will allow Mono
-to use typed allocations and support the
-debugger.
+  * *included*: (*slighty modified Boehm GC*) This is the default
+value for the Boehm GC, and it's the most feature complete, it will
+allow Mono to use typed allocations and support the debugger.
 
 
-  * *boehm*:
-This is used to use a system-install Boehm GC,
-it is useful to test new features available in
-Boehm GC, but we do not recommend that people
-use this, as it disables a few features.
+  * *boehm*: This is used to use a system-install Boehm GC, it is
+useful to test new features available in Boehm GC, but we do not
+recommend that people use this, as it disables a few features.
 
   * *none*:
 Disables the inclusion of a garbage collector.
 
   * *none*:
 Disables the inclusion of a garbage collector.
@@ -267,30 +282,6 @@ and runtime.
 
   * This defaults to `yes`.
 
 
   * This defaults to `yes`.
 
-* `--with-moonlight=yes,no`
-
-  * Whether you want to generate the Silverlight/Moonlight
-libraries and toolchain in addition to the default
-(1.1 and 2.0 APIs).
-
-  * This will produce the `smcs` compiler which will reference
-the Silverlight modified assemblies (mscorlib.dll,
-System.dll, System.Code.dll and System.Xml.Core.dll) and turn
-on the LINQ extensions for the compiler.
-
-* `--with-moon-gc=boehm,sgen` - Select the GC to use for Moonlight.
-
-  * *boehm*:
-Selects the Boehm Garbage Collector, with the same flags
-as the regular Mono build. This is the default.
-
-  * *sgen*:
-Selects the new SGen Garbage Collector, which provides
-Generational GC support, using the same flags as the
-mono-sgen build.
-
-  * This defaults to `boehm`.
-
 * `--with-libgdiplus=installed,sibling,<path>` - Configure where Mono
 searches for libgdiplus when running System.Drawing tests.
 
 * `--with-libgdiplus=installed,sibling,<path>` - Configure where Mono
 searches for libgdiplus when running System.Drawing tests.
 
@@ -298,7 +289,7 @@ searches for libgdiplus when running System.Drawing tests.
 library is available to Mono through the regular
 system setup.
 
 library is available to Mono through the regular
 system setup.
 
-  * `sibling' can be used to specify that a libgdiplus
+  * `sibling` can be used to specify that a libgdiplus
 that resides as a sibling of this directory (mono)
 should be used.
 
 that resides as a sibling of this directory (mono)
 should be used.
 
@@ -405,13 +396,13 @@ for Mono.  The LLVM code generator and optimizer will be
 used instead of Mono's built-in code generator for both
 Just in Time and Ahead of Time compilations.
 
 used instead of Mono's built-in code generator for both
 Just in Time and Ahead of Time compilations.
 
-  * See the http://www.mono-project.com/Mono_LLVM for the 
+  * See http://www.mono-project.com/docs/advanced/mono-llvm/ for the 
 full details and up-to-date information on this feature.
 
   * You will need to have an LLVM built that Mono can link
 against.
 
 full details and up-to-date information on this feature.
 
   * You will need to have an LLVM built that Mono can link
 against.
 
-  * The --enable-loadedllvm variant will make the LLVM backend
+  * The `--enable-loadedllvm` variant will make the LLVM backend
 into a runtime-loadable module instead of linking it directly
 into the main mono binary.
 
 into a runtime-loadable module instead of linking it directly
 into the main mono binary.
 
@@ -445,7 +436,6 @@ not done much testing with Mono.
 runtime that contains DTrace probes and can
 participate in the system profiling using DTrace.
 
 runtime that contains DTrace probes and can
 participate in the system profiling using DTrace.
 
-
 * `--disable-dev-random`
 
   * Mono uses /dev/random to obtain good random data for
 * `--disable-dev-random`
 
   * Mono uses /dev/random to obtain good random data for
@@ -465,84 +455,52 @@ http://code.google.com/p/nativeclient/
   * Currently this is used with Mono's AOT engine as
 Native Client does not support JIT engines yet.
 
   * Currently this is used with Mono's AOT engine as
 Native Client does not support JIT engines yet.
 
-Using Mono
-==========
+Working With Submodules
+=======================
 
 
-Once you have installed the software, you can run a few programs:
+Mono references several external git submodules, for example
+a fork of Microsoft's reference source code that has been altered
+to be suitable for use with the Mono runtime.
 
 
-* `mono program.exe` runtime engine
+This section describes how to use it.
 
 
-* `mcs program.cs` C# compiler 
+An initial clone should be done recursively so all submodules will also be
+cloned in a single pass:
 
 
-* `monodis program.exe` CIL Disassembler
+        $ git clone --recursive git@github.com:mono/mono
 
 
-See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
-for further details.
+Once cloned, submodules can be updated to pull down the latest changes.
+This can also be done after an initial non-recursive clone:
 
 
-Directory Roadmap
-=================
+        $ git submodule update --init --recursive
 
 
-* `docs/` - Technical documents about the Mono runtime.
+To pull external changes into a submodule:
 
 
-* `data/` - Configuration files installed as part of the Mono runtime.
+        $ cd <submodule>
+        $ git pull origin <branch>
+        $ cd <top-level>
+        $ git add <submodule>
+        $ git commit
 
 
-* `mono/` - The core of the Mono Runtime.
-
-  * `metadata/` - The object system and metadata reader.
-
-  * `mini/` - The Just in Time Compiler.
-
-  * `dis/` - CIL executable Disassembler
+By default, submodules are detached because they point to a specific commit.
+Use `git checkout` to move back to a branch before making changes:
 
 
-  * `io-layer/` - The I/O layer and system abstraction for 
-emulating the .NET IO model.
+        $ cd <submodule>
+        $ git checkout <branch>
+        # work as normal; the submodule is a normal repo
+        $ git commit/push new changes to the repo (submodule)
 
 
-  * `cil/` - Common Intermediate Representation, XML
-definition of the CIL bytecodes.
+        $ cd <top-level>
+        $ git add <submodule> # this will record the new commits to xamcore
+        $ git commit
 
 
- * `arch/` - Architecture specific portions.
+To switch the repo of a submodule (this should not be a common or normal thing
+to do at all), first edit `.gitmodules` to point to the new location, then:
 
 
-* `man/` - Manual pages for the various Mono commands and programs.
-
-* `samples/` -Some simple sample programs on uses of the Mono
-runtime as an embedded library.   
-
-* `scripts/` - Scripts used to invoke Mono and the corresponding program.
-
-* `runtime/` - A directory that contains the Makefiles that link the
-mono/ and mcs/ build systems.
-
-* `../olive/`
-
-  * If the directory ../olive is present (as an
-independent checkout) from the Mono module, that
-directory is automatically configured to share the
-same prefix than this module gets.
-
-Contributing to Mono
-====================
-Before submitting changes to Mono, please review the contribution guidelines at http://mono-project.com/Contributing. Please pay particular attention to the [Important Rules](http://mono-project.com/Contributing#Important_Rules) section.
-
-
-Git submodules maintenance
-==========================
-
-Read documentation at http://mono-project.com/Git_Submodule_Maintenance
-
-Maintainer
-==========
-
-Mono is maintained by miguel@xamarin.com
-
-Reporting bugs
-==============
-
-To submit bug reports, please use Xamarin's Bugzilla:
-
-https://bugzilla.xamarin.com/
-
-Please use the search facility to ensure the same bug hasn't already
-been submitted and follow our guidelines on how to make a good bug
-report:
+        $ git submodule sync -- <path of the submodule>
+        $ git submodule update --recursive
+        $ git checkout <desired new hash or branch>
 
 
-http://mono-project.com/Bugs#How_to_make_a_good_bug_report
+The desired output diff is a change in `.gitmodules` to reflect the
+change in the remote URL, and a change in /<submodule> where you see
+the desired change in the commit hash.
my mono mirror. check out Moved to http://github.com/mono/mono