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