README.md

   1 Mono is a software platform designed to allow developers to easily
   2 create cross platform applications.  It is an open source
   3 implementation of Microsoft's .NET Framework based on the ECMA
   4 standards for C# and the Common Language Runtime.
   5
   6 The Mono project is part of the [.NET Foundation](http://www.dotnetfoundation.org/)
   7
   8 [![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)
   9
  10 1. [Compilation and Installation](#compilation-and-installation)
  11 2. [Using Mono](#using-mono)
  12 3. [Directory Roadmap](#directory-roadmap)
  13 4. [Contributing to Mono](#contributing-to-mono)
  14 5. [Reporting bugs](#reporting-bugs)
  15 6. [Configuration Options](#configuration-options)
  16 7. [Working with Submodules](#working-with-submodules)
  17
  18 ### Build Status
  19
  20 | OS           | Architecture       | Status                       |
  21 |--------------|--------------------|------------------------------|
  22 | Ubuntu 14.04 | amd64              | [![ubuntu-1404-amd64][1]][2] |
  23 | Ubuntu 14.04 | i386               | [![ubuntu-1404-i386][3]][4]  |
  24 | Debian 8     | armel              | [![debian-8-armel][5]][6]    |
  25 | Debian 8     | armhf              | [![debian-8-armhf][7]][8]    |
  26 | Debian 8     | arm64              | [![debian-8-arm64][9]][10]   |
  27 | OS X         | amd64              | [![osx-amd64][11]][12]       |
  28 | OS X         | i386               | [![osx-i386][13]][14]        |
  29 | Windows      | amd64              | [![windows-amd64][15]][16]   |
  30 | Windows      | i386               | [![windows-amd64][17]][18]   |
  31 | CentOS       | s390x (cs)         | [![centos-s390x][19]][20]    |
  32
  33 _(cs) = community supported architecture_
  34
  35 [1]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-amd64/badge/icon
  36 [2]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-amd64
  37 [3]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-i386/badge/icon
  38 [4]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=ubuntu-1404-i386/
  39 [5]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armel/badge/icon
  40 [6]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armel/
  41 [7]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armhf/badge/icon
  42 [8]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-armhf/
  43 [9]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-arm64/badge/icon
  44 [10]: https://jenkins.mono-project.com/job/test-mono-mainline-linux/label=debian-8-arm64/
  45 [11]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-amd64/badge/icon
  46 [12]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-amd64/
  47 [13]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-i386/badge/icon
  48 [14]: https://jenkins.mono-project.com/job/test-mono-mainline/label=osx-i386/
  49 [15]: https://jenkins.mono-project.com/job/z/label=w64/badge/icon
  50 [16]: https://jenkins.mono-project.com/job/z/label=w64/
  51 [17]: https://jenkins.mono-project.com/job/z/label=w32/badge/icon
  52 [18]: https://jenkins.mono-project.com/job/z/label=w32/
  53 [19]: https://jenkins.mono-project.com/job/z/label=centos-s390x/badge/icon
  54 [20]: https://jenkins.mono-project.com/job/z/label=centos-s390x
  55
  56 Compilation and Installation
  57 ============================
  58
  59 Building the Software
  60 ---------------------
  61
  62 Please see our guides for building Mono on
  63 [Mac OS X](http://www.mono-project.com/docs/compiling-mono/mac/),
  64 [Linux](http://www.mono-project.com/docs/compiling-mono/linux/) and
  65 [Windows](http://www.mono-project.com/docs/compiling-mono/windows/).
  66
  67 Note that building from Git assumes that you already have Mono installed,
  68 so please download and [install the latest Mono release](http://www.mono-project.com/download/)
  69 before trying to build from Git. This is required because the Mono build
  70 relies on a working Mono C# compiler to compile itself
  71 (also known as [bootstrapping](http://en.wikipedia.org/wiki/Bootstrapping_(compilers))).
  72
  73 If you don't have a working Mono installation
  74 ---------------------------------------------
  75
  76 If you don't have a working Mono installation, you can try a slightly
  77 more risky approach: getting the latest version of the 'monolite' distribution,
  78 which contains just enough to run the 'mcs' compiler. You do this with:
  79
  80     # Run the following line after ./autogen.sh
  81     make get-monolite-latest
  82
  83 This will download and place the files appropriately so that you can then
  84 just run:
  85
  86     make
  87
  88 The build will then use the files downloaded by `make get-monolite-latest`.
  89
  90 Testing and Installation
  91 ------------------------
  92
  93 You can run the mono and mcs test suites with the command: `make check`.
  94
  95 Expect to find a few test suite failures. As a sanity check, you
  96 can compare the failures you got with [https://jenkins.mono-project.com/](https://jenkins.mono-project.com/).
  97
  98 You can now install mono with: `make install`
  99
 100 You can verify your installation by using the mono-test-install
 101 script, it can diagnose some common problems with Mono's install.
 102 Failure to follow these steps may result in a broken installation.
 103
 104 Using Mono
 105 ==========
 106
 107 Once you have installed the software, you can run a few programs:
 108
 109 * `mono program.exe` runtime engine
 110
 111 * `mcs program.cs` C# compiler
 112
 113 * `monodis program.exe` CIL Disassembler
 114
 115 See the man pages for mono(1), mcs(1) and monodis(1) for further details.
 116
 117 Directory Roadmap
 118 =================
 119
 120 * `acceptance-tests/` - Optional third party test suites used to validate Mono against a wider range of test cases.
 121
 122 * `data/` - Configuration files installed as part of the Mono runtime.
 123
 124 * `docs/` - Technical documents about the Mono runtime.
 125
 126 * `external/` - Git submodules for external libraries (Newtonsoft.Json, ikvm, etc).
 127
 128 * `man/` - Manual pages for the various Mono commands and programs.
 129
 130 * `mcs/` - The class libraries, compiler and tools
 131
 132   * `class/` - The class libraries (like System.*, Microsoft.Build, etc.)
 133
 134   * `mcs/` - The Mono C# compiler written in C#
 135
 136   * `tools/` - Tools like gacutil, ikdasm, mdoc, etc.
 137
 138 * `mono/` - The core of the Mono Runtime.
 139
 140   * `arch/` - Architecture specific portions.
 141
 142   * `cil/` - Common Intermediate Representation, XML
 143 definition of the CIL bytecodes.
 144
 145   * `dis/` - CIL executable Disassembler
 146
 147   * `io-layer/` - The I/O layer and system abstraction for
 148 emulating the .NET IO model.
 149
 150   * `metadata/` - The object system and metadata reader.
 151
 152   * `mini/` - The Just in Time Compiler.
 153
 154 * `runtime/` - A directory that contains the Makefiles that link the
 155 mono/ and mcs/ build systems.
 156
 157 * `samples/` -Some simple sample programs on uses of the Mono
 158 runtime as an embedded library.
 159
 160 * `scripts/` - Scripts used to invoke Mono and the corresponding program.
 161
 162 Contributing to Mono
 163 ====================
 164
 165 Before submitting changes to Mono, please review the [contribution
 166 guidelines](http://www.mono-project.com/community/contributing/).
 167 Please pay particular attention to the [Important
 168 Rules](http://www.mono-project.com/community/contributing/#important-rules)
 169 section.
 170
 171 Reporting bugs
 172 ==============
 173
 174 To submit bug reports, please use [Xamarin's
 175 Bugzilla](https://bugzilla.xamarin.com/)
 176
 177 Please use the search facility to ensure the same bug hasn't already
 178 been submitted and follow our
 179 [guidelines](http://www.mono-project.com/community/bugs/make-a-good-bug-report/)
 180 on how to make a good bug report.
 181
 182 Configuration Options
 183 =====================
 184
 185 The following are the configuration options that someone building Mono
 186 might want to use:
 187
 188 * `--with-sgen=yes,no` - Generational GC support: Used to enable or
 189 disable the compilation of a Mono runtime with the SGen garbage
 190 collector.
 191
 192   * On platforms that support it, after building Mono, you will have
 193 both a `mono` binary and a `mono-sgen` binary. `mono` uses Boehm,
 194 while `mono-sgen` uses the Simple Generational GC.
 195
 196 * `--with-gc=[included, boehm, none]` - Selects the default Boehm
 197 garbage collector engine to use.
 198
 199   * *included*: (*slightly modified Boehm GC*) This is the default
 200 value for the Boehm GC, and it's the most feature complete, it will
 201 allow Mono to use typed allocations and support the debugger.
 202
 203   * *boehm*: This is used to use a system-install Boehm GC, it is
 204 useful to test new features available in Boehm GC, but we do not
 205 recommend that people use this, as it disables a few features.
 206
 207   * *none*:
 208 Disables the inclusion of a garbage collector.
 209
 210   * This defaults to `included`.
 211
 212 * `--with-cooperative-gc`
 213
 214   * If you pass this flag the Mono runtime is configured to only use
 215   the cooperative mode of the garbage collector.  If you do not pass
 216   this flag, then you can control at runtime the use of the
 217   cooperative GC mode by setting the `MONO_ENABLE_COOP` flag.
 218
 219 * `--with-tls=__thread,pthread`
 220
 221   * Controls how Mono should access thread local storage,
 222 pthread forces Mono to use the pthread APIs, while
 223 __thread uses compiler-optimized access to it.
 224
 225   * Although __thread is faster, it requires support from
 226 the compiler, kernel and libc. Old Linux systems do
 227 not support with __thread.
 228
 229   * This value is typically pre-configured and there is no
 230 need to set it, unless you are trying to debug a problem.
 231
 232 * `--with-sigaltstack=yes,no`
 233
 234   * **Experimental**: Use at your own risk, it is known to
 235 cause problems with garbage collection and is hard to
 236 reproduce those bugs.
 237
 238   * This controls whether Mono will install a special
 239 signal handler to handle stack overflows. If set to
 240 `yes`, it will turn stack overflows into the
 241 StackOverflowException. Otherwise when a stack
 242 overflow happens, your program will receive a
 243 segmentation fault.
 244
 245   * The configure script will try to detect if your
 246 operating system supports this. Some older Linux
 247 systems do not support this feature, or you might want
 248 to override the auto-detection.
 249
 250 * `--with-static_mono=yes,no`
 251
 252   * This controls whether `mono` should link against a
 253 static library (libmono.a) or a shared library
 254 (libmono.so).
 255
 256   * This defaults to `yes`, and will improve the performance
 257 of the `mono` program.
 258
 259   * This only affects the `mono' binary, the shared
 260 library libmono.so will always be produced for
 261 developers that want to embed the runtime in their
 262 application.
 263
 264 * `--with-xen-opt=yes,no` - Optimize code for Xen virtualization.
 265
 266   * It makes Mono generate code which might be slightly
 267 slower on average systems, but the resulting executable will run
 268 faster under the Xen virtualization system.
 269
 270   * This defaults to `yes`.
 271
 272 * `--with-large-heap=yes,no` - Enable support for GC heaps larger than 3GB.
 273
 274   * This defaults to `no`.
 275
 276 * `--enable-small-config=yes,no` - Enable some tweaks to reduce memory usage
 277 and disk footprint at the expense of some capabilities.
 278
 279   * Typically this means that the number of threads that can be created
 280 is limited (256), that the maximum heap size is also reduced (256 MB)
 281 and other such limitations that still make mono useful, but more suitable
 282 to embedded devices (like mobile phones).
 283
 284   * This defaults to `no`.
 285
 286 * `--with-ikvm-native=yes,no` - Controls whether the IKVM JNI interface library is
 287 built or not.
 288
 289   * This is used if you are planning on
 290 using the IKVM Java Virtual machine with Mono.
 291
 292   * This defaults to `yes`.
 293
 294 * `--with-profile4=yes,no` - Whether you want to build the 4.x profile libraries
 295 and runtime.
 296
 297   * This defaults to `yes`.
 298
 299 * `--with-libgdiplus=installed,sibling,<path>` - Configure where Mono
 300 searches for libgdiplus when running System.Drawing tests.
 301
 302   * It defaults to `installed`, which means that the
 303 library is available to Mono through the regular
 304 system setup.
 305
 306   * `sibling` can be used to specify that a libgdiplus
 307 that resides as a sibling of this directory (mono)
 308 should be used.
 309
 310  * Or you can specify a path to a libgdiplus.
 311
 312 * `--disable-shared-memory`
 313
 314   * Use this option to disable the use of shared memory in
 315 Mono (this is equivalent to setting the MONO_DISABLE_SHM
 316 environment variable, although this removes the feature
 317 completely).
 318
 319   * Disabling the shared memory support will disable certain
 320 features like cross-process named mutexes.
 321
 322 * `--enable-minimal=LIST`
 323
 324   * Use this feature to specify optional runtime
 325 components that you might not want to include.  This
 326 is only useful for developers embedding Mono that
 327 require a subset of Mono functionality.
 328   * The list is a comma-separated list of components that
 329 should be removed, these are:
 330
 331     * `aot`:
 332 Disables support for the Ahead of Time compilation.
 333
 334     * `attach`:
 335 Support for the Mono.Management assembly and the
 336 VMAttach API (allowing code to be injected into
 337 a target VM)
 338
 339     * `com`:
 340 Disables COM support.
 341
 342     * `debug`:
 343 Drop debugging support.
 344
 345     * `decimal`:
 346 Disables support for System.Decimal.
 347
 348     * `full_messages`:
 349 By default Mono comes with a full table
 350 of messages for error codes. This feature
 351 turns off uncommon error messages and reduces
 352 the runtime size.
 353
 354     * `generics`:
 355 Generics support.  Disabling this will not
 356 allow Mono to run any 2.0 libraries or
 357 code that contains generics.
 358
 359     * `jit`:
 360 Removes the JIT engine from the build, this reduces
 361 the executable size, and requires that all code
 362 executed by the virtual machine be compiled with
 363 Full AOT before execution.
 364
 365     * `large_code`:
 366 Disables support for large assemblies.
 367
 368     * `logging`:
 369 Disables support for debug logging.
 370
 371     * `pinvoke`:
 372 Support for Platform Invocation services,
 373 disabling this will drop support for any
 374 libraries using DllImport.
 375
 376     * `portability`:
 377 Removes support for MONO_IOMAP, the environment
 378 variables for simplifying porting applications that
 379 are case-insensitive and that mix the Unix and Windows path separators.
 380
 381     * `profiler`:
 382 Disables support for the default profiler.
 383
 384     * `reflection_emit`:
 385 Drop System.Reflection.Emit support
 386
 387     * `reflection_emit_save`:
 388 Drop support for saving dynamically created
 389 assemblies (AssemblyBuilderAccess.Save) in
 390 System.Reflection.Emit.
 391
 392     * `shadow_copy`:
 393 Disables support for AppDomain's shadow copies
 394 (you can disable this if you do not plan on
 395 using appdomains).
 396
 397     * `simd`:
 398 Disables support for the Mono.SIMD intrinsics
 399 library.
 400
 401     * `ssa`:
 402 Disables compilation for the SSA optimization
 403 framework, and the various SSA-based optimizations.
 404
 405 * `--enable-llvm`
 406 * `--enable-loadedllvm`
 407
 408   * This enables the use of LLVM as a code generation engine
 409 for Mono.  The LLVM code generator and optimizer will be
 410 used instead of Mono's built-in code generator for both
 411 Just in Time and Ahead of Time compilations.
 412
 413   * See http://www.mono-project.com/docs/advanced/mono-llvm/ for the
 414 full details and up-to-date information on this feature.
 415
 416   * You will need to have an LLVM built that Mono can link
 417 against.
 418
 419   * The `--enable-loadedllvm` variant will make the LLVM backend
 420 into a runtime-loadable module instead of linking it directly
 421 into the main mono binary.
 422
 423 * `--enable-big-arrays` - Enable use of arrays with indexes larger
 424 than Int32.MaxValue.
 425
 426   * By default Mono has the same limitation as .NET on
 427 Win32 and Win64 and limits array indexes to 32-bit
 428 values (even on 64-bit systems).
 429
 430   * In certain scenarios where large arrays are required,
 431 you can pass this flag and Mono will be built to
 432 support 64-bit arrays.
 433
 434   * This is not the default as it breaks the C embedding
 435 ABI that we have exposed through the Mono development
 436 cycle.
 437
 438 * `--enable-parallel-mark`
 439
 440   * Use this option to enable the garbage collector to use
 441 multiple CPUs to do its work.  This helps performance
 442 on multi-CPU machines as the work is divided across CPUS.
 443
 444   * This option is not currently the default on OSX
 445 as it runs into issues there.
 446
 447   * This option only applies to the Boehm GC.
 448
 449 * `--enable-dtrace`
 450
 451   * On Solaris and MacOS X builds a version of the Mono
 452 runtime that contains DTrace probes and can
 453 participate in the system profiling using DTrace.
 454
 455 * `--disable-dev-random`
 456
 457   * Mono uses /dev/random to obtain good random data for
 458 any source that requires random numbers.   If your
 459 system does not support this, you might want to
 460 disable it.
 461
 462   * There are a number of runtime options to control this
 463 also, see the man page.
 464
 465 * `--enable-nacl`
 466
 467   * This configures the Mono compiler to generate code
 468 suitable to be used by Google's Native Client:
 469 http://code.google.com/p/nativeclient/
 470
 471   * Currently this is used with Mono's AOT engine as
 472 Native Client does not support JIT engines yet.
 473
 474 Working With Submodules
 475 =======================
 476
 477 Mono references several external git submodules, for example
 478 a fork of Microsoft's reference source code that has been altered
 479 to be suitable for use with the Mono runtime.
 480
 481 This section describes how to use it.
 482
 483 An initial clone should be done recursively so all submodules will also be
 484 cloned in a single pass:
 485
 486         $ git clone --recursive git@github.com:mono/mono
 487
 488 Once cloned, submodules can be updated to pull down the latest changes.
 489 This can also be done after an initial non-recursive clone:
 490
 491         $ git submodule update --init --recursive
 492
 493 To pull external changes into a submodule:
 494
 495         $ cd <submodule>
 496         $ git pull origin <branch>
 497         $ cd <top-level>
 498         $ git add <submodule>
 499         $ git commit
 500
 501 By default, submodules are detached because they point to a specific commit.
 502 Use `git checkout` to move back to a branch before making changes:
 503
 504         $ cd <submodule>
 505         $ git checkout <branch>
 506         # work as normal; the submodule is a normal repo
 507         $ git commit/push new changes to the repo (submodule)
 508
 509         $ cd <top-level>
 510         $ git add <submodule> # this will record the new commits to the submodule
 511         $ git commit
 512
 513 To switch the repo of a submodule (this should not be a common or normal thing
 514 to do at all), first edit `.gitmodules` to point to the new location, then:
 515
 516         $ git submodule sync -- <path of the submodule>
 517         $ git submodule update --recursive
 518         $ git checkout <desired new hash or branch>
 519
 520 The desired output diff is a change in `.gitmodules` to reflect the
 521 change in the remote URL, and a change in /<submodule> where you see
 522 the desired change in the commit hash.
 523
 524 License
 525 =======
 526
 527 See the LICENSE file for licensing information, and the PATENTS.TXT
 528 file for information about Microsoft's patent grant.
 529
 530 Mono Trademark Use Policy
 531 =========================
 532
 533 The use of trademarks and logos for Mono can be found [here] (http://www.dotnetfoundation.org/legal/mono-tm).
 534
 535 Maintaining the Class Library Solution Files
 536 ============================================
 537
 538 Mono now ships with a solution file that can be used to build the
 539 assemblies from an IDE.  Either by opening the topmost `net_4_x.sln`
 540 file, or to by loading one of the individual `csproj` files located in
 541 each directory.
 542
 543 These are maintained by extracting the configuration information from
 544 our Makefiles, which as of May 2016 remain the canonical location for
 545 configuration information.
 546
 547 When changes are made to the Makefiles, a user would need to run the
 548 following command to re-generate the solution files at the top level:
 549
 550         $ make update-solution-files
 551