Properly initialize a rgctx template. Fixes bxc #1147.
[mono-project.git] / README
blobd57aef26d8aa35567e313858ffbb0387adda2173
2 This is Mono.
4         1. Installation
5         2. Using Mono
6         3. Directory Roadmap
8 1. Compilation and Installation
9 ===============================
11    a. Build Requirements
12    ---------------------
14         On Itanium, you must obtain libunwind:
16                 http://www.hpl.hp.com/research/linux/libunwind/download.php4
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.
21         On Solaris, make sure that you use the GNU toolchain to build the software.
23         Optional dependencies:
25                 * libgdiplus
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:
30                         * pkg-config
32                           Available from: http://www.freedesktop.org/Software/pkgconfig
34                         * glib 2.4
36                           Available from: http://www.gtk.org/
38                 * libzlib
40                   This library and the development headers are required for compression
41                   file support in the 2.0 profile.
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:
49                 ./configure --prefix=/usr/local
50                 make
51                 make install
53         Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390,
54         S/390x, AMD64, ARM and PowerPC systems.   
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:
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
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:
72                  make V=1
75     c. Building the software from GIT
76     ---------------------------------
78         If you are building the software from GIT, make sure that you
79         have up-to-date mcs and mono sources:
81            If you are an anonymous user:
82                 git clone git://github.com/mono/mono.git
84            If you are a Mono contributors with read/write privileges:
85                 git clone git@github.com:mono/mono.git
88         Then, go into the mono directory, and configure:
90                 cd mono
91                 ./autogen.sh --prefix=/usr/local
92                 make
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:
98         ./configure: line 19176: syntax error near unexpected token `PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ...
100         This means that you need to set the ACLOCAL_FLAGS environment var
101         when invoking autogen.sh, like this:
103                 ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/loca
104         
105         where $acprefix is the prefix where aclocal has been installed.
107         This will automatically go into the mcs/ tree and build the
108         binaries there.
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
116           make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
117         
118         If you don't have a working Mono installation
119         ---------------------------------------------
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.
126         You can also try a slightly more risky approach: this may not work,
127         so start from the released tarball as detailed above.
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:
133                 # Run the following line after ./autogen.sh
134                 make get-monolite-latest
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:
140                 make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/gmcs.exe
142         And that will use the files downloaded by 'make get-monolite-latest.
144         Testing and Installation
145         ------------------------
147         You can run (part of) the mono and mcs testsuites with the command:
149                 make check
151         All tests should pass.  
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
157                 make -k check
159         Expect to find a few testsuite failures.  As a sanity check, you
160         can compare the failures you got with
162                 http://go-mono.com/tests/displayTestResults.php
164         You can now install mono with:
166                 make install
168         You can verify your installation by using the mono-test-install
169         script, it can diagnose some common problems with Mono's install.
171         Failure to follow these steps may result in a broken installation. 
173     d. Configuration Options
174     ------------------------
176         The following are the configuration options that someone
177         building Mono might want to use:
178         
179         --with-sgen=yes,no
181                 Generational GC support: Used to enable or disable the
182                 compilation of a Mono runtime with the SGen garbage collector.
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.
189         --with-gc=[boehm, included, sgen, none]
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.
200                         It is essentially a slightly modified Boehm GC
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.
208                 none:
209                         Disables the inclusion of a garbage
210                         collector.  
212         --with-tls=__thread,pthread
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.
218                 Although __thread is faster, it requires support from
219                 the compiler, kernel and libc.   Old Linux systems do
220                 not support with __thread.
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.
226         --with-sigaltstack=yes,no
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.
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.
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.
244         --with-static_mono=yes,no
246                 This controls whether `mono' should link against a
247                 static library (libmono.a) or a shared library
248                 (libmono.so). 
250                 This defaults to yes, and will improve the performance
251                 of the `mono' program. 
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.
258         --with-xen-opt=yes,no
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.
265         --with-large-heap=yes,no
267                 Enable support for GC heaps larger than 3GB.
269                 This value is set to `no' by default.
271         --enable-small-config=yes,no
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).
280                 This value is set to `no' by default.
282         --with-ikvm-native=yes,no
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.
288                 This defaults to `yes'.
290         --with-profile4=yes,no
292                 Whether you want to build the 4.x profile libraries
293                 and runtime.
295                 It defaults to `yes'.
297         --with-moonlight=yes,no
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).
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.
308         --with-moon-gc=boehm,sgen
310                 Select the GC to use for Moonlight.
312                 boehm:
313                         Selects the Boehm Garbage Collector, with the same flags
314                         as the regular Mono build. This is the default.
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.
321                 This defaults to `boehm'.
323         --with-libgdiplus=installed,sibling,<path>
325                 This is used to configure where should Mono look for
326                 libgdiplus when running the System.Drawing tests.
328                 It defaults to `installed', which means that the
329                 library is available to Mono through the regular
330                 system setup.
332                 `sibling' can be used to specify that a libgdiplus
333                 that resides as a sibling of this directory (mono)
334                 should be used.
336                 Or you can specify a path to a libgdiplus.
338         --disable-shared-memory 
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).
345                 Disabling the shared memory support will disable certain
346                 features like cross-process named mutexes.
348         --enable-minimal=LIST
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.
355                 The list is a comma-separated list of components that
356                 should be removed, these are:
358                 aot:
359                         Disables support for the Ahead of Time
360                         compilation.
362                 attach:
363                         Support for the Mono.Management assembly and the
364                         VMAttach API (allowing code to be injected into
365                         a target VM)
367                 com:
368                         Disables COM support.
370                 debug:
371                         Drop debugging support.
373                 decimal:
374                         Disables support for System.Decimal.
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.
382                 generics:
383                         Generics support.  Disabling this will not
384                         allow Mono to run any 2.0 libraries or
385                         code that contains generics.
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.
393                 large_code:
394                         Disables support for large assemblies.
396                 logging:
397                         Disables support for debug logging.
399                 pinvoke:
400                         Support for Platform Invocation services,
401                         disabling this will drop support for any
402                         libraries using DllImport.
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.
409                 profiler:
410                         Disables support for the default profiler.
412                 reflection_emit:
413                         Drop System.Reflection.Emit support
415                 reflection_emit_save:
416                         Drop support for saving dynamically created
417                         assemblies (AssemblyBuilderAccess.Save) in
418                         System.Reflection.Emit.
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).
425                 simd:
426                         Disables support for the Mono.SIMD intrinsics
427                         library.
429                 ssa:
430                         Disables compilation for the SSA optimization
431                         framework, and the various SSA-based
432                         optimizations.
434         --enable-llvm
435         --enable-loadedllvm
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.
442                 See the http://www.mono-project.com/Mono_LLVM for the 
443                 full details and up-to-date information on this feature.
445                 You will need to have an LLVM built that Mono can link
446                 against,
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.
452         --enable-big-arrays
454                 This enables the use arrays whose indexes are larger
455                 than Int32.MaxValue.   
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).
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.
465                 This is not the default as it breaks the C embedding
466                 ABI that we have exposed through the Mono development
467                 cycle.
469         --enable-parallel-mark
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.
475                 This option is not currently the default as we have
476                 not done much testing with Mono.
478         --enable-dtrace
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.
485         --disable-dev-random
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.
492                 There are a number of runtime options to control this
493                 also, see the man page.
495         --enable-nacl
497                 This configures the Mono compiler to generate code
498                 suitable to be used by Google's Native Client:
500                          http://code.google.com/p/nativeclient/
502                 Currently this is used with Mono's AOT engine as
503                 Native Client does not support JIT engines yet.
505 2. Using Mono
506 =============
508         Once you have installed the software, you can run a few programs:
510         * runtime engine
512                 mono program.exe
514         * C# compiler
516                 mcs program.cs
518         * CIL Disassembler
520                 monodis program.exe
522         See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
523         for further details.
525 3. Directory Roadmap
526 ====================
528         docs/
529                 Technical documents about the Mono runtime.
531         data/
532                 Configuration files installed as part of the Mono runtime.
534         mono/
535                 The core of the Mono Runtime.
537                 metadata/
538                         The object system and metadata reader.
540                 mini/
541                         The Just in Time Compiler.
543                 dis/
544                         CIL executable Disassembler
546                 cli/
547                         Common code for the JIT and the interpreter.
549                 io-layer/
550                         The I/O layer and system abstraction for 
551                         emulating the .NET IO model.
553                 cil/
554                         Common Intermediate Representation, XML
555                         definition of the CIL bytecodes.
557                 interp/
558                         Interpreter for CLI executables (obsolete).
560                 arch/
561                         Architecture specific portions.
563         man/
565                 Manual pages for the various Mono commands and programs.
567         samples/
569                 Some simple sample programs on uses of the Mono
570                 runtime as an embedded library.   
572         scripts/
574                 Scripts used to invoke Mono and the corresponding program.
576         runtime/
578                 A directory that contains the Makefiles that link the
579                 mono/ and mcs/ build systems.
581         ../olive/
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.