Reference¶

Factory functions¶

Get a Mono runtime instance

Parameters:

config_file – Path to the domain configuration file
global_config_file – Path to the global configuration file to load (defaults to, e.g., /etc/mono/config)
libmono – Path to the Mono runtime dll/so/dylib. If this is not specified, we try to discover a globally installed instance using find_libmono()
sgen – If libmono is not specified, this is passed to find_libmono()
debug – Whether to initialise Mono debugging
jit_options – “Command line options” passed to Mono’s mono_jit_parse_options
assembly_dir – The base directory for assemblies, passed to mono_set_dirs
config_dir – The base directory for configuration files, passed to mono_set_dirs
set_signal_chaining –
Whether to enable signal chaining, passed to mono_set_signal_chaining. If it is enabled, the runtime saves the original signal handlers before installing its own, and calls the original ones in the following cases:
- SIGSEGV/SIGABRT while executing native code
- SIGPROF
- SIGFPE
- SIGQUIT
- SIGUSR2
This currently only works on POSIX platforms

Get a CoreCLR (.NET Core) runtime instance

The returned DotnetCoreRuntime also acts as a mapping of the config properties. They can be retrieved using the index operator and can be written until the runtime is initialized. The runtime is initialized when the first function object is retrieved.

Parameters:

runtime_config – Pass to a runtimeconfig.json as generated by dotnet publish. If this parameter is not given, a temporary runtime config will be generated.
dotnet_root – The root directory of the .NET Core installation. If this is not specified, we try to discover it using find_dotnet_root().
properties – Additional runtime properties. These can also be passed using the configProperties section in the runtime config.
runtime_spec – If the runtime_config is not specified, the concrete runtime to use can be controlled by passing this parameter. Possible values can be retrieved using find_runtimes().

clr_loader.get_netfx(*, domain: str | None = None, config_file: str | PathLike | None = None) → Runtime¶

Get a .NET Framework runtime instance

Parameters:

domain – Name of the domain to create. If no value is passed, assemblies will be loaded into the root domain.
config_file – Configuration file to use to initialize the AppDomain. This will only be used for non-root-domains as we can not control the configuration of the implicitly loaded root domain.

Wrapper types¶

class clr_loader.Runtime¶

CLR Runtime

Encapsulates the lifetime of a CLR (.NET) runtime. If the instance is deleted, the runtime will be shut down.

get_assembly(assembly_path: str | PathLike) → Assembly¶

Get an assembly wrapper

This function does not guarantee that the respective assembly is or can be loaded. Due to the design of the different hosting APIs, loading only happens when the first function is referenced, and only then potential errors will be raised.

abstract info() → RuntimeInfo¶: Get configuration and version information

abstract shutdown() → None¶

Shut down the runtime as much as possible

Implementations should still be able to “reinitialize”, thus the final cleanup will usually happen in an atexit handler.

class clr_loader.Assembly(runtime: Runtime, path: str | PathLike)¶

get_function(name: str, func: str | None = None) → ClrFunction¶

Get a wrapped .NET function instance

The function must be static, and it must have the signature int Func(IntPtr ptr, int size). The returned wrapped instance will take a binary and call the .NET function with a pointer to that buffer and the buffer length. The buffer is reflected using CFFI’s from_buffer.

Parameters:

name – If func is not given, this is the fully qualified name of the function. If func is given, this is the fully qualified name of the containing class
func – Name of the function

Returns:

A function object that takes a single binary parameter and returns an int

Utilities¶

class clr_loader.RuntimeInfo(kind: str, version: str, initialized: bool, shutdown: bool, properties: Dict[str, str])¶

Information on a Runtime instance

An informative text can be retrieved from this by converting it to a str, in particular the following results in readable debug information:

>>> ri = RuntimeInfo()
>>> print(ri)
6.12.0.122 (tarball)
Runtime: Mono
=============
  Version:      6.12.0.122 (tarball)
  Initialized:  True
  Shut down:    False
  Properties:

class clr_loader.DotnetCoreRuntimeSpec(name: str, version: str, path: Path)¶: Specification of an installed .NET Core runtime

clr_loader.find_dotnet_root() → Path¶

Try to discover the .NET Core root directory

If the environment variable DOTNET_ROOT is defined, we will use that. Otherwise, we probe the default installation paths on Windows and macOS.

If none of these lead to a result, we try to discover the dotnet CLI tool and use its (real) parent directory.

Otherwise, this function raises an exception.

Returns:: Path to the .NET Core root

clr_loader.find_libmono(*, assembly_dir: str | None = None, sgen: bool = True) → Path¶

Find a suitable libmono dynamic library

On Windows and macOS, we check the default installation directories.

Parameters:: sgen – Whether to look for an SGen or Boehm GC instance. This parameter is ignored on Windows, as only sgen is installed with the default installer
Returns:: Path to usable libmono

clr_loader.find_runtimes() → Iterator[DotnetCoreRuntimeSpec]¶

Find installed .NET Core runtimes

If the dotnet CLI can be found, we will call it as dotnet --list-runtimes and parse the result.

If it is not available, we try to discover the dotnet root directory using find_dotnet_root() and enumerate the runtimes installed in the shared subdirectory.

Returns:: Iterable of DotnetCoreRuntimeSpec objects