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