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