Add a runburg command that will be executed after monoburg is built by visual studio...
[mono-project.git] / README
blob1cc99950c1cd2d1ee26dc93272760d25bfc8498c
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         To build Mono, you will need the following components:
16                 * pkg-config
18                   Available from: http://www.freedesktop.org/Software/pkgconfig
20                 * glib 2.4
22                   Available from: http://www.gtk.org/
24         On Itanium, you must obtain libunwind:
26                 http://www.hpl.hp.com/research/linux/libunwind/download.php4
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.
31         On Solaris, make sure that you use the GNU toolchain to build the software.
33         Optional dependencies:
35                 * libgdiplus
37                   If you want to get support for System.Drawing, you will need to get
38                   Libgdiplus.
40                 * libzlib
42                   This library and the development headers are required for compression
43                   file support in the 2.0 profile.
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:
51                 ./configure --prefix=/usr/local
52                 make
53                 make install
55         Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390, AMD64, ARM
56         and PowerPC systems.
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:
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
70     c. Building the software from SVN
71     ---------------------------------
73         If you are building the software from SVN, make sure that you
74         have up-to-date mcs and mono sources:
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
79         Then, go into the mono directory, and configure:
81                 cd mono
82                 ./autogen.sh --prefix=/usr/local
83                 make
85         This will automatically go into the mcs/ tree and build the
86         binaries there.
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
94           make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono
95         
96         If you don't have a working Mono installation
97         ---------------------------------------------
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.
104         You can also try a slightly more risky approach: this may not work,
105         so start from the released tarball as detailed above.
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:
111                 make get-monolite-latest
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:
117                 make
119         To ensure that you're using the 'monolite' distribution, you can
120         also try passing EXTERNAL_MCS=false on the make command-line.
122         Testing and Installation
123          ------------------------
125         You can run (part of) the mono and mcs testsuites with the command:
127                 make check
129         All tests should pass.  
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
135                 make -k check
137         Expect to find a few testsuite failures.  As a sanity check, you
138         can compare the failures you got with
140                 http://go-mono.com/tests/displayTestResults.php
142         You can now install mono with:
144                 make install
146         Failure to follow these steps may result in a broken installation. 
148     d. Common Configuration Options
149     -------------------------------
151         The following are the configuration options that someone
152         building Mono might want to use:
153         
155         --with-gc=[boehm, included, sgen, none]
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.
166                         It is essentially a slightly modified Boehm GC
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.
174                 sgen:
175                         The under-development Generational GC for
176                         Mono, do not use this in production.
178                 none:
179                         Disables the inclusion of a garbage
180                         collector.  
182         --with-tls=__thread,pthread
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.
188                 Although __thread is faster, it requires support from
189                 the compiler, kernel and libc.   Old Linux systems do
190                 not support with __thread.
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.
196         --with-sigaltstack=yes,no
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.
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.
210         --with-static-mono=yes,no
212                 This controls whether `mono' should link against a
213                 static library (libmono.a) or a shared library
214                 (libmono.so). 
216                 This defaults to yes, and will improve the performance
217                 of the `mono' program. 
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.
224         --with-xen-opt=yes,no
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.
231         --with-large-heap=yes,no
233                 Enable support for GC heaps larger than 3GB.
235                 This value is set to `no' by default.
237         --with-ikvm-native=yes,no
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.
243                 This defaults to `yes'.
245         --with-preview=yes,no
247                 Whether you want to build libraries that are still not
248                 completed (The 2.0 APIs).   It defaults to `yes'.
250         --with-libgdiplus=installed,sibling,<path>
252                 This is used to configure where should Mono look for
253                 libgdiplus when running the System.Drawing tests.
255                 It defaults to `installed', which means that the
256                 library is available to Mono through the regular
257                 system setup.
259                 `sibling' can be used to specify that a libgdiplus
260                 that resides as a sibling of this directory (mono)
261                 should be used.
263                 Or you can specify a path to a libgdiplus.
265         --enable-minimal=LIST
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.
272                 The list is a comma-separated list of components that
273                 should be removed, these are:
275                 aot:
276                         Disables support for the Ahead of Time
277                         compilation.
279                 profiler:
280                         Disables support for the default profiler.
282                 decimal:
283                         Disables support for System.Decimal.
285                 pinvoke:
286                         Support for Platform Invocation services,
287                         disabling this will drop support for any
288                         libraries using DllImport.
290                 debug:
291                         Drop debugging support.
293                 reflection_emit:
294                         Drop System.Reflection.Emit support
296                 large_code:
297                         Disables support for large assemblies.
299                 logging:
300                         Disables support for debug logging.
302                 com:
303                         Disables COM support.
305                 ssa:
306                         Disables compilation for the SSA optimization
307                         framework, and the various SSA-based
308                         optimizations.
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
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.
322                 There are a number of runtime options to control this
323                 also, see the man page.
326 2. Using Mono
327 =============
329         Once you have installed the software, you can run a few programs:
331         * runtime engine
333                 mono program.exe
335         * C# compiler
337                 mcs program.cs
339         * CIL Disassembler
341                 monodis program.exe
343         See the man pages for mono(1), mint(1), monodis(1) and mcs(2)
344         for further details.
346 3. Directory Roadmap
347 ====================
349         docs/
350                 Technical documents about the Mono runtime.
352         data/
353                 Configuration files installed as part of the Mono runtime.
355         mono/
356                 The core of the Mono Runtime.
358                 metadata/
359                         The object system and metadata reader.
361                 mini/
362                         The Just in Time Compiler.
364                 dis/
365                         CIL executable Disassembler
367                 cli/
368                         Common code for the JIT and the interpreter.
370                 io-layer/
371                         The I/O layer and system abstraction for 
372                         emulating the .NET IO model.
374                 cil/
375                         Common Intermediate Representation, XML
376                         definition of the CIL bytecodes.
378                 interp/
379                         Interpreter for CLI executables (obsolete).
381                 arch/
382                         Architecture specific portions.
384         man/
386                 Manual pages for the various Mono commands and programs.
388         scripts/
390                 Scripts used to invoke Mono and the corresponding program.
392         runtime/
394                 A directory that contains the Makefiles that link the
395                 mono/ and mcs/ build systems.