2007-01-01 Miguel de Icaza <miguel@novell.com>
[mono-project.git] / man / mono-config.5
blob48a099e474bda26ea9051de9b2a3ee50115f88b3
1 .\" 
2 .\" mono-config configuration page.
3 .\" (C) Ximian, Inc. 
4 .\" Author:
5 .\"   Miguel de Icaza (miguel@gnu.org)
6 .\"   Paolo Molaro (lupus@ximian.com)
7 .\"
8 .TH Mono "Mono 1.0"
9 .SH NAME
10 mono-config \- Mono runtime file format configuration
11 .SH DESCRIPTION
12 The Mono runtime will load configuration data from the
13 installation prefix /etc/mono/config file, the ~/.mono/config or from
14 the file pointed by the MONO_CONFIG environment variable.
15 .PP
16 For each assembly loaded a config file with the name:
17 /path/to/the/assembly.exe.config is loaded as well as the
18 ~/.mono/assemblies/ASSEMBLY/ASSEMBLY.EXT.config file. 
19 .PP
20 This file controls the behavior of the runtime.
21 .PP
22 The file contains an XML-like file with various sections, all of them
23 contained inside a 
24 .B<configuration> 
25 section (It actually uses GMarkup
26 to parse the file).
27 .PP
28 This page describes the Unix-specific and Mono-specific extensions to
29 the configuration file;   For complete details, see the
30 http://www.mono-project.com/Config web page.
31 .SH <dllmap> directive
32 You use the dllmap directive to map shared libraries referenced by
33 P/Invoke in your assemblies to a different shared library.
34 .PP
35 This is typically used to map Windows libraries to Unix library names.
36 The 
37 .B dllmap
38 element takes two attributes:
39 .TP
40 .I dll
41 This should be the same string used in the DllImport attribute
42 .TP
43 .I target
44 This should be the name of the library where the function can be found: 
45 this name should be suitable for use with the platform native shared library 
46 loading routines (dlopen etc.), so you may want to check the manpages for that, too.
47 .SH <dllentry> directive
48 This directive can be used to map a specific dll/function pair to a different
49 library and also a different function name. It should appear inside a
50 .B dllmap
51 element with only the dll attribute specified.
52 .PP
53 The
54 .B dllentry
55 element takes 3 attributes:
56 .TP
57 .I dll
58 This is the target library, where the function can be found.
59 .TP
60 .I name
61 This is the name of the fuction as it appears in the metadata: it is the name 
62 of the P/Invoke method.
63 .TP
64 .I target
65 This is the name of the function to lookup instead of the name specified in the 
66 P/Invoke method.
67 .SH Mapping based on operating system and cpu
68 Both the
69 .B dllmap
70 and the
71 .B dllentry
72 elements allow the following two attributes which make it easy to use a single
73 configuration file and support multiple operating systems and architectures with
74 different mapping requirements:
75 .TP
76 .I os
77 This is the name of the operating system for which the mapping should be applied.
78 Allowed values are: linux, osx, solaris, freebsd, openbsd, netbsd, windows, aix, hpux.
79 .TP
80 .I cpu
81 This is the name of the architecture for which the mapping should be applied.
82 Allowed values are: x86, x86-64, sparc, ppc, s390, s390x, arm, mips, alpha, hppa, ia64.
83 .PP
84 The attribute value for both attributes can be a comma-separated list of the allowed
85 values. Additionally, the first character may be a
86 .I '!'
87 to reverse the meaning. An attribute value of "!windows,osx", for example, would mean
88 that the entry is considered on all operating systems, except on Windows and OS X.
89 No spaces are allowed in any part of the value.
90 .PP
91 Note that later entries will override the entries defined earlier in the file.
92 .SH EXAMPLES
93 The following example maps references to the `cygwin1.dll' shared
94 library to the `libc.so.6' file.  
95 .nf
96 <configuration>
97         <dllmap dll="cygwin1.dll" target="libc.so.6"/>
98 </configuration>
99 .fi
101 This one maps the following C# method:
103         [DllImport ("libc")]
104         static extern void somefunction ();
107 .B differentfunction
109 .B libdifferent.so
110 , but to the same function in the library
111 .B libanother.so
112 when running under the Solaris and FreeBSD operating systems.
114 <configuration>
115         <dllmap dll="libc">
116                 <dllentry dll="libdifferent.so" name="somefunction" target="differentfunction" />
117                 <dllentry os="solaris,freebsd" dll="libanother.so" name="somefunction" target="differentfunction" />
118         </dllmap>
119 </configuration>
122 .SH SEE ALSO
123 .BR mono(1), monodis(1), mint(1)