projects / mono.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
[mcs] Accept and ignore command line args supported by csc ..
[mono.git] / README.md
diff --git a/README.md b/README.md
index b061956eee24f682e087c6d01b78bf1fad95dd74..96559ab5c34307f3b10e964dfd4ce67b465ae4cc 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,186 +1,193 @@
-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/)
+[![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. [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 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
+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/).
 
 
-* On Solaris
+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))).
 
 
- 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.
-
- 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
 
 
- 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:
-
-`./configure --prefix=/usr/local ; make ; make install`
+You can run the mono and mcs test suites with the command: `make check`.
 
 
-Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390,
-S/390x, AMD64, ARM and PowerPC systems.   
+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/).
 
 
-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 now install mono with: `make install`
 
 
-       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
+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. 
 
 
-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:
+Using Mono
+==========
 
 
-` make V=1`
+Once you have installed the software, you can run a few programs:
 
 
+* `mono program.exe` runtime engine
 
 
-c. Building the software from GIT
----------------------------------
+* `mcs program.cs` C# compiler 
 
 
-If you are building the software from GIT, make sure that you
-have up-to-date mcs and mono sources:
+* `monodis program.exe` CIL Disassembler
 
 
- * If you are an anonymous user: `git clone git://github.com/mono/mono.git`
+See the man pages for mono(1), mcs(1) and monodis(1) for further details.
 
 
- * If you are a Mono contributor with read/write privileges: `git clone git@github.com:mono/mono.git`
+Directory Roadmap
+=================
 
 
-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*: (*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 +274,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 +281,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 +388,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 +428,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 +447,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.
+By default, submodules are detached because they point to a specific commit.
+Use `git checkout` to move back to a branch before making changes:
 
 
-  * `metadata/` - The object system and metadata reader.
+       $ cd <submodule>
+       $ git checkout <branch>
+       # work as normal; the submodule is a normal repo
+       $ git commit/push new changes to the repo (submodule)
 
 
-  * `mini/` - The Just in Time Compiler.
+       $ cd <top-level>
+       $ git add <submodule> # this will record the new commits to the submodule
+       $ git commit
 
 
-  * `dis/` - CIL executable Disassembler
+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:
 
 
-  * `io-layer/` - The I/O layer and system abstraction for 
-emulating the .NET IO model.
-
-  * `cil/` - Common Intermediate Representation, XML
-definition of the CIL bytecodes.
-
- * `arch/` - Architecture specific portions.
-
-* `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