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