Factory functions¶

clr_loader.get_mono(*, config_file: str | PathLike[str] | None = None, global_config_file: str | PathLike[str] | None = None, libmono: str | PathLike[str] | None = None, sgen: bool = True, debug: bool = False, jit_options: Sequence[str] | None = None, assembly_dir: str | PathLike[str] | None = None, config_dir: str | PathLike[str] | None = None, set_signal_chaining: bool = False, trace_mask: str | None = None, trace_level: str | None = None) → Runtime¶

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

• trace_mask – The Mono trace mask to use, passed to mono_trace_set_mask_string. For example, "all" enables all trace messages.

• trace_level – The minimum Mono trace level to log, passed to mono_trace_set_level_string. For example, "message" enables message-level logging and more severe messages.

clr_loader.get_coreclr(*, runtime_config: str | PathLike[str] | None = None, entry_dll: str | PathLike[str] | None = None, dotnet_root: str | PathLike[str] | None = None, properties: dict[str, str] | None = None, runtime_spec: DotnetCoreRuntimeSpec | None = None, runtime_version: str | None = None) → Runtime¶

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 – Path to a runtimeconfig.json as generated by dotnet publish. If this parameter is not given, a temporary runtime config will be generated.

• entry_dll – The path to the entry dll. If this parameter is given, the runtime will be initialized using the command line hosting API instead of using the runtime config.

• 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().

• runtime_version – If neither the runtime_config nor the runtime_spec are specified, the concrete runtime version to use can be controlled by passing the major.minor version to this parameter.

clr_loader.get_netfx(*, domain: str | None = None, config_file: str | PathLike[str] | 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[str]) → 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.

abstractmethod info() → RuntimeInfo¶

Get configuration and version information

abstractmethod 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[str])¶

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 | PathLike[str] | None = None, sgen: bool = True) → Path | None¶

Find a suitable libmono dynamic library

On Windows, we check the default installation directory. On macOS, we check Homebrew (with architecture awareness) and the framework. On Unix-like systems, we check Homebrew and system locations.

Parameters:

• assembly_dir – Optional directory to search for libmono

• 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