README

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