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