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