Factory functions¶

clr_loader.get_mono(*,config_file:str|PathLike|None=None,global_config_file:str|PathLike|None=None,libmono:str|PathLike|None=None,sgen:bool=True,debug:bool=False,jit_options:Sequence[str]|None=None,assembly_dir:str|None=None,config_dir:str|None=None,set_signal_chaining:bool=False)→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 tryto discover a globally installed instance usingfind_libmono()

• sgen – Iflibmono is not specified, this is passed tofind_libmono()

• debug – Whether to initialise Mono debugging

• jit_options – “Command line options” passed to Mono’smono_jit_parse_options

• assembly_dir – The base directory for assemblies, passed tomono_set_dirs

• config_dir – The base directory for configuration files, passed tomono_set_dirs

• set_signal_chaining –

  Whether to enable signal chaining, passed tomono_set_signal_chaining.If it is enabled, the runtime saves the original signal handlers beforeinstalling 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

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

Get a CoreCLR (.NET Core) runtime instance

The returnedDotnetCoreRuntime also acts as a mapping of the configproperties. They can be retrieved using the index operator and can bewritten until the runtime is initialized. The runtime is initialized whenthe first function object is retrieved.

Parameters:

• runtime_config – Pass to aruntimeconfig.json as generated bydotnetpublish. If this parameter is not given, a temporary runtimeconfig will be generated.

• dotnet_root – The root directory of the .NET Core installation. If this is notspecified, we try to discover it usingfind_dotnet_root().

• properties – Additional runtime properties. These can also be passed using theconfigProperties section in the runtime config.

• runtime_spec – If theruntime_config is not specified, the concrete runtime to usecan be controlled by passing this parameter. Possible values can beretrieved usingfind_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 beloaded into the root domain.

• config_file – Configuration file to use to initialize theAppDomain. This willonly be used for non-root-domains as we can not control theconfiguration of the implicitly loaded root domain.

Wrapper types¶

classclr_loader.Runtime¶

CLR Runtime

Encapsulates the lifetime of a CLR (.NET) runtime. If the instance isdeleted, 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 canbe loaded. Due to the design of the different hosting APIs, loading onlyhappens when the first function is referenced, and only then potentialerrors will be raised.

abstractinfo()→RuntimeInfo¶

Get configuration and version information

abstractshutdown()→None¶

Shut down the runtime as much as possible

Implementations should still be able to “reinitialize”, thus the finalcleanup will usually happen in anatexit handler.

classclr_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 bestatic, and it must have the signatureintFunc(IntPtrptr,intsize). The returned wrapped instance willtake abinary and call the .NET function with a pointer to thatbuffer and the buffer length. The buffer is reflected using CFFI’sfrom_buffer.

Parameters:

• name – Iffunc is not given, this is the fully qualified nameof the function. Iffunc is given, this is the fullyqualified name of the containing class

• func – Name of the function

Returns:

A function object that takes a singlebinary parameterand returns anint

Utilities¶

classclr_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 astr, 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:

classclr_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 variableDOTNET_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 thedotnet CLItool 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,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 isignored on Windows, as onlysgen is installed with the defaultinstaller

Returns:

Path to usablelibmono

clr_loader.find_runtimes()→Iterator[DotnetCoreRuntimeSpec]¶

Find installed .NET Core runtimes

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

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

Returns:

Iterable ofDotnetCoreRuntimeSpec objects