## Embedding Mono

The simplest way of embedding Mono is illustrated here:

    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");
    }

mono_jit_init
Prototype: mono_jit_init

mono_jit_exec
int mono_jit_exec (MonoDomain *domain, MonoAssembly *assembly, int argc, char *argv[])

Parameters

> assembly:
>   reference to an assembly
> argc:
>   argument count
> argv:
>   argument vector

Remarks

Start execution of a program.

mono_set_dirs
void mono_set_dirs (const char *assembly_dir, const char *config_dir)

Parameters

> assembly_dir:
>   the base directory for assemblies
> config_dir:
>   the base directory for configuration files

Remarks

This routine is used internally and by developers embedding the runtime into their own applications. There are a number of cases to consider: Mono as a system-installed package that is available on the location preconfigured or Mono in a relocated location. If you are using a system-installed Mono, you can pass NULL to both parameters. If you are not, you should compute both directory values and call this routine. The values for a given PREFIX are: assembly_dir: PREFIX/lib config_dir: PREFIX/etc Notice that embedders that use Mono in a relocated way must compute the location at runtime, as they will be in control of where Mono is installed.

mono_main
int mono_main (int argc, char* argv[])

Parameters

> argc:
>   number of arguments in the argv array
> argv:
>   array of strings containing the startup arguments

Remarks

Launches the Mono JIT engine and parses all the command line options in the same way that the mono command line VM would.

mono_parse_default_optimizations
Prototype: mono_parse_default_optimizations

mono_jit_cleanup
Prototype: mono_jit_cleanup

mono_set_defaults
Prototype: mono_set_defaults

### Internal Calls

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.

The other option is to use the Platform Invoke (P/Invoke) to call C code from the CIL universe, using the standard P/Invoke mechanisms.

To register an internal call, use this call you use the `mono_add_internal_call` routine.

mono_add_internal_call
Prototype: mono_add_internal_call

### P/Invoke with embedded applications

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.

Usually P/Invoke declarations reference external libraries like:

    	[DllImport ("opengl")]
    	void glBegin (GLEnum mode)

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.

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 mono_dl_register_library.

#### mono_dl_register_library

### Data Marshalling

Managed objects are represented as `MonoObject*` types. Those objects that the runtime consumes directly have more specific C definitions (for example strings are of type `MonoString *`, delegates are of type `MonoDelegate*` but they are still `MonoObject *`s).

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.

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.

Important 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.

### Mono Runtime Configuration

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 `$sysconfig/mono/config` (typically this is `/etc/mono/config`).

See the `mono-config(5)` man page for more details on what goes in this file.

The following APIs expose this functionality:

mono_config_parse
void mono_config_parse (const char *filename)

Parameters

> filename:
>   the filename to load the configuration variables from.

Remarks

Pass a NULL filename to parse the default config files (or the file in the MONO_CONFIG env var).

mono_config_parse_memory
void mono_config_parse_memory (const char *buffer)

Parameters

> buffer:
>   a pointer to an string XML representation of the configuration

Remarks

Parses the configuration from a buffer

mono_get_config_dir
Prototype: mono_get_config_dir

### Function Pointers

To wrap a function pointer into something that the Mono runtime can consume, you should use the mono_create_ftnptr. This is only important if you plan on running on the IA64 architecture. Otherwise you can just use the function pointer address.

mono_create_ftnptr
Prototype: mono_create_ftnptr

### Advanced Execution Setups

These are not recommended ways of initializing Mono, they are done internally by mono_jit_init, but are here to explain what happens internally.

mono_runtime_exec_managed_code
void mono_runtime_exec_managed_code (MonoDomain *domain, MonoMainThreadFunc main_func, gpointer main_args)

Parameters

> domain:
>   Application domain
> main_func:
>   function to invoke from the execution thread
> main_args:
>   parameter to the main_func

Remarks

Launch a new thread to execute a function main_func is called back from the thread with main_args as the parameter. The callback function is expected to start Main() eventually. This function then waits for all managed threads to finish. It is not necesseray anymore to execute managed code in a subthread, so this function should not be used anymore by default: just execute the code and then call mono_thread_manage ().

mono_runtime_exec_main
Prototype: mono_runtime_exec_main

mono_init_from_assembly
MonoDomain* mono_init_from_assembly (const char *domain_name, const char *filename)

Parameters

> domain_name:
>   name to give to the initial domain
> filename:
>   filename to load on startup

Returns

> the initial domain.

Remarks

Used by the runtime, users should use mono_jit_init instead. Creates the initial application domain and initializes the mono_defaults structure. This function is guaranteed to not run any IL code. The runtime is initialized using the runtime version required by the provided executable. The version is determined by looking at the exe configuration file and the version PE field)

mono_init
MonoDomain* mono_init (const char *domain_name)

Returns

> the initial domain.

Remarks

Creates the initial application domain and initializes the mono_defaults structure. This function is guaranteed to not run any IL code. The runtime is initialized using the default runtime version.