README.md

   1 Mono is a software platform designed to allow developers to easily create cross platform applications.
   2 It 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. [Compilation and 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. [Reporting bugs](#reporting-bugs)
   9 6. [Configuration Options](#configuration-options)
  10
  11 **Build Status**
  12
  13 | debian-amd64 | debian-i386 | centos-s390x | windows-amd64 |
  14 |:------------:|:-----------:|:------------:|:-------------:|
  15 | [![debian-amd64](http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-amd64/badge/icon)](http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-amd64/) | [![debian-i386](http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-i386/badge/icon)](http://jenkins.mono-project.com/job/test-mono-mainline/label=debian-i386/) | [![centos-s390x](http://jenkins.mono-project.com/job/test-mono-mainline/label=centos-s390x/badge/icon)](http://jenkins.mono-project.com/job/test-mono-mainline/label=centos-s390x/) | [![windows-amd64](https://ci.appveyor.com/api/projects/status/1e61ebdfpbiei58v/branch/master?svg=true)](https://ci.appveyor.com/project/ajlennon/mono-817/branch/master) |
  16
  17 Compilation and Installation
  18 ============================
  19
  20 Building the Software
  21 ---------------------
  22
  23 Please see our guides for building Mono on
  24 [Mac OS X](http://www.mono-project.com/docs/compiling-mono/mac/),
  25 [Linux](http://www.mono-project.com/docs/compiling-mono/linux/) and
  26 [Windows](http://www.mono-project.com/docs/compiling-mono/windows/).
  27
  28 Note that building from Git assumes that you already have Mono installed,
  29 so please download and [install the latest Mono release](http://www.mono-project.com/download/)
  30 before trying to build from Git. This is required because the Mono build
  31 relies on a working Mono C# compiler to compile itself
  32 (also known as [bootstrapping](http://en.wikipedia.org/wiki/Bootstrapping_(compilers))).
  33
  34 If you don't have a working Mono installation
  35 ---------------------------------------------
  36
  37 If you don't have a working Mono installation, you can try a slightly
  38 more risky approach: getting the latest version of the 'monolite' distribution,
  39 which contains just enough to run the 'mcs' compiler. You do this with:
  40
  41     # Run the following line after ./autogen.sh
  42     make get-monolite-latest
  43
  44 This will download and place the files appropriately so that you can then
  45 just run:
  46
  47     make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/basic.exe
  48
  49 The build will then use the files downloaded by `make get-monolite-latest`.
  50
  51 Testing and Installation
  52 ------------------------
  53
  54 You can run the mono and mcs test suites with the command: `make check`.
  55
  56 Expect to find a few test suite failures. As a sanity check, you
  57 can compare the failures you got with [https://wrench.mono-project.com/Wrench/](https://wrench.mono-project.com/Wrench/)
  58 and [http://jenkins.mono-project.com/](http://jenkins.mono-project.com/).
  59
  60 You can now install mono with: `make install`
  61
  62 You can verify your installation by using the mono-test-install
  63 script, it can diagnose some common problems with Mono's install.
  64 Failure to follow these steps may result in a broken installation.
  65
  66 Using Mono
  67 ==========
  68
  69 Once you have installed the software, you can run a few programs:
  70
  71 * `mono program.exe` runtime engine
  72
  73 * `mcs program.cs` C# compiler
  74
  75 * `monodis program.exe` CIL Disassembler
  76
  77 See the man pages for mono(1), mcs(1) and monodis(1) for further details.
  78
  79 Directory Roadmap
  80 =================
  81
  82 * `data/` - Configuration files installed as part of the Mono runtime.
  83
  84 * `docs/` - Technical documents about the Mono runtime.
  85
  86 * `external/` - Git submodules for external libraries (Newtonsoft.Json, ikvm, etc).
  87
  88 * `man/` - Manual pages for the various Mono commands and programs.
  89
  90 * `mcs/` - The class libraries, compiler and tools
  91
  92   * `class/` - The class libraries (like System.*, Microsoft.Build, etc.)
  93
  94   * `mcs/` - The Mono C# compiler written in C#
  95
  96   * `tools/` - Tools like gacutil, ikdasm, mdoc, etc.
  97
  98 * `mono/` - The core of the Mono Runtime.
  99
 100   * `arch/` - Architecture specific portions.
 101
 102   * `cil/` - Common Intermediate Representation, XML
 103 definition of the CIL bytecodes.
 104
 105   * `dis/` - CIL executable Disassembler
 106
 107   * `io-layer/` - The I/O layer and system abstraction for
 108 emulating the .NET IO model.
 109
 110   * `metadata/` - The object system and metadata reader.
 111
 112   * `mini/` - The Just in Time Compiler.
 113
 114 * `runtime/` - A directory that contains the Makefiles that link the
 115 mono/ and mcs/ build systems.
 116
 117 * `samples/` -Some simple sample programs on uses of the Mono
 118 runtime as an embedded library.
 119
 120 * `scripts/` - Scripts used to invoke Mono and the corresponding program.
 121
 122 * `../olive/` - Incubation code from [Olive](https://github.com/mono/olive).
 123
 124   * If the directory ../olive is present (as an
 125 independent checkout) from the Mono module, that
 126 directory is automatically configured to share the
 127 same prefix than this module gets.
 128
 129 Contributing to Mono
 130 ====================
 131
 132 Before submitting changes to Mono, please review the [contribution guidelines](http://www.mono-project.com/community/contributing/).
 133 Please pay particular attention to the [Important Rules](http://www.mono-project.com/community/contributing/#important-rules) section.
 134
 135 Reporting bugs
 136 ==============
 137
 138 To submit bug reports, please use [Xamarin's Bugzilla](https://bugzilla.xamarin.com/)
 139
 140 Please use the search facility to ensure the same bug hasn't already
 141 been submitted and follow our [guidelines](http://www.mono-project.com/community/bugs/make-a-good-bug-report/)
 142 on how to make a good bug report.
 143
 144 Configuration Options
 145 =====================
 146
 147 The following are the configuration options that someone
 148 building Mono might want to use:
 149
 150 * `--with-sgen=yes,no` - Generational GC support: Used to enable or disable the
 151 compilation of a Mono runtime with the SGen garbage collector.
 152
 153   * On platforms that support it, after building Mono, you will have
 154 both a `mono` binary and a `mono-sgen` binary. `mono` uses Boehm, while
 155 `mono-sgen` uses the Simple Generational GC.
 156
 157 * `--with-gc=[included, boehm,  none]` - Selects the default Boehm garbage
 158 collector engine to use.
 159
 160   * *included*: (*slighty modified Boehm GC*)
 161 This is the default value for the Boehm GC, and it's
 162 the most feature complete, it will allow Mono
 163 to use typed allocations and support the debugger.
 164
 165   * *boehm*:
 166 This is used to use a system-install Boehm GC,
 167 it is useful to test new features available in
 168 Boehm GC, but we do not recommend that people
 169 use this, as it disables a few features.
 170
 171   * *none*:
 172 Disables the inclusion of a garbage collector.
 173
 174   * This defaults to `included`.
 175
 176 * `--with-tls=__thread,pthread`
 177
 178   * Controls how Mono should access thread local storage,
 179 pthread forces Mono to use the pthread APIs, while
 180 __thread uses compiler-optimized access to it.
 181
 182   * Although __thread is faster, it requires support from
 183 the compiler, kernel and libc. Old Linux systems do
 184 not support with __thread.
 185
 186   * This value is typically pre-configured and there is no
 187 need to set it, unless you are trying to debug a problem.
 188
 189 * `--with-sigaltstack=yes,no`
 190
 191   * **Experimental**: Use at your own risk, it is known to
 192 cause problems with garbage collection and is hard to
 193 reproduce those bugs.
 194
 195   * This controls whether Mono will install a special
 196 signal handler to handle stack overflows. If set to
 197 `yes`, it will turn stack overflows into the
 198 StackOverflowException. Otherwise when a stack
 199 overflow happens, your program will receive a
 200 segmentation fault.
 201
 202   * The configure script will try to detect if your
 203 operating system supports this. Some older Linux
 204 systems do not support this feature, or you might want
 205 to override the auto-detection.
 206
 207 * `--with-static_mono=yes,no`
 208
 209   * This controls whether `mono` should link against a
 210 static library (libmono.a) or a shared library
 211 (libmono.so).
 212
 213   * This defaults to `yes`, and will improve the performance
 214 of the `mono` program.
 215
 216   * This only affects the `mono' binary, the shared
 217 library libmono.so will always be produced for
 218 developers that want to embed the runtime in their
 219 application.
 220
 221 * `--with-xen-opt=yes,no` - Optimize code for Xen virtualization.
 222
 223   * It makes Mono generate code which might be slightly
 224 slower on average systems, but the resulting executable will run
 225 faster under the Xen virtualization system.
 226
 227   * This defaults to `yes`.
 228
 229 * `--with-large-heap=yes,no` - Enable support for GC heaps larger than 3GB.
 230
 231   * This defaults to `no`.
 232
 233 * `--enable-small-config=yes,no` - Enable some tweaks to reduce memory usage
 234 and disk footprint at the expense of some capabilities.
 235
 236   * Typically this means that the number of threads that can be created
 237 is limited (256), that the maximum heap size is also reduced (256 MB)
 238 and other such limitations that still make mono useful, but more suitable
 239 to embedded devices (like mobile phones).
 240
 241   * This defaults to `no`.
 242
 243 * `--with-ikvm-native=yes,no` - Controls whether the IKVM JNI interface library is
 244 built or not.
 245
 246   * This is used if you are planning on
 247 using the IKVM Java Virtual machine with Mono.
 248
 249   * This defaults to `yes`.
 250
 251 * `--with-profile4=yes,no` - Whether you want to build the 4.x profile libraries
 252 and runtime.
 253
 254   * This defaults to `yes`.
 255
 256 * `--with-libgdiplus=installed,sibling,<path>` - Configure where Mono
 257 searches for libgdiplus when running System.Drawing tests.
 258
 259   * It defaults to `installed`, which means that the
 260 library is available to Mono through the regular
 261 system setup.
 262
 263   * `sibling` can be used to specify that a libgdiplus
 264 that resides as a sibling of this directory (mono)
 265 should be used.
 266
 267  * Or you can specify a path to a libgdiplus.
 268
 269 * `--disable-shared-memory`
 270
 271   * Use this option to disable the use of shared memory in
 272 Mono (this is equivalent to setting the MONO_DISABLE_SHM
 273 environment variable, although this removes the feature
 274 completely).
 275
 276   * Disabling the shared memory support will disable certain
 277 features like cross-process named mutexes.
 278
 279 * `--enable-minimal=LIST`
 280
 281   * Use this feature to specify optional runtime
 282 components that you might not want to include.  This
 283 is only useful for developers embedding Mono that
 284 require a subset of Mono functionality.
 285   * The list is a comma-separated list of components that
 286 should be removed, these are:
 287
 288     * `aot`:
 289 Disables support for the Ahead of Time compilation.
 290
 291     * `attach`:
 292 Support for the Mono.Management assembly and the
 293 VMAttach API (allowing code to be injected into
 294 a target VM)
 295
 296     * `com`:
 297 Disables COM support.
 298
 299     * `debug`:
 300 Drop debugging support.
 301
 302     * `decimal`:
 303 Disables support for System.Decimal.
 304
 305     * `full_messages`:
 306 By default Mono comes with a full table
 307 of messages for error codes. This feature
 308 turns off uncommon error messages and reduces
 309 the runtime size.
 310
 311     * `generics`:
 312 Generics support.  Disabling this will not
 313 allow Mono to run any 2.0 libraries or
 314 code that contains generics.
 315
 316     * `jit`:
 317 Removes the JIT engine from the build, this reduces
 318 the executable size, and requires that all code
 319 executed by the virtual machine be compiled with
 320 Full AOT before execution.
 321
 322     * `large_code`:
 323 Disables support for large assemblies.
 324
 325     * `logging`:
 326 Disables support for debug logging.
 327
 328     * `pinvoke`:
 329 Support for Platform Invocation services,
 330 disabling this will drop support for any
 331 libraries using DllImport.
 332
 333     * `portability`:
 334 Removes support for MONO_IOMAP, the environment
 335 variables for simplifying porting applications that
 336 are case-insensitive and that mix the Unix and Windows path separators.
 337
 338     * `profiler`:
 339 Disables support for the default profiler.
 340
 341     * `reflection_emit`:
 342 Drop System.Reflection.Emit support
 343
 344     * `reflection_emit_save`:
 345 Drop support for saving dynamically created
 346 assemblies (AssemblyBuilderAccess.Save) in
 347 System.Reflection.Emit.
 348
 349     * `shadow_copy`:
 350 Disables support for AppDomain's shadow copies
 351 (you can disable this if you do not plan on
 352 using appdomains).
 353
 354     * `simd`:
 355 Disables support for the Mono.SIMD intrinsics
 356 library.
 357
 358     * `ssa`:
 359 Disables compilation for the SSA optimization
 360 framework, and the various SSA-based optimizations.
 361
 362 * `--enable-llvm`
 363 * `--enable-loadedllvm`
 364
 365   * This enables the use of LLVM as a code generation engine
 366 for Mono.  The LLVM code generator and optimizer will be
 367 used instead of Mono's built-in code generator for both
 368 Just in Time and Ahead of Time compilations.
 369
 370   * See http://www.mono-project.com/docs/advanced/mono-llvm/ for the
 371 full details and up-to-date information on this feature.
 372
 373   * You will need to have an LLVM built that Mono can link
 374 against.
 375
 376   * The `--enable-loadedllvm` variant will make the LLVM backend
 377 into a runtime-loadable module instead of linking it directly
 378 into the main mono binary.
 379
 380 * `--enable-big-arrays` - Enable use of arrays with indexes larger
 381 than Int32.MaxValue.
 382
 383   * By default Mono has the same limitation as .NET on
 384 Win32 and Win64 and limits array indexes to 32-bit
 385 values (even on 64-bit systems).
 386
 387   * In certain scenarios where large arrays are required,
 388 you can pass this flag and Mono will be built to
 389 support 64-bit arrays.
 390
 391   * This is not the default as it breaks the C embedding
 392 ABI that we have exposed through the Mono development
 393 cycle.
 394
 395 * `--enable-parallel-mark`
 396
 397   * Use this option to enable the garbage collector to use
 398 multiple CPUs to do its work.  This helps performance
 399 on multi-CPU machines as the work is divided across CPUS.
 400
 401   * This option is not currently the default as we have
 402 not done much testing with Mono.
 403
 404 * `--enable-dtrace`
 405
 406   * On Solaris and MacOS X builds a version of the Mono
 407 runtime that contains DTrace probes and can
 408 participate in the system profiling using DTrace.
 409
 410 * `--disable-dev-random`
 411
 412   * Mono uses /dev/random to obtain good random data for
 413 any source that requires random numbers.   If your
 414 system does not support this, you might want to
 415 disable it.
 416
 417   * There are a number of runtime options to control this
 418 also, see the man page.
 419
 420 * `--enable-nacl`
 421
 422   * This configures the Mono compiler to generate code
 423 suitable to be used by Google's Native Client:
 424 http://code.google.com/p/nativeclient/
 425
 426   * Currently this is used with Mono's AOT engine as
 427 Native Client does not support JIT engines yet.