Merge pull request #1718 from madewokherd/sgenthreadcleanup

[mono.git] / README.md

diff --git a/README.md b/README.md
index 07c950004d70bc09294b11f4656a3964d4534ca0..d3ff65bda20411879d323a6aa9e14d4c38efbcfa 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,186 +1,208 @@
-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.

 
 

-1. [Installation](#compilation-and-installation)
+[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/mono/mono?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+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 Submodules](#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:
+
+| centos-s390x              |
+|---------------------------|
+| [![centos-s390x][11]][12] |
+
+[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]: https://jenkins.mono-project.com/job/z/label=centos-s390x/badge/icon
+[12]: https://jenkins.mono-project.com/job/z/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.
+If you don't have a working Mono installation
+---------------------------------------------

 
 

- 3. Optional dependencies
+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:

 
 

-  * libgdiplus - Required for System.Drawing. This library in turn requires glib and pkg-config
+    # Run the following line after ./autogen.sh
+    make get-monolite-latest

 
 

-  * pkg-config - Available at: http://www.freedesktop.org/Software/pkgconfig
+This will download and place the files appropriately so that you can then
+just run:

 
 

-  * glib 2.4 - Available at: http://www.gtk.org/
+    make

 
 

-  * libzlib - This library and the development headers are required for compression
-file support in the 2.0 profile.
+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://jenkins.mono-project.com/](https://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`
+* `acceptance-tests/` - Optional third party test suites used to validate Mono against a wider range of test cases.

 
 

-Then, go into the mono directory, and configure:
+* `data/` - Configuration files installed as part of the Mono runtime.

 
 

-       cd mono
-       ./autogen.sh --prefix=/usr/local
-       make
+* `docs/` - Technical documents about the Mono runtime.

 
 

-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:
+* `external/` - Git submodules for external libraries (Newtonsoft.Json, ikvm, etc).

 
 

-       ./configure: line 19176: syntax error near unexpected token 'PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ...
+* `man/` - Manual pages for the various Mono commands and programs.

 
 

-This means that you need to set the ACLOCAL_FLAGS environment variable
-when invoking autogen.sh, like this: 
+* `mcs/` - The class libraries, compiler and tools

 
 

-        ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/local
+  * `class/` - The class libraries (like System.*, Microsoft.Build, etc.)

 
 

-where $acprefix is the prefix where aclocal has been installed.
-This will automatically go into the mcs/ tree and build the
-binaries there.
+  * `mcs/` - The Mono C# compiler written in C#

 
 

-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:
+  * `tools/` - Tools like gacutil, ikdasm, mdoc, etc.

 
 

-       make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
+* `mono/` - The core of the Mono Runtime.

 
 

-If you don't have a working Mono installation
----------------------------------------------
+  * `arch/` - Architecture specific portions.

 
 

-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.
+  * `cil/` - Common Intermediate Representation, XML
+definition of the CIL bytecodes.

 
 

-You can also try a slightly more risky approach: this may not work,
-so start from the released tarball as detailed above.
+  * `dis/` - CIL executable Disassembler

 
 

-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:
+  * `io-layer/` - The I/O layer and system abstraction for 
+emulating the .NET IO model.

 
 

-       # Run the following line after ./autogen.sh
-       make get-monolite-latest
+  * `metadata/` - The object system and metadata reader.

 
 

-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`
+  * `mini/` - The Just in Time Compiler.

 
 

-That will use the files downloaded by 'make get-monolite-latest.
+* `runtime/` - A directory that contains the Makefiles that link the
+mono/ and mcs/ build systems.

 
 

-Testing and Installation
-------------------------
+* `samples/` -Some simple sample programs on uses of the Mono
+runtime as an embedded library.   

 
 

-You can run *(part of)* the mono and mcs test suites with the command: `make check`.
-All tests should pass.  
+* `scripts/` - Scripts used to invoke Mono and the corresponding program.

 
 

-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*: (*slightly 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.
 
   * This defaults to `included`.
 
 
   * *none*:
 Disables the inclusion of a garbage collector.
 
   * This defaults to `included`.
 

+* `--with-cooperative-gc`
+
+  * If you pass this flag the Mono runtime is configured to only use
+  the cooperative mode of the garbage collector.  If you do not pass
+  this flag, then you can control at runtime the use of the
+  cooperative GC mode by setting the `MONO_ENABLE_COOP` flag.
+  

 * `--with-tls=__thread,pthread`
 
   * Controls how Mono should access thread local storage,
 * `--with-tls=__thread,pthread`
 
   * Controls how Mono should access thread local storage,


@@ -261,30 +283,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.
 


@@ -292,7 +290,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.
 


@@ -399,13 +397,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.
 


@@ -430,8 +428,10 @@ cycle.
 multiple CPUs to do its work.  This helps performance
 on multi-CPU machines as the work is divided across CPUS.
 
 multiple CPUs to do its work.  This helps performance
 on multi-CPU machines as the work is divided across CPUS.
 

-  * This option is not currently the default as we have
-not done much testing with Mono.
+  * This option is not currently the default on OSX
+as it runs into issues there.
+
+  * This option only applies to the Boehm GC.

 
 * `--enable-dtrace`
 
 
 * `--enable-dtrace`
 


@@ -439,7 +439,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


@@ -459,88 +458,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
-==========
-
-Once you have installed the software, you can run a few programs:
-
-* `mono program.exe` runtime engine
-
-* `mcs program.cs` C# compiler 
-
-* `monodis program.exe` CIL Disassembler
-
-See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
-for further details.
-
-Directory Roadmap
-=================
-
-* `docs/` - Technical documents about the Mono runtime.
-
-* `data/` - Configuration files installed as part of the Mono runtime.
-
-* `mono/` - The core of the Mono Runtime.
-
-  * `metadata/` - The object system and metadata reader.
-
-  * `mini/` - The Just in Time Compiler.
+Working With Submodules
+=======================

 
 

-  * `dis/` - CIL executable Disassembler
+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.

 
 

-  * `cli/` - Common code for the JIT and the interpreter.
+This section describes how to use it.

 
 

-  * `io-layer/` - The I/O layer and system abstraction for 
-emulating the .NET IO model.
+An initial clone should be done recursively so all submodules will also be
+cloned in a single pass:

 
 

-  * `cil/` - Common Intermediate Representation, XML
-definition of the CIL bytecodes.
+       $ git clone --recursive git@github.com:mono/mono

 
 

- * `interp/` - Interpreter for CLI executables (obsolete).
+Once cloned, submodules can be updated to pull down the latest changes.
+This can also be done after an initial non-recursive clone:

 
 

- * `arch/` - Architecture specific portions.
+       $ git submodule update --init --recursive

 
 

-* `man/` - Manual pages for the various Mono commands and programs.
+To pull external changes into a submodule:

 
 

-* `samples/` -Some simple sample programs on uses of the Mono
-runtime as an embedded library.   
+       $ cd <submodule>
+       $ git pull origin <branch>
+       $ cd <top-level>
+       $ git add <submodule>
+       $ git commit

 
 

-* `scripts/` - Scripts used to invoke Mono and the corresponding program.
+By default, submodules are detached because they point to a specific commit.
+Use `git checkout` to move back to a branch before making changes:

 
 

-* `runtime/` - A directory that contains the Makefiles that link the
-mono/ and mcs/ build systems.
+       $ cd <submodule>
+       $ git checkout <branch>
+       # work as normal; the submodule is a normal repo
+       $ git commit/push new changes to the repo (submodule)

 
 

-* `../olive/`
+       $ cd <top-level>
+       $ git add <submodule> # this will record the new commits to the submodule
+       $ git commit

 
 

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

 
 

-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.