Compiling Mono on Windows
To build Mono on Windows, a Cygwin setup is required. You’ll also need Visual Studio 2015 or Visual Studio 2015 Build Tools for command line builds. Visual Studio 2017 is also supported.
NOTE, below instructions apply to Cygwin. If WSL (Windows Subsystem for Linux) is used instead of Cygwin, corresponding packages needs to be installed into WSL environment.
It is possible to build Mono runtime and BCL using Visual Studio without any prerequisites on Cygwin or WSL environment, see build Mono without Cygwin or WSL for details.
NOTE, for full build and execution of tests, a Cygwin environment is still needed as outlined below.
Install prerequisites
- Enable
Developer Mode
in the Windows 10 Settings app (Update & Security -> For developers tab) - Download and install 64 bit Cygwin from www.cygwin.com.
- Install Visual Studio 2015 or later - Community Edition works fine.
- Download and install Mono for Windows or use
monolite
build step as described below. - Run the following command in cmd.exe to install Cygwin and required packages:
setup-x86_64.exe -P autoconf,automake,bison,gcc-core,gcc-g++,mingw64-i686-runtime,mingw64-i686-binutils,mingw64-i686-gcc-core,mingw64-i686-gcc-g++,mingw64-i686-pthreads,mingw64-i686-w32api,mingw64-x86_64-runtime,mingw64-x86_64-binutils,mingw64-x86_64-gcc-core,mingw64-x86_64-gcc-g++,mingw64-x86_64-pthreads,mingw64-x86_64-w32api,libtool,make,python,gettext-devel,gettext,intltool,libiconv,pkg-config,git,curl,wget,libxslt,bc,patch,cmake,perl,yasm,unzip
Make sure that the following GIT setting is used to avoid issues with line endings:
git config --global core.autocrlf input
Cloning Mono from GitHub repository
First step is to clone Mono repository directly from GitHub, PREFIX
is you Mono installation location (see below for details):
export PREFIX=[mono installation location]
export PATH=$PREFIX/bin:$PATH
git clone https://github.com/mono/mono.git
cd mono
Pre-configured build instructions
Pre-configured build instructions, building a default Visual Studio Mono runtime, mingw Mono runtime, Mono BCL and install into PREFIX
. For further detailed build configurations and instructions, see next section. Run one of the following set of commands from a Cygwin command prompt after all steps in section above have been completed.
64-bit Mono runtime using SGen GC and default BCL profile (net_4_x):
./autogen.sh --prefix=$PREFIX --host=x86_64-w64-mingw32 --enable-msvc --disable-boehm
make -j4
make install
32-bit Mono runtime using SGen GC and default BCL profile (net_4_x):
./autogen.sh --prefix=$PREFIX --host=i686-w64-mingw32 --enable-msvc --disable-boehm
make -j4
make install
Detailed build instructions
If one of the pre-configured set of build instructions above doesn’t match configuration needs, this section outline detailed step by step build instructions.
Build will use configured PREFIX
where an existing Mono distribution exists that will be used and later replaced by build. NOTE, to keep existing Mono distribution untouched, setup a different PREFIX
where the new build will be installed.
It is possible to only configure PATH
to point to an existing Mono distribution without specify PREFIX
but then make install
will install build into default location.
Another option is to build without an existing pre-installed Mono distribution, see section related to monolite
for more details or the section describing how to use a Visual Studio build Mono runtime in MONO_EXECUTABLE
environment variable as part of build.
The following configure steps shows different supported Mono build configurations.
64-bit Mono runtime using SGen GC and default BCL profile (net_4_x). The Boehm GC is not supported on 64-bit Windows build:
./autogen.sh --prefix=$PREFIX --host=x86_64-w64-mingw32 --disable-boehm
32-bit Mono runtime using SGen GC and default BCL profile (net_4_x):
./autogen.sh --prefix=$PREFIX --host=i686-w64-mingw32 --disable-boehm
32-bit Mono runtime using Boehm GC and default BCL profile (net_4_x):
./autogen.sh --prefix=$PREFIX --host=i686-w64-mingw32
NOTE, 32-bit Mono runtime supports both SGen and Boehm GC. Boehm GC is still available for legacy reasons but not supported on 64-bit Windows builds. It is recommended to use SGen GC for both 32 and 64-bit Windows builds.
Enable BTLS as cryptographic backend for Windows builds
Mono on Windows supports BTLS library as an alternative cryptographic backend for SSL/TLS. It is not the default alternative and must be enabled to build and be used by Mono runtime. To enable BTLS, pass --enable-btls
to the autogen.sh
step above.
BTLS build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use Chocolatey package manager. See https://chocolatey.org/install for instructions on how to install Chocolatey package manager into the build system.
Once Chocolatey has been installed, add the following packages to the build system:
choco install cmake
Optional, in order to build BTLS with assembler optimization support, additional packages needs to be installed. It is still possible to build without these packages using Visual Studio as cmake build generator, but that configuration won’t be able to build assembler optimized cryptographic functions.
choco install activeperl
choco install ninja
choco install yasm
Make sure they are all visible to the build environment used by Visual Studio (restart any command prompts or Visual Studio IDE’s used in the build).
Enable LLVM for Windows builds
Mono on Windows supports LLVM in several different build combinations. When doing Windows cross compiler builds, host == Win32 but target != Win32, standard LLVM build instructions can be used.
For regular Windows builds, host == Win32, target == Win32 (described in this page), only x64 Visual Studio build supports LLVM. To enable LLVM, pass --enable-llvm
to the autogen.sh
step above.
Windows build supports most of the LLVM configuration flags, except --enable-loadedllvm
. If configured with --with-llvm
, Visual Studio build will use pre-build LLVM version pointed to by llvm-config.exe
instead of building internal LLVM version as part of Visual Studio build.
NOTE, since only x64 Visual Studio build supports LLVM for regular Windows builds, a warning will be generated in the autogen.sh
output indicating that LLVM will be disabled for mingw builds. Similar warning will be generated when building an unsupported build configuration from within Visual Studio (using the Win32 build configurations).
There is also a couple of MSBuild properties directly controlling the use of LLVM from Visual Studio builds (in case autogen.sh
is not used or needs to be overridden).
MONO_ENABLE_LLVM
When set to true, enable Visual Studio LLVM build. Could be explicitly passed to MSBuild or set in mono.props
in order to force LLVM build.
MONO_EXTERNAL_LLVM_CONFIG
When set to a path pointing to a pre-build version of llvm-config.exe
, specified LLVM build will be used instead of doing local internal LLVM build as part of regular Visual Studio Mono runtime build. Could be explicitly passed to MSBuild or set in mono.props
in order to force LLVM build.
Additional prerequisites only applies when building LLVM as part of Visual Studio Mono runtime build. If using --with-llvm
configuration option or MONO_EXTERNAL_LLVM_CONFIG MSBuild property, no additional prerequisites are needed.
LLVM build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use Chocolatey package manager. See https://chocolatey.org/install for instructions on how to install Chocolatey package manager into the build system.
Once Chocolatey has been installed, add the following packages to the build system:
choco install cmake
choco install python2
Optional, by default LLVM build will use Visual Studio as cmake build generator. Build also support ninja as cmake build generator. In order to use ninja, install the following packages to the build system:
choco install ninja
Make sure they are all visible to the build environment used by Visual Studio (restart any command prompts or Visual Studio IDE’s used in the build).
Use monolite instead of pre-installed Mono distribution
If no Mono distribution is available, you can build using monolite
. Just run the command below before running make
:
make get-monolite-latest
Build Mono using Visual Studio
The native runtime libraries can be built using Visual Studio and msbuild. However, the .NET libraries and tests must currently be built in Cygwin using make
. The steps below describe how to build the runtime libraries in Visual Studio and use the Visual Studio built Mono executable when building the class libraries and tests as well as running the test suites in Cygwin.
Build 64-bit Mono using Visual Studio
Open the Mono solution msvc\mono.sln
in Visual Studio IDE. Rebuild the solution using Release and x64 platform configurations. For command line build, see below.
Build 32-bit Mono using Visual Studio
Open the Mono solution msvc\mono.sln
in Visual Studio IDE. Rebuild the solution using Release and Win32 platform configurations. For command line build, see below.
Build Mono from Visual Studio command line
Instead of building from within Visual Studio IDE you can run msbuild.exe
directly from the command line. It is recommended to run the build from a Visual Studio Developer Command Prompt to get a correctly setup build environment.
For Visual Studio 2015: Run "%ProgramFiles(x86)%\Microsoft Visual Studio 14.0\Common7\Tools\VsDevCmd.bat"
from command prompt used in build or launch new command prompt using ´Developer Command Prompt for VS2015´ from start menu (if installed).
For Visual Studio 2017: Run "%ProgramFiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat"
from the command prompt used in build or launch new command prompt using ´Developer Command Prompt for VS2017´ from start menu (if installed).
NOTE, paths to installed Visual Studio files could be different depending on install location and Visual Studio edition.
Example of a Visual Studio 2015 32-bit Mono runtime release build using SGen GC:
msbuild.exe /p:PlatformToolset=v140 /p:Platform=Win32 /p:Configuration=Release /p:MONO_TARGET_GC=sgen msvc/mono.sln
Example of a Visual Studio 2015 64-bit Mono runtime release build using SGen GC:
msbuild.exe /p:PlatformToolset=v140 /p:Platform=x64 /p:Configuration=Release /p:MONO_TARGET_GC=sgen msvc/mono.sln
Example of a Visual Studio 2017 32-bit Mono runtime release build using SGen GC:
msbuild.exe /p:PlatformToolset=v141 /p:Platform=Win32 /p:Configuration=Release /p:MONO_TARGET_GC=sgen msvc/mono.sln
Example of a Visual Studio 2017 64-bit Mono runtime release build using SGen GC:
msbuild.exe /p:PlatformToolset=v141 /p:Platform=x64 /p:Configuration=Release /p:MONO_TARGET_GC=sgen msvc/mono.sln
There is also a build script that can be used to run msbuild.exe
from a Visual Studio build environment, msvc\run-msbuild.bat
. The script selects Visual Studio version toolchain based on VisualStudioVersion
environment variable.
For Visual Studio 2015 64-bit Mono Runtime build:
set VisualStudioVersion=14.0
msvc\run-msbuild.bat "/p:Configuration=Release /p:Platform:x64 /p:MONO_TARGET_GC=sgen /t:Build"
For Visual Studio 2017 64-bit Mono Runtime build:
set VisualStudioVersion=15.0
msvc\run-msbuild.bat "/p:Configuration=Release /p:Platform=x64 /p:MONO_TARGET_GC=sgen /t:Build"
NOTE, while it is possible to run msbuild.exe
from Cygwin environment it is not recommended since the build might pick up build tools and dependencies from Cygwin instead of Windows environment. There is however a build script msvc/run-msbuild.sh
that can be called from Cygwin that will try to setup original Windows environment before running msbuild.exe
.
Visual Studio MSBuild build properties
Building Mono runtime using Visual Studio offers a number of additional options compared to regular autogen.sh
configuration steps. These properties can be explicitly passed to MBuild or set in mono.props
property file, read by Mono Visual Studio build.
It is also possible to change property values within Visual Studio IDE through “Property Manager”, “View” -> “Other Windows” -> “Property Manager”, open Mono property sheet under Mono project (any configuration will do), and select “Common Properties” -> “User Macros”. When a value has been changed, select OK and all Visual Studio build configurations should be updated accordingly. If property values are changed directly in mono.props
, while solution is loaded in Visual Studio, changes will not take place until after solution has been reloaded. If property values are change using IDE’s “Property Manager” dialog, changes applies directly to loaded solution.
MONO_BUILD_DIR_PREFIX
Build tree location. Change to enable out of source tree builds, example c:\mono-build\
. Default value is .\build\
meaning build will end up in mono-root\msvc\build
MONO_TARGET_GC
GC used in build, sgen or boehm. NOTE, boehm is only supported on 32-bit build configurations. Default is sgen for all build configuration.
MONO_USE_STATIC_C_RUNTIME
Link Mono binaries using static c-runtime. When false, all binaries and libraries will link using dynamic c-runtime. Default value is false.
MONO_USE_STATIC_LIBMONO
Link Mono binaries using static libmono. When false, Mono binaries will link using dynamic libmono. Default value is false.
MONO_ENABLE_LLVM
Mono runtime will link and include LLVM. If MONO_EXTERNAL_LLVM_CONFIG is not set, this will also build Mono LLVM repository as part of regular Mono runtime build. When false, Mono runtime will not link and include llvm libraries. Default value is false.
NOTE, this options can also be set through standard configuration, using --enable-llvm
.
MONO_EXTERNAL_LLVM_CONFIG
Use an external pre-build LLVM library instead of internal build. NOTE, this requires MONO_ENABLE_LLVM to be set or won’t have effect. Default value is empty.
NOTE, this options can also be set through standard configuration, using --with-llvm=full-path-to-llvm-config.exe
.
MONO_ENABLE_BTLS
Mono runtime will link and include BTLS. Setting this value to true will also build Mono BTLS repository as part of regular Mono runtime build. When false, Mono runtime will not link and include BTLS. Default value is false.
NOTE, since BTLS support is part of BCL build, just setting this when doing Mono runtime build will not include needed BTLS support in BCL build. It is recommended to use --enable-btls
as part of configuration step since that will make sure BTLS support is included in both BCL as well as Mono runtime build.
Configure make
to use Visual Studio build Mono runtime
For make to use Visual Studio build Mono runtime when building BCL and test, set MONO_EXECUTABLE
environment variable to Visual Studio build Mono runtime. Switch to the Cygwin shell previously used and run:
export MONO_EXECUTABLE=/cygdrive/c/mono-source-location/msvc/build/sgen/x64/bin/Release/mono-sgen.exe
NOTE, above path will change depending on source location, build location, 32/64-bit build configuration and used GC. The example above uses the default build location for a 64-bit release build Mono runtime configured to use SGen GC.
Build Mono mingw runtime, BCL and Tests
Switch to the Cygwin shell previously used and run:
make -j4
NOTE, the mingw build Mono runtime will still be built even if a Visual Studio build Mono runtime has been built and configured. The mingw runtime will however not be used as part of the BCL or test builds since MONO_EXECUTABLE
has been configured.
Known Issue: “failed to create symbolic link”
If you run make V=1
and see this after a successful BCL build:
make[8]: Entering directory '/home/user/work/mono/mcs/class/corlib'
CYGWIN=winsymlinks:nativestrict ln -s /home/user/work/mono/mcs/class/lib/build-win32 /home/user/work/mono/mcs/class/lib/build
ln: failed to create symbolic link '/home/user/work/mono/mcs/class/lib/build': Operation not permitted
make[8]: *** [../../build/library.make:336: ../../class/lib/build/.stamp] Error 1
you need to enable Developer Mode
in the Windows 10 Settings app (Update & Security -> For developers tab) which will allow your user to create symbolic links without administrator privileges.
If you use an earlier Windows versions, you need to run the build as administrator.
Run all tests
Make sure MONO_EXECUTABLE
has been setup to use Visual Studio build Mono runtime, see above for instructions. For all tests to run and pass, the Cygwin shell will need elevated permissions. Without additional permissions, some test failures will be identified.
make check
Install build
make install