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