-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.
-[](http://monojenkins.cloudapp.net/job/Mono/)
+[](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)
-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]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=nealef-s390x-1/badge/icon
+[12]: http://jenkins.mono-project.com/job/test-mono-mainline-communityarchitectures/label=nealef-s390x-1/
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://wrench.mono-project.com/Wrench/](https://wrench.mono-project.com/Wrench/)
+and [http://jenkins.mono-project.com/](http://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
-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.
* 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.
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.
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.
- * 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.
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
* 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.
projects / mono.git / blobdiff