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