X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=README.md;h=e7ed2c4f704790abd401315f7dd1b001e7dd5e11;hb=f03a1b538bfb0d9be810688e8713731e122320b5;hp=d600ce4ad172f638313959ad71f1251861e78f61;hpb=11a3daa71d8524cf6ec1f88c646b590dc444ee3e;p=mono.git diff --git a/README.md b/README.md index d600ce4ad17..e7ed2c4f704 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,194 @@ -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://monojenkins.cloudapp.net/job/Mono/badge/icon)](http://monojenkins.cloudapp.net/job/Mono/) +[![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) -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. @@ -267,30 +275,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. @@ -298,7 +282,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. @@ -405,13 +389,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. @@ -445,7 +429,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 @@ -465,88 +448,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. -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 + $ git pull origin + $ cd + $ git add + $ 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 + $ git checkout + # work as normal; the submodule is a normal repo + $ git commit/push new changes to the repo (submodule) -* `../olive/` + $ cd + $ git add # 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 -- + $ git submodule update --recursive + $ git checkout -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 / where you see +the desired change in the commit hash.