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