X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=README.md;h=facec5b23836396c9fbc11120c5f8eee8fd64b1c;hb=30cddad5fb4c3d290906a6e6c33ecd8b07d8b48c;hp=07c950004d70bc09294b11f4656a3964d4534ca0;hpb=99b5aad5ee74b270b33e3779cf14cf18d847db50;p=mono.git diff --git a/README.md b/README.md index 07c950004d7..facec5b2383 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,220 @@ -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) +The Mono project is part of the [.NET Foundation](http://www.dotnetfoundation.org/) + +[![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) -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 + +| OS | Architecture | Status | +|--------------|--------------------|------------------------------| +| Ubuntu 14.04 | amd64 | [![ubuntu-1404-amd64][1]][2] | +| Ubuntu 14.04 | i386 | [![ubuntu-1404-i386][3]][4] | +| Debian 8 | armel | [![debian-8-armel][5]][6] | +| Debian 8 | armhf | [![debian-8-armhf][7]][8] | +| Debian 8 | arm64 | [![debian-8-arm64][9]][10] | +| OS X | amd64 | [![osx-amd64][11]][12] | +| OS X | i386 | [![osx-i386][13]][14] | +| Windows | amd64 | [![windows-amd64][15]][16] | +| Windows | i386 | [![windows-amd64][17]][18] | +| CentOS | s390x (cs) | [![centos-s390x][19]][20] | +| Debian 8 | ppc64el (cs) | [![debian-8-ppc64el][21]][22]| + +_(cs) = community supported architecture_ + +[1]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-amd64/badge/icon +[2]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-amd64 +[3]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-i386/badge/icon +[4]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-i386/ +[5]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armel/badge/icon +[6]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armel/ +[7]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armhf/badge/icon +[8]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armhf/ +[9]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-arm64/badge/icon +[10]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-arm64/ +[11]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-amd64/badge/icon +[12]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-amd64/ +[13]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-i386/badge/icon +[14]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-i386/ +[15]: https://jenkins.mono-project.com/job/z/label=w64/badge/icon +[16]: https://jenkins.mono-project.com/job/z/label=w64/ +[17]: https://jenkins.mono-project.com/job/z/label=w32/badge/icon +[18]: https://jenkins.mono-project.com/job/z/label=w32/ +[19]: https://jenkins.mono-project.com/job/test-mono-mainline-community/label=centos-s390x/badge/icon +[20]: https://jenkins.mono-project.com/job/test-mono-mainline-community/label=centos-s390x +[21]: https://jenkins.mono-project.com/job/test-mono-mainline-community-chroot/label=debian-8-ppc64el/badge/icon +[22]: https://jenkins.mono-project.com/job/test-mono-mainline-community-chroot/label=debian-8-ppc64el 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. +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 -both a mono binary and a mono-sgen binary. Mono uses Boehm, while -mono-sgen uses the Simple Generational GC. +both a `mono-boehm` binary and a `mono-sgen` binary. `mono-boehm` 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-libgc=[included, 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. - - * *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. + * *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. * *none*: -Disables the inclusion of a garbage collector. +Disables the inclusion of a Boehm 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, @@ -261,30 +295,6 @@ and runtime. * 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,` - Configure where Mono searches for libgdiplus when running System.Drawing tests. @@ -292,7 +302,7 @@ 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. @@ -399,13 +409,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. - * 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. @@ -430,8 +440,10 @@ cycle. 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` @@ -439,7 +451,6 @@ not done much testing with Mono. 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 @@ -450,6 +461,19 @@ disable it. * There are a number of runtime options to control this also, see the man page. +* `--with-csc=roslyn,mcs,default` + + * Use this option to configure which C# compiler to use. By default + the configure script will pick Roslyn, except on platforms where + Roslyn does not work (Big Endian systems) where it will pick mcs. + + If you specify "mcs", then Mono's C# compiler will be used. This + also allows for a complete bootstrap of Mono's core compiler and + core libraries from source. + +   If you specify "roslyn", then Roslyn's C# compiler will be used. + This currently uses Roslyn binaries. + * `--enable-nacl` * This configures the Mono compiler to generate code @@ -459,88 +483,91 @@ http://code.google.com/p/nativeclient/ * 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. +* `--enable-wasm` -Directory Roadmap -================= + * Use this option to configure mono to run on WebAssembly. It will + set both host and target to the WebAssembly triplet. This overrides + the values passed to `--host` or `--target` and ignored what config.sub guesses. -* `docs/` - Technical documents about the Mono runtime. + This is a workaround to enable usage of old automake versions that don't + recognize the wasm triplet. -* `data/` - Configuration files installed as part of the Mono runtime. -* `mono/` - The core of the Mono Runtime. +Working With Submodules +======================= - * `metadata/` - The object system and metadata reader. +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. - * `mini/` - The Just in Time Compiler. +This section describes how to use it. - * `dis/` - CIL executable Disassembler +An initial clone should be done recursively so all submodules will also be +cloned in a single pass: - * `cli/` - Common code for the JIT and the interpreter. + $ git clone --recursive git@github.com:mono/mono - * `io-layer/` - The I/O layer and system abstraction for -emulating the .NET IO model. +Once cloned, submodules can be updated to pull down the latest changes. +This can also be done after an initial non-recursive clone: - * `cil/` - Common Intermediate Representation, XML -definition of the CIL bytecodes. + $ git submodule update --init --recursive - * `interp/` - Interpreter for CLI executables (obsolete). +To pull external changes into a submodule: - * `arch/` - Architecture specific portions. + $ cd + $ git pull origin + $ cd + $ git add + $ git commit -* `man/` - Manual pages for the various Mono commands and programs. +By default, submodules are detached because they point to a specific commit. +Use `git checkout` to move back to a branch before making changes: -* `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. + $ cd + $ git checkout + # work as normal; the submodule is a normal repo + $ git commit/push new changes to the repo (submodule) -* `runtime/` - A directory that contains the Makefiles that link the -mono/ and mcs/ build systems. + $ cd + $ git add # this will record the new commits to the submodule + $ git commit -* `../olive/` +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: - * 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. + $ git submodule sync -- + $ git submodule update --recursive + $ git checkout -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. +The desired output diff is a change in `.gitmodules` to reflect the +change in the remote URL, and a change in / where you see +the desired change in the commit hash. +License +======= -Git submodules maintenance -========================== +See the LICENSE file for licensing information, and the PATENTS.TXT +file for information about Microsoft's patent grant. -Read documentation at http://mono-project.com/Git_Submodule_Maintenance +Mono Trademark Use Policy +========================= -Maintainer -========== +The use of trademarks and logos for Mono can be found [here] (http://www.dotnetfoundation.org/legal/mono-tm). -Mono is maintained by miguel@xamarin.com +Maintaining the Class Library Solution Files +============================================ -Reporting bugs -============== +Mono now ships with a solution file that can be used to build the +assemblies from an IDE. Either by opening the topmost `net_4_x.sln` +file, or to by loading one of the individual `csproj` files located in +each directory. -To submit bug reports, please use Xamarin's Bugzilla: +These are maintained by extracting the configuration information from +our Makefiles, which as of May 2016 remain the canonical location for +configuration information. -https://bugzilla.xamarin.com/ +When changes are made to the Makefiles, a user would need to run the +following command to re-generate the solution files at the top level: -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: + $ make update-solution-files -http://mono-project.com/Bugs#How_to_make_a_good_bug_report