From 36fbacfe85d278427501305ac63f6e416db9b164 Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Tue, 14 Dec 2010 13:33:44 -0500 Subject: [PATCH] Add README2 --- README2 | 568 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 568 insertions(+) create mode 100644 README2 diff --git a/README2 b/README2 new file mode 100644 index 0000000000000..6d1033ac3a5b6 --- /dev/null +++ b/README2 @@ -0,0 +1,568 @@ + +This is Mono. + + 1. Installation + 2. Using Mono + 3. Directory Roadmap + +1. Compilation and Installation +=============================== + + a. Build Requirements + --------------------- + + To build Mono, you will need the following components: + + * pkg-config + + Available from: http://www.freedesktop.org/Software/pkgconfig + + * glib 2.4 + + Available from: http://www.gtk.org/ + + On Itanium, you must obtain libunwind: + + http://www.hpl.hp.com/research/linux/libunwind/download.php4 + + On Solaris, make sure that you used GNU tar to unpack this package, as + Solaris tar will not unpack this correctly, and you will get strange errors. + + On Solaris, make sure that you use the GNU toolchain to build the software. + + Optional dependencies: + + * libgdiplus + + If you want to get support for System.Drawing, you will need to get + Libgdiplus. + + * libzlib + + This library and the development headers are required for compression + file support in the 2.0 profile. + + b. Building the Software + ------------------------ + + If you obtained this package as an officially released tarball, + this is very simple, use configure and make: + + ./configure --prefix=/usr/local + make + make install + + Mono supports a JIT engine on x86, SPARC, SPARCv9, S/390, + S/390x, AMD64, ARM and PowerPC systems. + + If you obtained this as a snapshot, you will need an existing + Mono installation. To upgrade your installation, unpack both + mono and mcs: + + tar xzf mcs-XXXX.tar.gz + tar xzf mono-XXXX.tar.gz + mv mono-XXX mono + mv mcs-XXX mcs + cd mono + ./autogen.sh --prefix=/usr/local + make + + The Mono build system is silent for most compilation commands. + To enable a more verbose compile (for example, to pinpoint + problems in your makefiles or your system) pass the V=1 flag to make, like this: + + make V=1 + + + + c. Building the software from SVN + --------------------------------- + + If you are building the software from SVN, make sure that you + have up-to-date mcs and mono sources: + + svn co svn+ssh://USER@mono-cvs.ximian.com/source/trunk/mono + svn co svn+ssh://USER@mono-cvs.ximian.com/source/trunk/mcs + + Then, go into the mono directory, and configure: + + cd mono + ./autogen.sh --prefix=/usr/local + make + + For people with non-standard installations of the auto* utils and of + pkg-config (common on misconfigured OSX and windows boxes), you could get + an error like this: + + ./configure: line 19176: syntax error near unexpected token `PKG_CHECK_MODULES(BASE_DEPENDENCIES,' ... + + This means that you need to set the ACLOCAL_FLAGS environment var + when invoking autogen.sh, like this: + + ACLOCAL_FLAGS="-I $acprefix/share/aclocal" ./autogen.sh --prefix=/usr/loca + + where $acprefix is the prefix where aclocal has been installed. + + This will automatically go into the mcs/ tree and build the + binaries there. + + This assumes that you have a working mono installation, and that + there's a C# compiler named 'mcs', and a corresponding IL + runtime called 'mono'. You can use two make variables + EXTERNAL_MCS and EXTERNAL_RUNTIME to override these. e.g., you + can say + + make EXTERNAL_MCS=/foo/bar/mcs EXTERNAL_RUNTIME=/somewhere/else/mono + + If you don't have a working Mono installation + --------------------------------------------- + + If you don't have a working Mono installation, an obvious choice + is to install the latest released packages of 'mono' for your + distribution and running autogen.sh; make; make install in the + mono module directory. + + You can also try a slightly more risky approach: this may not work, + so start from the released tarball as detailed above. + + This works by first getting the latest version of the 'monolite' + distribution, which contains just enough to run the 'mcs' + compiler. You do this with: + + # Run the following line after ./autogen.sh + make get-monolite-latest + + This will download and automatically gunzip and untar the + tarball, and place the files appropriately so that you can then + just run: + + make EXTERNAL_MCS=${PWD}/mcs/class/lib/monolite/gmcs.exe + + And that will use the files downloaded by 'make get-monolite-latest. + + Testing and Installation + ------------------------ + + You can run (part of) the mono and mcs testsuites with the command: + + make check + + All tests should pass. + + If you want more extensive tests, including those that test the + class libraries, you need to re-run 'configure' with the + '--enable-nunit-tests' flag, and try + + make -k check + + Expect to find a few testsuite failures. As a sanity check, you + can compare the failures you got with + + http://go-mono.com/tests/displayTestResults.php + + You can now install mono with: + + make install + + Failure to follow these steps may result in a broken installation. + + d. Common Configuration Options + ------------------------------- + + The following are the configuration options that someone + building Mono might want to use: + + --with-sgen=yes,no + + Generational GC support: Used to enable or disable the + compilation of a Mono runtime with the SGen garbage collector. + + On platforms that support it, after building Mono, you + will have both a mono binary and a mono-sgen binary. + Mono uses Boehm, while mono-sgen uses the Simple + Generational GC. + + --with-gc=[boehm, included, sgen, none] + + Selects the default Boehm garbage collector engine to + use, the default is the "included" value. + + included: + This is the default value, and its + the most feature complete, it will allow Mono + to use typed allocations and support the + debugger. + + It is essentially a slightly modified Boehm GC + + boehm: + This is used to use a system-install Boehm GC, + it is useful to test new features available in + Boehm GC, but we do not recommend that people + use this, as it disables a few features. + + none: + Disables the inclusion of a garbage + collector. + + --with-tls=__thread,pthread + + Controls how Mono should access thread local storage, + pthread forces Mono to use the pthread APIs, while + __thread uses compiler-optimized access to it. + + Although __thread is faster, it requires support from + the compiler, kernel and libc. Old Linux systems do + not support with __thread. + + This value is typically pre-configured and there is no + need to set it, unless you are trying to debug a + problem. + + --with-sigaltstack=yes,no + + Experimental: Use at your own risk, it is known to + cause problems with garbage collection and is hard to + reproduce those bugs. + + This controls whether Mono will install a special + signal handler to handle stack overflows. If set to + "yes", it will turn stack overflows into the + StackOverflowException. Otherwise when a stack + overflow happens, your program will receive a + segmentation fault. + + The configure script will try to detect if your + operating system supports this. Some older Linux + systems do not support this feature, or you might want + to override the auto-detection. + + --with-static_mono=yes,no + + This controls whether `mono' should link against a + static library (libmono.a) or a shared library + (libmono.so). + + This defaults to yes, and will improve the performance + of the `mono' program. + + This only affects the `mono' binary, the shared + library libmono.so will always be produced for + developers that want to embed the runtime in their + application. + + --with-xen-opt=yes,no + + The default value for this is `yes', and it makes Mono + generate code which might be slightly slower on + average systems, but the resulting executable will run + faster under the Xen virtualization system. + + --with-large-heap=yes,no + + Enable support for GC heaps larger than 3GB. + + This value is set to `no' by default. + + --enable-small-config=yes,no + + Enable some tweaks to reduce memory usage and disk footprint at + the expense of some capabilities. Typically this means that the + number of threads that can be created is limited (256), that the + maxmimum heap size is also reduced (256 MB) and other such limitations + that still make mono useful, but more suitable to embedded devices + (like mobile phones). + + This value is set to `no' by default. + + --with-ikvm-native=yes,no + + Controls whether the IKVM JNI interface library is + built or not. This is used if you are planning on + using the IKVM Java Virtual machine with Mono. + + This defaults to `yes'. + + --with-profile4=yes,no + + Whether you want to build the 4.x profile libraries + and runtime. + + It defaults to `yes'. + + --with-moonlight=yes,no + + Whether you want to generate the Silverlight/Moonlight + libraries and toolchain in addition to the default + (1.1 and 2.0 APIs). + + This will produce the `smcs' compiler which will reference + the Silverlight modified assemblies (mscorlib.dll, + System.dll, System.Code.dll and System.Xml.Core.dll) and turn + on the LINQ extensions for the compiler. + + --with-libgdiplus=installed,sibling, + + This is used to configure where should Mono look for + libgdiplus when running the System.Drawing tests. + + It defaults to `installed', which means that the + library is available to Mono through the regular + system setup. + + `sibling' can be used to specify that a libgdiplus + that resides as a sibling of this directory (mono) + should be used. + + Or you can specify a path to a libgdiplus. + + --disable-shared-memory + + Use this option to disable the use of shared memory in + Mono (this is equivalent to setting the MONO_DISABLE_SHM + environment variable, although this removes the feature + completely). + + Disabling the shared memory support will disable certain + features like cross-process named mutexes. + + --enable-minimal=LIST + + Use this feature to specify optional runtime + components that you might not want to include. This + is only useful for developers embedding Mono that + require a subset of Mono functionality. + + The list is a comma-separated list of components that + should be removed, these are: + + aot: + Disables support for the Ahead of Time + compilation. + + attach: + Support for the Mono.Management assembly and the + VMAttach API (allowing code to be injected into + a target VM) + + com: + Disables COM support. + + debug: + Drop debugging support. + + decimal: + Disables support for System.Decimal. + + full_messages: + By default Mono comes with a full table + of messages for error codes. This feature + turns off uncommon error messages and reduces + the runtime size. + + generics: + Generics support. Disabling this will not + allow Mono to run any 2.0 libraries or + code that contains generics. + + jit: + Removes the JIT engine from the build, this reduces + the executable size, and requires that all code + executed by the virtual machine be compiled with + Full AOT before execution. + + large_code: + Disables support for large assemblies. + + logging: + Disables support for debug logging. + + pinvoke: + Support for Platform Invocation services, + disabling this will drop support for any + libraries using DllImport. + + portability: + Removes support for MONO_IOMAP, the environment + variables for simplifying porting applications that + are case-insensitive and that mix the Unix and Windows path separators. + + profiler: + Disables support for the default profiler. + + reflection_emit: + Drop System.Reflection.Emit support + + reflection_emit_save: + Drop support for saving dynamically created + assemblies (AssemblyBuilderAccess.Save) in + System.Reflection.Emit. + + shadow_copy: + Disables support for AppDomain's shadow copies + (you can disable this if you do not plan on + using appdomains). + + simd: + Disables support for the Mono.SIMD intrinsics + library. + + ssa: + Disables compilation for the SSA optimization + framework, and the various SSA-based + optimizations. + + --enable-llvm + --enable-loadedllvm + + This enables the use of LLVM as a code generation engine + for Mono. The LLVM code generator and optimizer will be + used instead of Mono's built-in code generator for both + Just in Time and Ahead of Time compilations. + + See the http://www.mono-project.com/Mono_LLVM for the + full details and up-to-date information on this feature. + + You will need to have an LLVM built that Mono can link + against, + + The --enable-loadedllvm variant will make the llvm backend + into a runtime-loadable module instead of linking it directly + into the main mono binary. + + --enable-big-arrays + + This enables the use arrays whose indexes are larger + than Int32.MaxValue. + + By default Mono has the same limitation as .NET on + Win32 and Win64 and limits array indexes to 32-bit + values (even on 64-bit systems). + + In certain scenarios where large arrays are required, + you can pass this flag and Mono will be built to + support 64-bit arrays. + + This is not the default as it breaks the C embedding + ABI that we have exposed through the Mono development + cycle. + + --enable-parallel-mark + + Use this option to enable the garbage collector to use + multiple CPUs to do its work. This helps performance + on multi-CPU machines as the work is divided across CPUS. + + This option is not currently the default as we have + not done much testing with Mono. + + --enable-dtrace + + On Solaris and MacOS X builds a version of the Mono + runtime that contains DTrace probes and can + participate in the system profiling using DTrace. + + + --disable-dev-random + + Mono uses /dev/random to obtain good random data for + any source that requires random numbers. If your + system does not support this, you might want to + disable it. + + There are a number of runtime options to control this + also, see the man page. + + --enable-nacl + + This configures the Mono compiler to generate code + suitable to be used by Google's Native Client: + + http://code.google.com/p/nativeclient/ + + Currently this is used with Mono's AOT engine as + Native Client does not support JIT engines yet. + +2. Using Mono +============= + + Once you have installed the software, you can run a few programs: + + * runtime engine + + mono program.exe + + * C# compiler + + mcs program.cs + + * CIL Disassembler + + monodis program.exe + + See the man pages for mono(1), mint(1), monodis(1) and mcs(2) + for further details. + +3. Directory Roadmap +==================== + + docs/ + Technical documents about the Mono runtime. + + data/ + Configuration files installed as part of the Mono runtime. + + mono/ + The core of the Mono Runtime. + + metadata/ + The object system and metadata reader. + + mini/ + The Just in Time Compiler. + + dis/ + CIL executable Disassembler + + cli/ + Common code for the JIT and the interpreter. + + io-layer/ + The I/O layer and system abstraction for + emulating the .NET IO model. + + cil/ + Common Intermediate Representation, XML + definition of the CIL bytecodes. + + interp/ + Interpreter for CLI executables (obsolete). + + arch/ + Architecture specific portions. + + man/ + + Manual pages for the various Mono commands and programs. + + samples/ + + Some simple sample programs on uses of the Mono + runtime as an embedded library. + + scripts/ + + Scripts used to invoke Mono and the corresponding program. + + runtime/ + + A directory that contains the Makefiles that link the + mono/ and mcs/ build systems. + + ../olive/ + + If the directory ../olive is present (as an + independent checkout) from the Mono module, that + directory is automatically configured to share the + same prefix than this module gets. +