README.md

   1 Mono is a software platform designed to allow developers to easily create cross platform applications.
   2 Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
   3
   4 [![Build Status](http://monojenkins.cloudapp.net/job/Mono/badge/icon)](http://monojenkins.cloudapp.net/job/Mono/)
   5
   6 1. [Installation](#compilation-and-installation)
   7 2. [Using Mono](#using-mono)
   8 3. [Directory Roadmap](#directory-roadmap)
   9 4. [Contributing to Mono] (#contributing-to-mono)
  10 5. [Git submodules maintenance](#git-submodules-maintenance)
  11 6. [Reporting bugs](#reporting-bugs)
  12
  13 Compilation and Installation
  14 ============================
  15
  16 a. Build Requirements
  17 ---------------------
  18
  19 * On Itanium, you must obtain libunwind: http://www.hpl.hp.com/research/linux/libunwind/download.php4
  20
  21 * On Solaris
  22
  23  1. Make sure that you used GNU tar to unpack this package, as
  24  Solaris tar will not unpack this correctly, and you will get strange errors.
  25
  26  2. Make sure that you use the GNU toolchain to build the software.
  27
  28  3. Optional dependencies
  29
  30   * libgdiplus - Required for System.Drawing. This library in turn requires glib and pkg-config
  31
  32   * pkg-config - Available at: http://www.freedesktop.org/Software/pkgconfig
  33
  34   * glib 2.4 - Available at: http://www.gtk.org/
  35
  36   * libzlib - This library and the development headers are required for compression
  37 file support in the 2.0 profile.
  38
  39  4. Mono is required to build Mono. Use a system package or monolite (explained further below)
  40
  41  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
  42
  43 b. Building the Software
  44 ------------------------
  45
  46 If you obtained this package as an officially released tarball,
  47 this is very simple, use configure and make:
  48
  49 `./configure --prefix=/usr/local ; make ; make install`
  50
  51 Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390,
  52 S/390x, AMD64, ARM and PowerPC systems.
  53
  54 If you obtained this as a snapshot, you will need an existing
  55 Mono installation.  To upgrade your installation, unpack both
  56 mono and mcs:
  57
  58         tar xzf mcs-XXXX.tar.gz
  59         tar xzf mono-XXXX.tar.gz
  60         mv mono-XXX mono
  61         mv mcs-XXX mcs
  62         cd mono
  63         ./autogen.sh --prefix=/usr/local
  64         make
  65
  66 The Mono build system is silent for most compilation commands.
  67 To enable a more verbose compile (for example, to pinpoint
  68 problems in your makefiles or your system) pass the V=1 flag to make, like this:
  69
  70 ` make V=1`
  71
  72
  73 c. Building the software from GIT
  74 ---------------------------------
  75
  76 If you are building the software from GIT, make sure that you
  77 have up-to-date mcs and mono sources:
  78
  79  * If you are an anonymous user: `git clone git://github.com/mono/mono.git`
  80
  81  * If you are a Mono contributor with read/write privileges: `git clone git@github.com:mono/mono.git`
  82
  83 Then, go into the mono directory, and configure:
  84
  85         cd mono
  86         ./autogen.sh --prefix=/usr/local
  87         make
  88
  89 For people with non-standard installations of the auto* utils and of
  90 pkg-config (common on misconfigured OSX and windows boxes), you could get
  91 an error like this:
  92
  93         ./configure: line 19176: syntax error near unexpected token 'PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ...
  94
  95 This means that you need to set the ACLOCAL_FLAGS environment variable
  96 when invoking autogen.sh, like this:
  97
  98         ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/local
  99
 100 where $acprefix is the prefix where aclocal has been installed.
 101 This will automatically go into the mcs/ tree and build the
 102 binaries there.
 103
 104 This assumes that you have a working mono installation, and that
 105 there's a C# compiler named 'mcs', and a corresponding IL
 106 runtime called 'mono'.  You can use two make variables
 107 EXTERNAL_MCS and EXTERNAL_RUNTIME to override these.  e.g., you
 108 can say:
 109
 110         make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
 111
 112 If you don't have a working Mono installation
 113 ---------------------------------------------
 114
 115 If you don't have a working Mono installation, an obvious choice
 116 is to install the latest released packages of 'mono' for your
 117 distribution and running `autogen.sh; make; make install` in the
 118 mono module directory.
 119
 120 You can also try a slightly more risky approach: this may not work,
 121 so start from the released tarball as detailed above.
 122
 123 This works by first getting the latest version of the 'monolite'
 124 distribution, which contains just enough to run the 'mcs'
 125 compiler. You do this with:
 126
 127         # Run the following line after ./autogen.sh
 128         make get-monolite-latest
 129
 130 This will download and automatically gunzip and untar the
 131 tarball, and place the files appropriately so that you can then
 132 just run: `make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/gmcs.exe`
 133
 134 That will use the files downloaded by 'make get-monolite-latest.
 135
 136 Testing and Installation
 137 ------------------------
 138
 139 You can run *(part of)* the mono and mcs test suites with the command: `make check`.
 140 All tests should pass.
 141
 142 If you want more *extensive* tests, including those that test the
 143 class libraries, you need to re-run 'configure' with the
 144 '--enable-nunit-tests' flag, and try: `make -k check`
 145
 146 Expect to find a few test suite failures. As a sanity check, you
 147 can compare the failures you got with
 148
 149     https://wrench.mono-project.com/Wrench/
 150
 151 You can now install mono with: `make install`
 152
 153 You can verify your installation by using the mono-test-install
 154 script, it can diagnose some common problems with Mono's install.
 155 Failure to follow these steps may result in a broken installation.
 156
 157 d. Configuration Options
 158 ------------------------
 159
 160 The following are the configuration options that someone
 161 building Mono might want to use:
 162
 163 * `--with-sgen=yes,no` - Generational GC support: Used to enable or disable the
 164 compilation of a Mono runtime with the SGen garbage collector.
 165
 166   * On platforms that support it, after building Mono, you will have
 167 both a mono binary and a mono-sgen binary.  Mono uses Boehm, while
 168 mono-sgen uses the Simple Generational GC.
 169
 170 * `--with-gc=[boehm, included, sgen, none]` - Selects the default Boehm garbage
 171 collector engine to use.
 172
 173   * *included*: (*slighty modified Boehm GC*)
 174 This is the default value, and its
 175 the most feature complete, it will allow Mono
 176 to use typed allocations and support the
 177 debugger.
 178
 179   * *boehm*:
 180 This is used to use a system-install Boehm GC,
 181 it is useful to test new features available in
 182 Boehm GC, but we do not recommend that people
 183 use this, as it disables a few features.
 184
 185   * *none*:
 186 Disables the inclusion of a garbage collector.
 187
 188   * This defaults to `included`.
 189
 190 * `--with-tls=__thread,pthread`
 191
 192   * Controls how Mono should access thread local storage,
 193 pthread forces Mono to use the pthread APIs, while
 194 __thread uses compiler-optimized access to it.
 195
 196   * Although __thread is faster, it requires support from
 197 the compiler, kernel and libc. Old Linux systems do
 198 not support with __thread.
 199
 200   * This value is typically pre-configured and there is no
 201 need to set it, unless you are trying to debug a problem.
 202
 203 * `--with-sigaltstack=yes,no`
 204
 205   * **Experimental**: Use at your own risk, it is known to
 206 cause problems with garbage collection and is hard to
 207 reproduce those bugs.
 208
 209   * This controls whether Mono will install a special
 210 signal handler to handle stack overflows. If set to
 211 `yes`, it will turn stack overflows into the
 212 StackOverflowException. Otherwise when a stack
 213 overflow happens, your program will receive a
 214 segmentation fault.
 215
 216   * The configure script will try to detect if your
 217 operating system supports this. Some older Linux
 218 systems do not support this feature, or you might want
 219 to override the auto-detection.
 220
 221 * `--with-static_mono=yes,no`
 222
 223   * This controls whether `mono` should link against a
 224 static library (libmono.a) or a shared library
 225 (libmono.so).
 226
 227   * This defaults to `yes`, and will improve the performance
 228 of the `mono` program.
 229
 230   * This only affects the `mono' binary, the shared
 231 library libmono.so will always be produced for
 232 developers that want to embed the runtime in their
 233 application.
 234
 235 * `--with-xen-opt=yes,no` - Optimize code for Xen virtualization.
 236
 237   * It makes Mono generate code which might be slightly
 238 slower on average systems, but the resulting executable will run
 239 faster under the Xen virtualization system.
 240
 241   * This defaults to `yes`.
 242
 243 * `--with-large-heap=yes,no` - Enable support for GC heaps larger than 3GB.
 244
 245   * This defaults to `no`.
 246
 247 * `--enable-small-config=yes,no` - Enable some tweaks to reduce memory usage
 248 and disk footprint at the expense of some capabilities.
 249
 250   * Typically this means that the number of threads that can be created
 251 is limited (256), that the maximum heap size is also reduced (256 MB)
 252 and other such limitations that still make mono useful, but more suitable
 253 to embedded devices (like mobile phones).
 254
 255   * This defaults to `no`.
 256
 257 * `--with-ikvm-native=yes,no` - Controls whether the IKVM JNI interface library is
 258 built or not.
 259
 260   * This is used if you are planning on
 261 using the IKVM Java Virtual machine with Mono.
 262
 263   * This defaults to `yes`.
 264
 265 * `--with-profile4=yes,no` - Whether you want to build the 4.x profile libraries
 266 and runtime.
 267
 268   * This defaults to `yes`.
 269
 270 * `--with-moonlight=yes,no`
 271
 272   * Whether you want to generate the Silverlight/Moonlight
 273 libraries and toolchain in addition to the default
 274 (1.1 and 2.0 APIs).
 275
 276   * This will produce the `smcs` compiler which will reference
 277 the Silverlight modified assemblies (mscorlib.dll,
 278 System.dll, System.Code.dll and System.Xml.Core.dll) and turn
 279 on the LINQ extensions for the compiler.
 280
 281 * `--with-moon-gc=boehm,sgen` - Select the GC to use for Moonlight.
 282
 283   * *boehm*:
 284 Selects the Boehm Garbage Collector, with the same flags
 285 as the regular Mono build. This is the default.
 286
 287   * *sgen*:
 288 Selects the new SGen Garbage Collector, which provides
 289 Generational GC support, using the same flags as the
 290 mono-sgen build.
 291
 292   * This defaults to `boehm`.
 293
 294 * `--with-libgdiplus=installed,sibling,<path>` - Configure where Mono
 295 searches for libgdiplus when running System.Drawing tests.
 296
 297   * It defaults to `installed`, which means that the
 298 library is available to Mono through the regular
 299 system setup.
 300
 301   * `sibling' can be used to specify that a libgdiplus
 302 that resides as a sibling of this directory (mono)
 303 should be used.
 304
 305  * Or you can specify a path to a libgdiplus.
 306
 307 * `--disable-shared-memory`
 308
 309   * Use this option to disable the use of shared memory in
 310 Mono (this is equivalent to setting the MONO_DISABLE_SHM
 311 environment variable, although this removes the feature
 312 completely).
 313
 314   * Disabling the shared memory support will disable certain
 315 features like cross-process named mutexes.
 316
 317 * `--enable-minimal=LIST`
 318
 319   * Use this feature to specify optional runtime
 320 components that you might not want to include.  This
 321 is only useful for developers embedding Mono that
 322 require a subset of Mono functionality.
 323   * The list is a comma-separated list of components that
 324 should be removed, these are:
 325
 326     * `aot`:
 327 Disables support for the Ahead of Time compilation.
 328
 329     * `attach`:
 330 Support for the Mono.Management assembly and the
 331 VMAttach API (allowing code to be injected into
 332 a target VM)
 333
 334     * `com`:
 335 Disables COM support.
 336
 337     * `debug`:
 338 Drop debugging support.
 339
 340     * `decimal`:
 341 Disables support for System.Decimal.
 342
 343     * `full_messages`:
 344 By default Mono comes with a full table
 345 of messages for error codes. This feature
 346 turns off uncommon error messages and reduces
 347 the runtime size.
 348
 349     * `generics`:
 350 Generics support.  Disabling this will not
 351 allow Mono to run any 2.0 libraries or
 352 code that contains generics.
 353
 354     * `jit`:
 355 Removes the JIT engine from the build, this reduces
 356 the executable size, and requires that all code
 357 executed by the virtual machine be compiled with
 358 Full AOT before execution.
 359
 360     * `large_code`:
 361 Disables support for large assemblies.
 362
 363     * `logging`:
 364 Disables support for debug logging.
 365
 366     * `pinvoke`:
 367 Support for Platform Invocation services,
 368 disabling this will drop support for any
 369 libraries using DllImport.
 370
 371     * `portability`:
 372 Removes support for MONO_IOMAP, the environment
 373 variables for simplifying porting applications that
 374 are case-insensitive and that mix the Unix and Windows path separators.
 375
 376     * `profiler`:
 377 Disables support for the default profiler.
 378
 379     * `reflection_emit`:
 380 Drop System.Reflection.Emit support
 381
 382     * `reflection_emit_save`:
 383 Drop support for saving dynamically created
 384 assemblies (AssemblyBuilderAccess.Save) in
 385 System.Reflection.Emit.
 386
 387     * `shadow_copy`:
 388 Disables support for AppDomain's shadow copies
 389 (you can disable this if you do not plan on
 390 using appdomains).
 391
 392     * `simd`:
 393 Disables support for the Mono.SIMD intrinsics
 394 library.
 395
 396     * `ssa`:
 397 Disables compilation for the SSA optimization
 398 framework, and the various SSA-based optimizations.
 399
 400 * `--enable-llvm`
 401 * `--enable-loadedllvm`
 402
 403   * This enables the use of LLVM as a code generation engine
 404 for Mono.  The LLVM code generator and optimizer will be
 405 used instead of Mono's built-in code generator for both
 406 Just in Time and Ahead of Time compilations.
 407
 408   * See the http://www.mono-project.com/Mono_LLVM for the
 409 full details and up-to-date information on this feature.
 410
 411   * You will need to have an LLVM built that Mono can link
 412 against.
 413
 414   * The --enable-loadedllvm variant will make the LLVM backend
 415 into a runtime-loadable module instead of linking it directly
 416 into the main mono binary.
 417
 418 * `--enable-big-arrays` - Enable use of arrays with indexes larger
 419 than Int32.MaxValue.
 420
 421   * By default Mono has the same limitation as .NET on
 422 Win32 and Win64 and limits array indexes to 32-bit
 423 values (even on 64-bit systems).
 424
 425   * In certain scenarios where large arrays are required,
 426 you can pass this flag and Mono will be built to
 427 support 64-bit arrays.
 428
 429   * This is not the default as it breaks the C embedding
 430 ABI that we have exposed through the Mono development
 431 cycle.
 432
 433 * `--enable-parallel-mark`
 434
 435   * Use this option to enable the garbage collector to use
 436 multiple CPUs to do its work.  This helps performance
 437 on multi-CPU machines as the work is divided across CPUS.
 438
 439   * This option is not currently the default as we have
 440 not done much testing with Mono.
 441
 442 * `--enable-dtrace`
 443
 444   * On Solaris and MacOS X builds a version of the Mono
 445 runtime that contains DTrace probes and can
 446 participate in the system profiling using DTrace.
 447
 448
 449 * `--disable-dev-random`
 450
 451   * Mono uses /dev/random to obtain good random data for
 452 any source that requires random numbers.   If your
 453 system does not support this, you might want to
 454 disable it.
 455
 456   * There are a number of runtime options to control this
 457 also, see the man page.
 458
 459 * `--enable-nacl`
 460
 461   * This configures the Mono compiler to generate code
 462 suitable to be used by Google's Native Client:
 463 http://code.google.com/p/nativeclient/
 464
 465   * Currently this is used with Mono's AOT engine as
 466 Native Client does not support JIT engines yet.
 467
 468 Using Mono
 469 ==========
 470
 471 Once you have installed the software, you can run a few programs:
 472
 473 * `mono program.exe` runtime engine
 474
 475 * `mcs program.cs` C# compiler
 476
 477 * `monodis program.exe` CIL Disassembler
 478
 479 See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
 480 for further details.
 481
 482 Directory Roadmap
 483 =================
 484
 485 * `docs/` - Technical documents about the Mono runtime.
 486
 487 * `data/` - Configuration files installed as part of the Mono runtime.
 488
 489 * `mono/` - The core of the Mono Runtime.
 490
 491   * `metadata/` - The object system and metadata reader.
 492
 493   * `mini/` - The Just in Time Compiler.
 494
 495   * `dis/` - CIL executable Disassembler
 496
 497   * `cli/` - Common code for the JIT and the interpreter.
 498
 499   * `io-layer/` - The I/O layer and system abstraction for
 500 emulating the .NET IO model.
 501
 502   * `cil/` - Common Intermediate Representation, XML
 503 definition of the CIL bytecodes.
 504
 505  * `interp/` - Interpreter for CLI executables (obsolete).
 506
 507  * `arch/` - Architecture specific portions.
 508
 509 * `man/` - Manual pages for the various Mono commands and programs.
 510
 511 * `samples/` -Some simple sample programs on uses of the Mono
 512 runtime as an embedded library.
 513
 514 * `scripts/` - Scripts used to invoke Mono and the corresponding program.
 515
 516 * `runtime/` - A directory that contains the Makefiles that link the
 517 mono/ and mcs/ build systems.
 518
 519 * `../olive/`
 520
 521   * If the directory ../olive is present (as an
 522 independent checkout) from the Mono module, that
 523 directory is automatically configured to share the
 524 same prefix than this module gets.
 525
 526 Contributing to Mono
 527 ====================
 528 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.
 529
 530
 531 Git submodules maintenance
 532 ==========================
 533
 534 Read documentation at http://mono-project.com/Git_Submodule_Maintenance
 535
 536 Maintainer
 537 ==========
 538
 539 Mono is maintained by miguel@xamarin.com
 540
 541 Reporting bugs
 542 ==============
 543
 544 To submit bug reports, please use Xamarin's Bugzilla:
 545
 546 https://bugzilla.xamarin.com/
 547
 548 Please use the search facility to ensure the same bug hasn't already
 549 been submitted and follow our guidelines on how to make a good bug
 550 report:
 551
 552 http://mono-project.com/Bugs#How_to_make_a_good_bug_report