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         On Itanium, you must obtain libunwind:
  15
  16                 http://www.hpl.hp.com/research/linux/libunwind/download.php4
  17
  18         On Solaris, make sure that you used GNU tar to unpack this package, as
  19         Solaris tar will not unpack this correctly, and you will get strange errors.
  20
  21         On Solaris, make sure that you use the GNU toolchain to build the software.
  22
  23         Optional dependencies:
  24
  25                 * libgdiplus
  26
  27                   If you want to get support for System.Drawing, you will need to get
  28                   Libgdiplus.    This library in turn requires glib and pkg-config:
  29
  30                         * pkg-config
  31
  32                           Available from: http://www.freedesktop.org/Software/pkgconfig
  33
  34                         * glib 2.4
  35
  36                           Available from: http://www.gtk.org/
  37
  38                 * libzlib
  39
  40                   This library and the development headers are required for compression
  41                   file support in the 2.0 profile.
  42
  43     b. Building the Software
  44     ------------------------
  45
  46         If you obtained this package as an officially released tarball,
  47         this is very simple, use configure and make:
  48
  49                 ./configure --prefix=/usr/local
  50                 make
  51                 make install
  52
  53         Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390,
  54         S/390x, AMD64, ARM and PowerPC systems.
  55
  56         If you obtained this as a snapshot, you will need an existing
  57         Mono installation.  To upgrade your installation, unpack both
  58         mono and mcs:
  59
  60                 tar xzf mcs-XXXX.tar.gz
  61                 tar xzf mono-XXXX.tar.gz
  62                 mv mono-XXX mono
  63                 mv mcs-XXX mcs
  64                 cd mono
  65                 ./autogen.sh --prefix=/usr/local
  66                 make
  67
  68         The Mono build system is silent for most compilation commands.
  69         To enable a more verbose compile (for example, to pinpoint
  70         problems in your makefiles or your system) pass the V=1 flag to make, like this:
  71
  72                  make V=1
  73
  74
  75     c. Building the software from GIT
  76     ---------------------------------
  77
  78         If you are building the software from GIT, make sure that you
  79         have up-to-date mcs and mono sources:
  80
  81            If you are an anonymous user:
  82                 git clone git://github.com/mono/mono.git
  83
  84            If you are a Mono contributors with read/write privileges:
  85                 git clone git@github.com:mono/mono.git
  86
  87
  88         Then, go into the mono directory, and configure:
  89
  90                 cd mono
  91                 ./autogen.sh --prefix=/usr/local
  92                 make
  93
  94         For people with non-standard installations of the auto* utils and of
  95         pkg-config (common on misconfigured OSX and windows boxes), you could get
  96         an error like this:
  97
  98         ./configure: line 19176: syntax error near unexpected token `PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ...
  99
 100         This means that you need to set the ACLOCAL_FLAGS environment var
 101         when invoking autogen.sh, like this:
 102
 103                 ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/loca
 104
 105         where $acprefix is the prefix where aclocal has been installed.
 106
 107         This will automatically go into the mcs/ tree and build the
 108         binaries there.
 109
 110         This assumes that you have a working mono installation, and that
 111         there's a C# compiler named 'mcs', and a corresponding IL
 112         runtime called 'mono'.  You can use two make variables
 113         EXTERNAL_MCS and EXTERNAL_RUNTIME to override these.  e.g., you
 114         can say
 115
 116           make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
 117
 118         If you don't have a working Mono installation
 119         ---------------------------------------------
 120
 121         If you don't have a working Mono installation, an obvious choice
 122         is to install the latest released packages of 'mono' for your
 123         distribution and running autogen.sh; make; make install in the
 124         mono module directory.
 125
 126         You can also try a slightly more risky approach: this may not work,
 127         so start from the released tarball as detailed above.
 128
 129         This works by first getting the latest version of the 'monolite'
 130         distribution, which contains just enough to run the 'mcs'
 131         compiler.  You do this with:
 132
 133                 # Run the following line after ./autogen.sh
 134                 make get-monolite-latest
 135
 136         This will download and automatically gunzip and untar the
 137         tarball, and place the files appropriately so that you can then
 138         just run:
 139
 140                 make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/gmcs.exe
 141
 142         And that will use the files downloaded by 'make get-monolite-latest.
 143
 144         Testing and Installation
 145         ------------------------
 146
 147         You can run (part of) the mono and mcs testsuites with the command:
 148
 149                 make check
 150
 151         All tests should pass.
 152
 153         If you want more extensive tests, including those that test the
 154         class libraries, you need to re-run 'configure' with the
 155         '--enable-nunit-tests' flag, and try
 156
 157                 make -k check
 158
 159         Expect to find a few testsuite failures.  As a sanity check, you
 160         can compare the failures you got with
 161
 162                 http://go-mono.com/tests/displayTestResults.php
 163
 164         You can now install mono with:
 165
 166                 make install
 167
 168         You can verify your installation by using the mono-test-install
 169         script, it can diagnose some common problems with Mono's install.
 170
 171         Failure to follow these steps may result in a broken installation.
 172
 173     d. 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-moon-gc=boehm,sgen
 309
 310                 Select the GC to use for Moonlight.
 311
 312                 boehm:
 313                         Selects the Boehm Garbage Collector, with the same flags
 314                         as the regular Mono build. This is the default.
 315
 316                 sgen:
 317                         Selects the new SGen Garbage Collector, which provides
 318                         Generational GC support, using the same flags as the
 319                         mono-sgen build.
 320
 321                 This defaults to `boehm'.
 322
 323         --with-libgdiplus=installed,sibling,<path>
 324
 325                 This is used to configure where should Mono look for
 326                 libgdiplus when running the System.Drawing tests.
 327
 328                 It defaults to `installed', which means that the
 329                 library is available to Mono through the regular
 330                 system setup.
 331
 332                 `sibling' can be used to specify that a libgdiplus
 333                 that resides as a sibling of this directory (mono)
 334                 should be used.
 335
 336                 Or you can specify a path to a libgdiplus.
 337
 338         --disable-shared-memory
 339
 340                 Use this option to disable the use of shared memory in
 341                 Mono (this is equivalent to setting the MONO_DISABLE_SHM
 342                 environment variable, although this removes the feature
 343                 completely).
 344
 345                 Disabling the shared memory support will disable certain
 346                 features like cross-process named mutexes.
 347
 348         --enable-minimal=LIST
 349
 350                 Use this feature to specify optional runtime
 351                 components that you might not want to include.  This
 352                 is only useful for developers embedding Mono that
 353                 require a subset of Mono functionality.
 354
 355                 The list is a comma-separated list of components that
 356                 should be removed, these are:
 357
 358                 aot:
 359                         Disables support for the Ahead of Time
 360                         compilation.
 361
 362                 attach:
 363                         Support for the Mono.Management assembly and the
 364                         VMAttach API (allowing code to be injected into
 365                         a target VM)
 366
 367                 com:
 368                         Disables COM support.
 369
 370                 debug:
 371                         Drop debugging support.
 372
 373                 decimal:
 374                         Disables support for System.Decimal.
 375
 376                 full_messages:
 377                         By default Mono comes with a full table
 378                         of messages for error codes.   This feature
 379                         turns off uncommon error messages and reduces
 380                         the runtime size.
 381
 382                 generics:
 383                         Generics support.  Disabling this will not
 384                         allow Mono to run any 2.0 libraries or
 385                         code that contains generics.
 386
 387                 jit:
 388                         Removes the JIT engine from the build, this reduces
 389                         the executable size, and requires that all code
 390                         executed by the virtual machine be compiled with
 391                         Full AOT before execution.
 392
 393                 large_code:
 394                         Disables support for large assemblies.
 395
 396                 logging:
 397                         Disables support for debug logging.
 398
 399                 pinvoke:
 400                         Support for Platform Invocation services,
 401                         disabling this will drop support for any
 402                         libraries using DllImport.
 403
 404                 portability:
 405                         Removes support for MONO_IOMAP, the environment
 406                         variables for simplifying porting applications that
 407                         are case-insensitive and that mix the Unix and Windows path separators.
 408
 409                 profiler:
 410                         Disables support for the default profiler.
 411
 412                 reflection_emit:
 413                         Drop System.Reflection.Emit support
 414
 415                 reflection_emit_save:
 416                         Drop support for saving dynamically created
 417                         assemblies (AssemblyBuilderAccess.Save) in
 418                         System.Reflection.Emit.
 419
 420                 shadow_copy:
 421                         Disables support for AppDomain's shadow copies
 422                         (you can disable this if you do not plan on
 423                         using appdomains).
 424
 425                 simd:
 426                         Disables support for the Mono.SIMD intrinsics
 427                         library.
 428
 429                 ssa:
 430                         Disables compilation for the SSA optimization
 431                         framework, and the various SSA-based
 432                         optimizations.
 433
 434         --enable-llvm
 435         --enable-loadedllvm
 436
 437                 This enables the use of LLVM as a code generation engine
 438                 for Mono.  The LLVM code generator and optimizer will be
 439                 used instead of Mono's built-in code generator for both
 440                 Just in Time and Ahead of Time compilations.
 441
 442                 See the http://www.mono-project.com/Mono_LLVM for the
 443                 full details and up-to-date information on this feature.
 444
 445                 You will need to have an LLVM built that Mono can link
 446                 against,
 447
 448                 The --enable-loadedllvm variant will make the llvm backend
 449                 into a runtime-loadable module instead of linking it directly
 450                 into the main mono binary.
 451
 452         --enable-big-arrays
 453
 454                 This enables the use arrays whose indexes are larger
 455                 than Int32.MaxValue.
 456
 457                 By default Mono has the same limitation as .NET on
 458                 Win32 and Win64 and limits array indexes to 32-bit
 459                 values (even on 64-bit systems).
 460
 461                 In certain scenarios where large arrays are required,
 462                 you can pass this flag and Mono will be built to
 463                 support 64-bit arrays.
 464
 465                 This is not the default as it breaks the C embedding
 466                 ABI that we have exposed through the Mono development
 467                 cycle.
 468
 469         --enable-parallel-mark
 470
 471                 Use this option to enable the garbage collector to use
 472                 multiple CPUs to do its work.  This helps performance
 473                 on multi-CPU machines as the work is divided across CPUS.
 474
 475                 This option is not currently the default as we have
 476                 not done much testing with Mono.
 477
 478         --enable-dtrace
 479
 480                 On Solaris and MacOS X builds a version of the Mono
 481                 runtime that contains DTrace probes and can
 482                 participate in the system profiling using DTrace.
 483
 484
 485         --disable-dev-random
 486
 487                 Mono uses /dev/random to obtain good random data for
 488                 any source that requires random numbers.   If your
 489                 system does not support this, you might want to
 490                 disable it.
 491
 492                 There are a number of runtime options to control this
 493                 also, see the man page.
 494
 495         --enable-nacl
 496
 497                 This configures the Mono compiler to generate code
 498                 suitable to be used by Google's Native Client:
 499
 500                          http://code.google.com/p/nativeclient/
 501
 502                 Currently this is used with Mono's AOT engine as
 503                 Native Client does not support JIT engines yet.
 504
 505 2. Using Mono
 506 =============
 507
 508         Once you have installed the software, you can run a few programs:
 509
 510         * runtime engine
 511
 512                 mono program.exe
 513
 514         * C# compiler
 515
 516                 mcs program.cs
 517
 518         * CIL Disassembler
 519
 520                 monodis program.exe
 521
 522         See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
 523         for further details.
 524
 525 3. Directory Roadmap
 526 ====================
 527
 528         docs/
 529                 Technical documents about the Mono runtime.
 530
 531         data/
 532                 Configuration files installed as part of the Mono runtime.
 533
 534         mono/
 535                 The core of the Mono Runtime.
 536
 537                 metadata/
 538                         The object system and metadata reader.
 539
 540                 mini/
 541                         The Just in Time Compiler.
 542
 543                 dis/
 544                         CIL executable Disassembler
 545
 546                 cli/
 547                         Common code for the JIT and the interpreter.
 548
 549                 io-layer/
 550                         The I/O layer and system abstraction for
 551                         emulating the .NET IO model.
 552
 553                 cil/
 554                         Common Intermediate Representation, XML
 555                         definition of the CIL bytecodes.
 556
 557                 interp/
 558                         Interpreter for CLI executables (obsolete).
 559
 560                 arch/
 561                         Architecture specific portions.
 562
 563         man/
 564
 565                 Manual pages for the various Mono commands and programs.
 566
 567         samples/
 568
 569                 Some simple sample programs on uses of the Mono
 570                 runtime as an embedded library.
 571
 572         scripts/
 573
 574                 Scripts used to invoke Mono and the corresponding program.
 575
 576         runtime/
 577
 578                 A directory that contains the Makefiles that link the
 579                 mono/ and mcs/ build systems.
 580
 581         ../olive/
 582
 583                 If the directory ../olive is present (as an
 584                 independent checkout) from the Mono module, that
 585                 directory is automatically configured to share the
 586                 same prefix than this module gets.
 587
 588