189 lines
7.1 KiB
HTML
189 lines
7.1 KiB
HTML
<h2>Embedding Mono</h2>
|
|
|
|
<p>The Mono runtime can be embedded into C and C++
|
|
applications. Your C/C++ code can invoke managed code
|
|
running in the Mono/.NET world and you can also surface your
|
|
internal application APIs to Mono and .NET.
|
|
|
|
<p>For an overview of how to embed Mono into your application
|
|
and the strategies that you can use to embed Mono, check the
|
|
Mono
|
|
website's <a href="http://www.mono-project.com/docs/advanced/embedding/">Embedding
|
|
Mono</a> page.
|
|
|
|
<p>This page is the companion API reference for the above guide.
|
|
|
|
<p>The simplest way of embedding Mono is illustrated here:
|
|
<pre>
|
|
int main (int argc, char *argv)
|
|
{
|
|
/*
|
|
* Load the default Mono configuration file, this is needed
|
|
* if you are planning on using the dllmaps defined on the
|
|
* system configuration
|
|
*/
|
|
mono_config_parse (NULL);
|
|
|
|
/*
|
|
* mono_jit_init() creates a domain: each assembly is
|
|
* loaded and run in a MonoDomain.
|
|
*/
|
|
MonoDomain *domain = mono_jit_init ("startup.exe");
|
|
|
|
/*
|
|
* Optionally, add an internal call that your startup.exe
|
|
* code can call, this will bridge startup.exe to Mono
|
|
*/
|
|
mono_add_internal_call ("Sample::GetMessage", getMessage);
|
|
|
|
/*
|
|
* Open the executable, and run the Main method declared
|
|
* in the executable
|
|
*/
|
|
MonoAssembly *assembly = mono_domain_assembly_open (domain, "startup.exe");
|
|
|
|
if (!assembly)
|
|
exit (2);
|
|
/*
|
|
* mono_jit_exec() will run the Main() method in the assembly.
|
|
* The return value needs to be looked up from
|
|
* System.Environment.ExitCode.
|
|
*/
|
|
mono_jit_exec (domain, assembly, argc, argv);
|
|
}
|
|
|
|
/* The C# signature for this method is: string GetMessage () in class Sample */
|
|
MonoString*
|
|
getMessage ()
|
|
{
|
|
return mono_string_new (mono_domain_get (), "Hello, world");
|
|
}
|
|
</pre>
|
|
|
|
<h4><a name="api:mono_jit_init">mono_jit_init</a></h4>
|
|
<h4><a name="api:mono_jit_parse_options">mono_jit_parse_options</a></h4>
|
|
<h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
|
|
<h4><a name="api:mono_set_dirs">mono_set_dirs</a></h4>
|
|
<h4><a name="api:mono_parse_default_optimizations">mono_parse_default_optimizations</a></h4>
|
|
<h4><a name="api:mono_runtime_set_main_args">mono_runtime_set_main_args</a></h4>
|
|
<h4><a name="api:mono_jit_cleanup">mono_jit_cleanup</a></h4>
|
|
<h4><a name="api:mono_jit_set_trace_options">mono_jit_set_trace_options</a></h4>
|
|
|
|
|
|
<h3>Internal Calls</h3>
|
|
|
|
<p>The Mono runtime provides two mechanisms to expose C code
|
|
to the CIL universe: internal calls and native C
|
|
code. Internal calls are tightly integrated with the runtime,
|
|
and have the least overhead, as they use the same data types
|
|
that the runtime uses.
|
|
|
|
<p>The other option is to use the Platform Invoke (P/Invoke)
|
|
to call C code from the CIL universe, using the standard
|
|
<a href="http://www.mono-project.com/Interop_with_Native_Libraries">P/Invoke</a>
|
|
mechanisms.
|
|
|
|
<p>To register an internal call, use this call you use the
|
|
<a href="#api:mono_add_internal_call"><tt>mono_add_internal_call</tt>
|
|
routine.
|
|
|
|
<h4><a name="api:mono_add_internal_call">mono_add_internal_call</a></h4>
|
|
|
|
<h3>P/Invoke with embedded applications</h3>
|
|
|
|
<p>Unlike internal calls, Platform/Invoke is easier to use and
|
|
more portable. It allows you to share code with Windows and
|
|
.NET that have a different setup for internal calls to their
|
|
own runtime.
|
|
|
|
<p>Usually P/Invoke declarations reference external libraries
|
|
like:
|
|
|
|
<pre>
|
|
[DllImport ("opengl")]
|
|
void glBegin (GLEnum mode)
|
|
</pre>
|
|
|
|
<p>Mono extends P/Invoke to support looking up symbols not in
|
|
an external library, but looking up those symbols into the
|
|
same address space as your program, to do this, use the
|
|
special library name "__Internal". This will direct Mono to
|
|
lookup the method in your own process.
|
|
|
|
<p>There are situations where the host operating system does
|
|
not support looking up symbols on the process address space.
|
|
For situations like this you can use
|
|
the <a href="#api:mono_dl_register_library">mono_dl_register_library</a>.
|
|
|
|
<h4><a name="api:mono_dl_register_library">mono_dl_register_library</h4>
|
|
|
|
<h3>Data Marshalling</h3>
|
|
|
|
<p>Managed objects are represented as <tt>MonoObject*</tt>
|
|
types. Those objects that the runtime consumes directly have
|
|
more specific C definitions (for example strings are of type
|
|
<tt>MonoString *</tt>, delegates are of type
|
|
<tt>MonoDelegate*</tt> but they are still <tt>MonoObject
|
|
*</tt>s).
|
|
|
|
<p>As of Mono 1.2.x types defined in mscorlib.dll do not have
|
|
their fields reordered in any way. But other libraries might
|
|
have their fields reordered. In these cases, Managed
|
|
structures and objects have the same layout in the C# code as
|
|
they do in the unmanaged world.
|
|
|
|
<p>Structures defined outside corlib must have a specific
|
|
StructLayout definition, and have it set as sequential if you
|
|
plan on accessing these fields directly from C code.
|
|
|
|
<p><b>Important</B> Internal calls do not provide support for
|
|
marshalling structures. This means that any API calls that
|
|
take a structure (excluding the system types like int32,
|
|
int64, etc) must be passed as a pointer, in C# this means
|
|
passing the value as a "ref" or "out" parameter.
|
|
|
|
<h3>Mono Runtime Configuration</h3>
|
|
|
|
<p>Certain features of the Mono runtime, like DLL mapping, are
|
|
available through a configuration file that is loaded at
|
|
runtime. The default Mono implementation loads the
|
|
configuration file from <tt>$sysconfig/mono/config</tt>
|
|
(typically this is <tt>/etc/mono/config</tt>).
|
|
|
|
<p>See the <tt>mono-config(5)</tt> man page for more details
|
|
on what goes in this file.
|
|
|
|
<p>The following APIs expose this functionality:
|
|
|
|
<h4><a name="api:mono_config_cleanup">mono_config_cleanup</a></h4>
|
|
<h4><a name="api:mono_config_is_server_mode">mono_config_is_server_mode</a></h4>
|
|
<h4><a name="api:mono_config_parse">mono_config_parse</a></h4>
|
|
<h4><a name="api:mono_config_parse_memory">mono_config_parse_memory</a></h4>
|
|
<h4><a name="api:mono_config_set_server_mode">mono_config_set_server_mode</a></h4>
|
|
<h4><a name="api:mono_config_string_for_assembly_file">mono_config_string_for_assembly_file</a></h4>
|
|
<h4><a name="api:mono_get_config_dir">mono_get_config_dir</a></h4>
|
|
<h4><a name="api:mono_get_machine_config">mono_get_machine_config</a></h4>
|
|
<h4><a name="api:mono_register_machine_config">mono_register_machine_config</a></h4>
|
|
<h4><a name="api:mono_set_config_dir">mono_set_config_dir</a></h4>
|
|
|
|
<h3>Advanced Execution Setups</h3>
|
|
|
|
<p>These are not recommended ways of initializing Mono, they
|
|
are done internally by mono_jit_init, but are here to explain
|
|
what happens internally.
|
|
|
|
<h4><a name="api:mono_runtime_exec_managed_code">mono_runtime_exec_managed_code</a></h4>
|
|
<h4><a name="api:mono_runtime_exec_main">mono_runtime_exec_main</a></h4>
|
|
<h4><a name="api:mono_init">mono_init</a></h4>
|
|
<h4><a name="api:mono_init_from_assembly">mono_init_from_assembly</a></h4>
|
|
<h4><a name="api:mono_init_version">mono_init_version</a></h4>
|
|
<h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
|
|
<h4><a name="api:mono_jit_set_aot_mode">mono_jit_set_aot_mode</a></h4>
|
|
<h4><a name="api:mono_set_break_policy">mono_set_break_policy</a></h4>
|
|
<h4><a name="api:mono_get_runtime_build_info">mono_get_runtime_build_info</a></h4>
|
|
|
|
<h3>Signal Chaining</h3>
|
|
|
|
<h4><a name="api:mono_set_signal_chaining">mono_set_signal_chaining</a></h4>
|
|
<h4><a name="api:mono_set_crash_chaining">mono_set_crash_chaining</a></h4>
|