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, AMD64, ARM
  56         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     c. Building the software from SVN
  71     ---------------------------------
  72
  73         If you are building the software from SVN, make sure that you
  74         have up-to-date mcs and mono sources:
  75
  76                 svn co svn+ssh://USER@mono-cvs.ximian.com/source/trunk/mono
  77                 svn co svn+ssh://USER@mono-cvs.ximian.com/source/trunk/mcs
  78
  79         Then, go into the mono directory, and configure:
  80
  81                 cd mono
  82                 ./autogen.sh --prefix=/usr/local
  83                 make
  84
  85         This will automatically go into the mcs/ tree and build the
  86         binaries there.
  87
  88         This assumes that you have a working mono installation, and that
  89         there's a C# compiler named 'mcs', and a corresponding IL
  90         runtime called 'mono'.  You can use two make variables
  91         EXTERNAL_MCS and EXTERNAL_RUNTIME to override these.  e.g., you
  92         can say
  93
  94           make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
  95
  96         If you don't have a working Mono installation
  97         ---------------------------------------------
  98
  99         If you don't have a working Mono installation, an obvious choice
 100         is to install the latest released packages of 'mono' for your
 101         distribution and running autogen.sh; make; make install in the
 102         mono module directory.
 103
 104         You can also try a slightly more risky approach: this may not work,
 105         so start from the released tarball as detailed above.
 106
 107         This works by first getting the latest version of the 'monolite'
 108         distribution, which contains just enough to run the 'mcs'
 109         compiler.  You do this with:
 110
 111                 make get-monolite-latest
 112
 113         This will download and automatically gunzip and untar the
 114         tarball, and place the files appropriately so that you can then
 115         just run:
 116
 117                 make
 118
 119         To ensure that you're using the 'monolite' distribution, you can
 120         also try passing EXTERNAL_MCS=false on the make command-line.
 121
 122         Testing and Installation
 123          ------------------------
 124
 125         You can run (part of) the mono and mcs testsuites with the command:
 126
 127                 make check
 128
 129         All tests should pass.
 130
 131         If you want more extensive tests, including those that test the
 132         class libraries, you need to re-run 'configure' with the
 133         '--enable-nunit-tests' flag, and try
 134
 135                 make -k check
 136
 137         Expect to find a few testsuite failures.  As a sanity check, you
 138         can compare the failures you got with
 139
 140                 http://go-mono.com/tests/displayTestResults.php
 141
 142         You can now install mono with:
 143
 144                 make install
 145
 146         Failure to follow these steps may result in a broken installation.
 147
 148     d. Common Configuration Options
 149     -------------------------------
 150
 151         The following are the configuration options that someone
 152         building Mono might want to use:
 153
 154
 155         --with-gc=[boehm, included, sgen, none]
 156
 157                 Selects the garbage collector engine to use, the
 158                 default is the "included" value.
 159
 160                 included:
 161                         This is the default value, and its
 162                         the most feature complete, it will allow Mono
 163                         to use typed allocations and support the
 164                         debugger.
 165
 166                         It is essentially a slightly modified Boehm GC
 167
 168                 boehm:
 169                         This is used to use a system-install Boehm GC,
 170                         it is useful to test new features available in
 171                         Boehm GC, but we do not recommend that people
 172                         use this, as it disables a few features.
 173
 174                 sgen:
 175                         The under-development Generational GC for
 176                         Mono, do not use this in production.
 177
 178                 none:
 179                         Disables the inclusion of a garbage
 180                         collector.
 181
 182         --with-tls=__thread,pthread
 183
 184                 Controls how Mono should access thread local storage,
 185                 pthread forces Mono to use the pthread APIs, while
 186                 __thread uses compiler-optimized access to it.
 187
 188                 Although __thread is faster, it requires support from
 189                 the compiler, kernel and libc.   Old Linux systems do
 190                 not support with __thread.
 191
 192                 This value is typically pre-configured and there is no
 193                 need to set it, unless you are trying to debug a
 194                 problem.
 195
 196         --with-sigaltstack=yes,no
 197
 198                 This controls whether Mono will install a special
 199                 signal handler to handle stack overflows.   If set to
 200                 "yes", it will turn stack overflows into the
 201                 StackOverflowException.  Otherwise when a stack
 202                 overflow happens, your program will receive a
 203                 segmentation fault.
 204
 205                 The configure script will try to detect if your
 206                 operating system supports this.   Some older Linux
 207                 systems do not support this feature, or you might want
 208                 to override the auto-detection.
 209
 210         --with-static-mono=yes,no
 211
 212                 This controls whether `mono' should link against a
 213                 static library (libmono.a) or a shared library
 214                 (libmono.so).
 215
 216                 This defaults to yes, and will improve the performance
 217                 of the `mono' program.
 218
 219                 This only affects the `mono' binary, the shared
 220                 library libmono.so will always be produced for
 221                 developers that want to embed the runtime in their
 222                 application.
 223
 224         --with-xen-opt=yes,no
 225
 226                 The default value for this is `yes', and it makes Mono
 227                 generate code which might be slightly slower on
 228                 average systems, but the resulting executable will run
 229                 faster under the Xen virtualization system.
 230
 231         --with-large-heap=yes,no
 232
 233                 Enable support for GC heaps larger than 3GB.
 234
 235                 This value is set to `no' by default.
 236
 237         --with-ikvm-native=yes,no
 238
 239                 Controls whether the IKVM JNI interface library is
 240                 built or not.  This is used if you are planning on
 241                 using the IKVM Java Virtual machine with Mono.
 242
 243                 This defaults to `yes'.
 244
 245         --with-preview=yes,no
 246
 247                 Whether you want to build libraries that are still not
 248                 completed (The 2.0 APIs).   It defaults to `yes'.
 249
 250         --with-libgdiplus=installed,sibling,<path>
 251
 252                 This is used to configure where should Mono look for
 253                 libgdiplus when running the System.Drawing tests.
 254
 255                 It defaults to `installed', which means that the
 256                 library is available to Mono through the regular
 257                 system setup.
 258
 259                 `sibling' can be used to specify that a libgdiplus
 260                 that resides as a sibling of this directory (mono)
 261                 should be used.
 262
 263                 Or you can specify a path to a libgdiplus.
 264
 265         --enable-minimal=LIST
 266
 267                 Use this feature to specify optional runtime
 268                 components that you might not want to include.  This
 269                 is only useful for developers embedding Mono that
 270                 require a subset of Mono functionality.
 271
 272                 The list is a comma-separated list of components that
 273                 should be removed, these are:
 274
 275                 aot:
 276                         Disables support for the Ahead of Time
 277                         compilation.
 278
 279                 profiler:
 280                         Disables support for the default profiler.
 281
 282                 decimal:
 283                         Disables support for System.Decimal.
 284
 285                 pinvoke:
 286                         Support for Platform Invocation services,
 287                         disabling this will drop support for any
 288                         libraries using DllImport.
 289
 290                 debug:
 291                         Drop debugging support.
 292
 293                 reflection_emit:
 294                         Drop System.Reflection.Emit support
 295
 296                 large_code:
 297                         Disables support for large assemblies.
 298
 299                 logging:
 300                         Disables support for debug logging.
 301
 302                 com:
 303                         Disables COM support.
 304
 305                 ssa:
 306                         Disables compilation for the SSA optimization
 307                         framework, and the various SSA-based
 308                         optimizations.
 309
 310                 generics:
 311                         Generics support.  Disabling this will not
 312                         allow Mono to run any 2.0 libraries or
 313                         code that contains generics.
 314
 315         --disable-dev-random
 316
 317                 Mono uses /dev/random to obtain good random data for
 318                 any source that requires random numbers.   If your
 319                 system does not support this, you might want to
 320                 disable it.
 321
 322                 There are a number of runtime options to control this
 323                 also, see the man page.
 324
 325
 326 2. Using Mono
 327 =============
 328
 329         Once you have installed the software, you can run a few programs:
 330
 331         * runtime engine
 332
 333                 mono program.exe
 334
 335         * C# compiler
 336
 337                 mcs program.cs
 338
 339         * CIL Disassembler
 340
 341                 monodis program.exe
 342
 343         See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
 344         for further details.
 345
 346 3. Directory Roadmap
 347 ====================
 348
 349         docs/
 350                 Technical documents about the Mono runtime.
 351
 352         data/
 353                 Configuration files installed as part of the Mono runtime.
 354
 355         mono/
 356                 The core of the Mono Runtime.
 357
 358                 metadata/
 359                         The object system and metadata reader.
 360
 361                 mini/
 362                         The Just in Time Compiler.
 363
 364                 dis/
 365                         CIL executable Disassembler
 366
 367                 cli/
 368                         Common code for the JIT and the interpreter.
 369
 370                 io-layer/
 371                         The I/O layer and system abstraction for
 372                         emulating the .NET IO model.
 373
 374                 cil/
 375                         Common Intermediate Representation, XML
 376                         definition of the CIL bytecodes.
 377
 378                 interp/
 379                         Interpreter for CLI executables (obsolete).
 380
 381                 arch/
 382                         Architecture specific portions.
 383
 384         man/
 385
 386                 Manual pages for the various Mono commands and programs.
 387
 388         scripts/
 389
 390                 Scripts used to invoke Mono and the corresponding program.
 391
 392         runtime/
 393
 394                 A directory that contains the Makefiles that link the
 395                 mono/ and mcs/ build systems.
 396