docs/sources/mono-api-embedding.html

   1 <h2>Embedding Mono</h2>
   2
   3         <p>The simplest way of embedding Mono is illustrated here:
   4 <pre>
   5 int main (int argc, char *argv)
   6 {
   7         /*
   8          * Load the default Mono configuration file, this is needed
   9          * if you are planning on using the dllmaps defined on the
  10          * system configuration
  11          */
  12         mono_config_parse (NULL);
  13
  14         /*
  15          * mono_jit_init() creates a domain: each assembly is
  16          * loaded and run in a MonoDomain.
  17          */
  18         MonoDomain *domain = mono_jit_init ("startup.exe");
  19
  20         /*
  21          * Optionally, add an internal call that your startup.exe
  22          * code can call, this will bridge startup.exe to Mono
  23          */
  24         mono_add_internal_call ("Sample::GetMessage", getMessage);
  25
  26         /*
  27          * Open the executable, and run the Main method declared
  28          * in the executable
  29          */
  30         MonoAssembly *assembly = mono_domain_assembly_open (domain, "startup.exe");
  31
  32         if (!assembly)
  33                 exit (2);
  34         /*
  35          * mono_jit_exec() will run the Main() method in the assembly.
  36          * The return value needs to be looked up from
  37          * System.Environment.ExitCode.
  38          */
  39         mono_jit_exec (domain, assembly, argc, argv);
  40 }
  41
  42 /* The C# signature for this method is: string GetMessage () in class Sample */
  43 MonoString*
  44 getMessage ()
  45 {
  46         return mono_string_new (mono_domain_get (), "Hello, world");
  47 }
  48 </pre>
  49
  50 <h4><a name="api:mono_jit_init">mono_jit_init</a></h4>
  51 <h4><a name="api:mono_jit_parse_options">mono_jit_parse_options</a></h4>
  52 <h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
  53 <h4><a name="api:mono_set_dirs">mono_set_dirs</a></h4>
  54 <h4><a name="api:mono_parse_default_optimizations">mono_parse_default_optimizations</a></h4>
  55 <h4><a name="api:mono_runtime_set_main_args">mono_runtime_set_main_args</a></h4>
  56 <h4><a name="api:mono_jit_cleanup">mono_jit_cleanup</a></h4>
  57 <h4><a name="api:mono_jit_set_trace_options">mono_jit_set_trace_options</a></h4>
  58
  59
  60 <h3>Internal Calls</h3>
  61
  62         <p>The Mono runtime provides two mechanisms to expose C code
  63         to the CIL universe: internal calls and native C
  64         code. Internal calls are tightly integrated with the runtime,
  65         and have the least overhead, as they use the same data types
  66         that the runtime uses.
  67
  68         <p>The other option is to use the Platform Invoke (P/Invoke)
  69         to call C code from the CIL universe, using the standard
  70         <a href="http://www.mono-project.com/Interop_with_Native_Libraries">P/Invoke</a>
  71         mechanisms.
  72
  73         <p>To register an internal call, use this call you use the
  74         <a href="#api:mono_add_internal_call"><tt>mono_add_internal_call</tt>
  75         routine.
  76
  77 <h4><a name="api:mono_add_internal_call">mono_add_internal_call</a></h4>
  78
  79 <h3>P/Invoke with embedded applications</h3>
  80
  81         <p>Unlike internal calls, Platform/Invoke is easier to use and
  82         more portable.  It allows you to share code with Windows and
  83         .NET that have a different setup for internal calls to their
  84         own runtime.
  85
  86         <p>Usually P/Invoke declarations reference external libraries
  87         like:
  88
  89         <pre>
  90         [DllImport ("opengl")]
  91         void glBegin (GLEnum mode)
  92         </pre>
  93
  94         <p>Mono extends P/Invoke to support looking up symbols not in
  95         an external library, but looking up those symbols into the
  96         same address space as your program, to do this, use the
  97         special library name "__Internal".   This will direct Mono to
  98         lookup the method in your own process.
  99
 100         <p>There are situations where the host operating system does
 101         not support looking up symbols on the process address space.
 102         For situations like this you can use
 103         the <a href="#api:mono_dl_register_library">mono_dl_register_library</a>.
 104
 105 <h4><a name="api:mono_dl_register_library">mono_dl_register_library</h4>
 106
 107 <h3>Data Marshalling</h3>
 108
 109         <p>Managed objects are represented as <tt>MonoObject*</tt>
 110         types.  Those objects that the runtime consumes directly have
 111         more specific C definitions (for example strings are of type
 112         <tt>MonoString *</tt>, delegates are of type
 113         <tt>MonoDelegate*</tt> but they are still <tt>MonoObject
 114         *</tt>s).
 115
 116         <p>As of Mono 1.2.x types defined in mscorlib.dll do not have
 117         their fields reordered in any way.   But other libraries might
 118         have their fields reordered.   In these cases, Managed
 119         structures and objects have the same layout in the C# code as
 120         they do in the unmanaged world.
 121
 122         <p>Structures defined outside corlib must have a specific
 123         StructLayout definition, and have it set as sequential if you
 124         plan on accessing these fields directly from C code.
 125
 126         <p><b>Important</B> Internal calls do not provide support for
 127         marshalling structures.  This means that any API calls that
 128         take a structure (excluding the system types like int32,
 129         int64, etc) must be passed as a pointer, in C# this means
 130         passing the value as a "ref" or "out" parameter.
 131
 132 <h3>Mono Runtime Configuration</h3>
 133
 134         <p>Certain features of the Mono runtime, like DLL mapping, are
 135         available through a configuration file that is loaded at
 136         runtime.   The default Mono implementation loads the
 137         configuration file from <tt>$sysconfig/mono/config</tt>
 138         (typically this is <tt>/etc/mono/config</tt>).
 139
 140         <p>See the <tt>mono-config(5)</tt> man page for more details
 141         on what goes in this file.
 142
 143         <p>The following APIs expose this functionality:
 144
 145 <h4><a name="api:mono_config_cleanup">mono_config_cleanup</a></h4>
 146 <h4><a name="api:mono_config_is_server_mode">mono_config_is_server_mode</a></h4>
 147 <h4><a name="api:mono_config_parse">mono_config_parse</a></h4>
 148 <h4><a name="api:mono_config_parse_memory">mono_config_parse_memory</a></h4>
 149 <h4><a name="api:mono_config_set_server_mode">mono_config_set_server_mode</a></h4>
 150 <h4><a name="api:mono_config_string_for_assembly_file">mono_config_string_for_assembly_file</a></h4>
 151 <h4><a name="api:mono_get_config_dir">mono_get_config_dir</a></h4>
 152 <h4><a name="api:mono_get_machine_config">mono_get_machine_config</a></h4>
 153 <h4><a name="api:mono_register_machine_config">mono_register_machine_config</a></h4>
 154 <h4><a name="api:mono_set_config_dir">mono_set_config_dir</a></h4>
 155
 156 <h3>Advanced Execution Setups</h3>
 157
 158         <p>These are not recommended ways of initializing Mono, they
 159         are done internally by mono_jit_init, but are here to explain
 160         what happens internally.
 161
 162 <h4><a name="api:mono_runtime_exec_managed_code">mono_runtime_exec_managed_code</a></h4>
 163 <h4><a name="api:mono_runtime_exec_main">mono_runtime_exec_main</a></h4>
 164 <h4><a name="api:mono_init">mono_init</a></h4>
 165 <h4><a name="api:mono_init_from_assembly">mono_init_from_assembly</a></h4>
 166 <h4><a name="api:mono_init_version">mono_init_version</a></h4>
 167 <h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
 168 <h4><a name="api:mono_jit_set_aot_mode">mono_jit_set_aot_mode</a></h4>
 169 <h4><a name="api:mono_set_break_policy">mono_set_break_policy</a></h4>
 170 <h4><a name="api:mono_get_runtime_build_info">mono_get_runtime_build_info</a></h4>
 171
 172 <h3>Signal Chaining</h3>
 173
 174 <h4><a name="api:mono_set_signal_chaining">mono_set_signal_chaining</a></h4>
 175 <h4><a name="api:mono_set_crash_chaining">mono_set_crash_chaining</a></h4>