README

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