Difference between revisions of "Mono"

From WineHQ Wiki
Jump to: navigation, search
(remove the "runtime detection" section as it's no longer accurate and is redundant with the new install section)
(update test suite section to document the new test tools in 5.0)
Line 85: Line 85:
  
 
== Test Suite ==
 
== Test Suite ==
See http://www.mono-project.com/Testing first.
+
As of 5.0, Wine Mono includes a test shell which can run tests from Mono and a few of its own. In the future, it'd be nice to include tests from some of the .NET Core projects as well.
  
Running the Mono test suite on Wine is very important for fixing bugs (in Mono and in Wine), and I suspect that MS .NET hosted in Wine will also benefit from some of the fixes made for the Mono tests.
+
The tests can be built using "make tests" in the build tree or downloaded from https://dl.winehq.org/wine/wine-mono/. Currently, the .zip file can't be automatically build from the source tree, and there's no easy way to run the full test suite in Wine without a source tree. Distributing the tests in zip form was a last-minute decision in the 5.0.0 release.
  
The Mono build system has make targets for running tests, but using them on Windows or Wine requires building Mono with cygwin or doing strange things to the build system. To make this easier, the build script for wine-mono will create self-contained builds of the Mono test suite when run with the -t switch. These tests are located in directories named like tests-net_2_0.
+
To run the full test suite in Wine, use the "make test" target.
  
To run tests, run nunit-console.exe with the dll file containing the tests as an argument. For example, to run the System.Drawing tests:
+
To run the full test suite in Windows, use run-on-windows.bat.
  
wine nunit-console.exe System.Drawing_test_net_2_0.dll
+
Both of these methods use the -skip-list, -pass-list, and -fail-list command-line switches to skip certain unreliable tests and to determine which tests are expected to pass or fail. Since these are only tested on my own build machine, and even there they are unpredictable, expect some unexpected results.
  
You could also invoke nunit-console.exe using Mono, or on a Windows machine from a command prompt. NUnit is actually a general-purpose unit testing framework for .NET, which Mono happens to use, and it should work on any .NET impelementation.
+
Specific test names can be passed to run-tests.exe as arguments, for example:
 +
<pre>
 +
$ wine tests/run-tests.exe System.Drawing # run all System.Drawing tests
 +
$ wine tests/run-tests.exe x86.System.Drawing # run the tests only on x86
 +
$ wine tests/run-tests.exe MonoTests.System.Drawing.GraphicsTest:Dpi_556181 # run one specific test
 +
</pre>
  
You can use the /fixture or /run switches to run only a single related set or tests or a single test.
+
run-tests.exe can be used in the same way on native Linux Mono, or .NET on Windows. It can also be used with the native Mono inside a Mono build tree with the mono-env script:
 +
<pre>
 +
$ ./mono-env mono tests/run-tests.exe MonoTests.System.Drawing.GraphicsTest:Dpi_556181
 +
</pre>
  
Note that the tests are marked based on whether they are expected to work on various platforms, and running them in this way will include tests that are known not to work in Mono. One would have to use the /exclude switch to change this.
+
Note that this particular Mono environment is only intended for building Wine Mono components, and may not accurately reflect the state of upstream Mono.
 +
 
 +
Test source code can be found in tools/tests, mono/mono/tests, and mono/mcs/class/*/Test. See https://www.mono-project.com/community/contributing/test-suite/ for information on Mono's tests.
  
 
== Microsoft .NET ==
 
== Microsoft .NET ==

Revision as of 21:09, 19 April 2020

Mono is an open-source and cross-platform implementation of the .NET Framework. Wine can use a Windows build of Mono to run .NET applications.

Installing

From source

From a source tree, you can use the "make dev" target to build Wine Mono and configure the current Wine prefix (default or as set by the WINEPREFIX environment variable) to use the build. The "make dev-setup" target will just configure the Wine prefix without building.

Shared Install

For packagers, and users with multiple prefixes, a shared install is recommended.

To create a shared install, download the appropriate binary tarball from https://dl.winehq.org/wine/wine-mono/ (or build it from source with "make bin") and extract it to the appropriate location.

Wine will search for Wine Mono in the following places (replacing 5.0.0 with the expected version):

  • c:\windows\mono\mono-2.0. Extracting a tarball here is not recommended. If you want to install into a specific prefix, use the Prefix Local Install instructions below. It's only included in this list to make it clear that an installed .msi takes priority over the other loctions.
  • The directory specified in HKEY_CURRENT_USER\Software\Wine\Mono string value "RuntimePath".
  • ${prefix}/share/wine/mono/wine-mono-5.0.0 or ${builddir}/../mono/wine-mono-5.0.0
  • /usr/share/wine/mono/wine-mono-5.0.0
  • /opt/wine/mono/wine-mono-5.0.0


When using a shared install, The "Wine Mono Windows Support" package must still be installed in the prefix. This is handled automatically on prefix update, so normally it shouldn't be a problem, but in some corner cases you might have to run "wineboot -u" to set this up after creating the shared install.

Prefix Local Install

Wine will automatically download and install the appropriate Wine Mono MSI on prefix update, so this shouldn't usually be necessary.

If you wish to use a different MSI installer than the one you'd get automatically:

  • Obtain the MSI file you wish to use, either from https://dl.winehq.org/wine/wine-mono/ or by running "make msi" in a build tree. It's possible you already have the one you want in ~/.cache/wine.
  • Run "wine uninstaller" and remove "Wine Mono Runtime" and "Wine Mono Windows Support" if you have them.
  • Run "wine msiexec /i path/to/wine-mono.msi"

Old instructions

For Wine releases 1.5.3 and later, the Wine-Mono package is recommended. For earlier versions, an official Windows release of Mono 2.10 is recommended.

Wine 1.5.6 and later will install Wine-Mono automatically as needed. It will search for the MSI in the following locations:

  • The Unix directory stored in the "MonoCabDir" value at HKCU\Software\Wine\Dotnet.
  • /usr/share/wine/mono, or possibly some substitution for /usr if Wine was installed to a different location.
  • wine_build_directory/../mono, if Wine is being run from a build tree.
  • Download from http://dl.winehq.org/wine/wine-mono/.


Unlike gecko, there is only one package containing the code for both x86 and x86_64, as most of the code does not depend on the architecture.

The Mono package should always be removed before installing native .NET. This can be done with the following command-line:

$ wine uninstaller --remove '{E45D8920-A758-4088-B6C6-31DBB276992E}'

In a 64 bit wineprefix, substitute wine64 for wine in the above command

Building

For build instructions, see the readme at https://github.com/madewokherd/wine-mono

Debugging

As of Wine Mono 0.0.4, the WINE_MONO_TRACE environment variable may be set as follows to trace calls within Mono:

    all                  All assemblies
    none                 No assemblies
    program              Entry point assembly
    assembly             Specifies an assembly
    wrapper              All wrappers bridging native and managed code
    M:Type:Method        Specifies a method
    N:Namespace          Specifies a namespace
    T:Type               Specifies a type
    E:Type               Specifies stack traces for an exception type
    EXPR                 Includes expression
    -EXPR                Excludes expression
    EXPR,EXPR            Multiple expressions
    disabled             Don't print any output until toggled via SIGUSR2

This option is the same as the --trace option in Mono.

Note that "All assemblies" includes the program itself and all libraries shipped with it. Mono is capable of tracing any .NET code. You probably should avoid the "all" trace if there might be proprietary code running in the process.

Activating any trace at all, even a bogus assembly name, will cause Mono to print out all exceptions as they occur. This can be useful, but it can also be misleading as some exceptions are perfectly normal.

If you're not sure which libraries might be involved in a problem, and no exceptions are being raised, try WINE_MONO_TRACE=wrapper. It tends to be low-traffic while also containing useful information.

In earlier versions of Wine, the "MONO_TRACE" environment variable may work.

If you see "Stacktrace:" in the console, this means that Mono has crashed. To debug, set MONO_DEBUG=suspend-on-sigsegv. You will then see "Received SIGSEGV, suspending..." after the crash, and you can attach winedbg to the process.

Documentation

Standard .NET namespaces and classes are documented at MSDN here: http://msdn.microsoft.com/en-us/library/w0x726c2.aspx

Test Suite

As of 5.0, Wine Mono includes a test shell which can run tests from Mono and a few of its own. In the future, it'd be nice to include tests from some of the .NET Core projects as well.

The tests can be built using "make tests" in the build tree or downloaded from https://dl.winehq.org/wine/wine-mono/. Currently, the .zip file can't be automatically build from the source tree, and there's no easy way to run the full test suite in Wine without a source tree. Distributing the tests in zip form was a last-minute decision in the 5.0.0 release.

To run the full test suite in Wine, use the "make test" target.

To run the full test suite in Windows, use run-on-windows.bat.

Both of these methods use the -skip-list, -pass-list, and -fail-list command-line switches to skip certain unreliable tests and to determine which tests are expected to pass or fail. Since these are only tested on my own build machine, and even there they are unpredictable, expect some unexpected results.

Specific test names can be passed to run-tests.exe as arguments, for example:

$ wine tests/run-tests.exe System.Drawing # run all System.Drawing tests
$ wine tests/run-tests.exe x86.System.Drawing # run the tests only on x86
$ wine tests/run-tests.exe MonoTests.System.Drawing.GraphicsTest:Dpi_556181 # run one specific test

run-tests.exe can be used in the same way on native Linux Mono, or .NET on Windows. It can also be used with the native Mono inside a Mono build tree with the mono-env script:

$ ./mono-env mono tests/run-tests.exe MonoTests.System.Drawing.GraphicsTest:Dpi_556181

Note that this particular Mono environment is only intended for building Wine Mono components, and may not accurately reflect the state of upstream Mono.

Test source code can be found in tools/tests, mono/mono/tests, and mono/mcs/class/*/Test. See https://www.mono-project.com/community/contributing/test-suite/ for information on Mono's tests.

Microsoft .NET

If you need to use Microsoft's implementation of the .NET framework, the Microsoft runtimes can partly run on Wine. You can find tips and share comments with other users at the .NET AppDB page.

You can install the appropriate version of Microsoft's .NET runtime (dotnet35, dotnet30, dotnet20, or dotnet11) through winetricks. Be aware though, that your .NET application still might not work (at least not yet), and Microsoft's .NET runtimes are not free software so be sure to read the EULA before accepting. Mono, on the other hand, is free software, supported by a strong community, and probably a better choice if it works with your application.