Skip to content

Latest commit

 

History

History
211 lines (133 loc) · 10.4 KB

DEVGUIDE.md

File metadata and controls

211 lines (133 loc) · 10.4 KB

Development Guide

Follow the instructions below to build and develop the F# Compiler, Core Library and tools on Windows, macOS and Linux.

Developing the F# Compiler (Windows)

Install

NOTE on Windows:

  1. It is recommended to run the build.cmd and the qualifiers below on a command prompt with path set to have the location of MSBuild. If we have Visual Studio, we can also run using Developer Command Prompt for Visual Studio 20xx (depends on Visual Studio version). This developer command prompt is easier to use than normal command prompt, because it already has the correct path of Visual Studio and .NET's tooling set for us to use (including MSBuild).
  2. The running command prompt must be run under Administrator right (Run as Administrator).

Before running the build scripts, ensure that you have cleaned up the visualfsharp repo by running this git command:

git clean -xfd

On Windows you can build the F# compiler for .NET Framework as follows:

build.cmd

This is the same as

build.cmd net40

There are various qualifiers:

build.cmd release         -- build release (the default)
build.cmd debug           -- build debug instead of release

build.cmd net40           -- build .NET Framework compiler (the default)
build.cmd coreclr         -- build .NET Core compiler 
build.cmd vs              -- build the Visual F# IDE Tools (see below)
build.cmd pcls            -- build the PCL FSharp.Core libraries
build.cmd all             -- build all 

build.cmd proto           -- force the rebuild of the Proto bootstrap compiler in addition to other things

build.cmd test            -- build default targets, run suitable tests
build.cmd net40 test      -- build net40, run suitable tests
build.cmd coreclr test    -- build coreclr, run suitable tests
build.cmd vs test         -- build Visual F# IDE Tools, run all tests (see below)
build.cmd all test        -- build all, run all tests

build.cmd test-smoke      -- build, run smoke tests
build.cmd test-net40-fsharp     -- build, run tests\fsharp suite for .NET Framework
build.cmd test-net40-fsharpqa   -- build, run tests\fsharpqa suite for .NET Framework

After you build the first time you can open and use this solution:

.\FSharp.sln

or just build it directly:

msbuild FSharp.sln

Building FSharp.sln builds nearly everything. However building portable profiles of FSharp.Core.dll is not included. If you are just developing the core compiler and library then building the solution will be enough.

Developing the F# Compiler (Linux)

For Linux/Mono, follow these instructions. Also you may need:

sudo apt-get install mono-complete autoconf libtool pkg-config make git automake

Then:

./autoconf.sh --prefix /usr
make
make install

Full testing is not yet enabled on Linux, nor is a .NET Core build of the compiler.

You can alternatively use

./build.sh

Developing the F# Compiler (macOS)

Install Xamarin Studio, then

./autogen.sh --prefix=/Library/Frameworks/Mono.framework/Versions/Current/
make
sudo make install

Developing the Visual F# IDE Tools (Windows Only)

To build and test Visual F# IDE Tools, install these requirements:

  • Visual Studio 2017
    • Under the "Windows" workloads, select ".NET desktop development"
      • Select "F# desktop language support" under the optional components
    • Under the "Other Toolsets" workloads, select "Visual Studio extension development"

Steps to build:

build.cmd vs              -- build the Visual F# IDE Tools in Release configuration (see below)
build.cmd vs debug        -- build the Visual F# IDE Tools in Debug configuration (see below)
build.cmd vs test         -- build Visual F# IDE Tools, run all tests (see below)

Use VisualFSharp.sln if you're building the Visual F# IDE Tools.

Note on Debug vs Release: Release Configuration has a degraded debugging experience, so if you want to test a change locally, it is recommended to do it in the Debug configuration. For more information see dotnet#2771 and dotnet#2773.

Note: if you face this error #2351:

error VSSDK1077: Unable to locate the extensions directory. "ExternalSettingsManager::GetScopePaths failed to initialize PkgDefManager for C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\devenv.exe".

Or hard crash on launch ("Unknown Error"), delete these folders:

  • %localappdata%\Microsoft\VisualStudio\15.0_(some number here)RoslynDev
  • %localappdata%\Microsoft\VisualStudio\15.0_(some number here)

[Optional] Install the Visual F# IDE Tools (Windows Only)

The new builds of the Visual F# IDE Tools can no longer be installed into Visual Studio 2015.

You can install Visual Studio 2017 from https://www.visualstudio.com/downloads/.

Note: This step will install a VSIX extension into Visual Studio "Next" that changes the Visual F# IDE Tools components installed in that VS installation. You can revert this step by disabling or uninstalling the addin.

For Debug, uninstall then reinstall:

VSIXInstaller.exe /u:"VisualFSharp"
VSIXInstaller.exe debug\net40\bin\VisualFSharpOpenSource.vsix

For Release, uninstall then reinstall:

VSIXInstaller.exe /u:"VisualFSharp"
VSIXInstaller.exe release\net40\bin\VisualFSharpOpenSource.vsix

Restart Visual Studio, it should now be running your freshly-built Visual F# IDE Tools with updated F# Interactive.

[Optional] F5 testing of local changes

To test your changes locally without overwriting your default installed Visual F# tools, set the VisualFSharp\Vsix\VisualFSharpOpenSource project as the startup project. When you hit F5 a new instance of Visual Studio will be started in the RoslynDev hive with your changes, but the root (default) hive will remain untouched. You can also start this hive automatically using

devenv.exe /rootsuffix RoslynDev

Because this uses the "RoslynDev" hive you can simultaneously test changes to an appropriate build of Roslyn binaries.

[Optional] Rapid deployment of incremental changes to Visual F# IDE Tools components

For the brave, you can rapidly deploy incrementally updated versions of Visual F# IDE Tool components such as FSHarp.Editor.dll by copying them directly into the extension directory in your user AppData folder:

xcopy /y debug\net40\bin\FSharp.* "%USERPROFILE%\AppData\Local\Microsoft\VisualStudio\15.0_7c5620b7FSharpDev\Extensions\Microsoft.VisualFSharpTools\Visual F# Tools\15.4.1.9055"

This gives a much tighter inner development loop than uninstalling/reinstalling the VSIX, as you do not have to restart VIsual Studio. Caveat emptor.

[Optional] Clobber the F# SDK on the machine

Note: The step below will try to clobber the machine-wide installed F# SDK on your machine. This replaces the fsc.exe used by the standard install location or Microsoft.FSharp.Targets. Repairing Visual Studio 15 is currently the only way to revert this step.

For Debug:

vsintegration\update-vsintegration.cmd debug

For Release:

vsintegration\update-vsintegration.cmd release

Notes

Windows: Links to Additional frameworks

Notes on the Windows .NET Framework build

  1. The update.cmd script adds required strong name validation skips and NGens the compiler and libraries. This requires admin privileges.
  2. The compiler binaries produced are "private" and strong-named signed with a test key.
  3. Some additional tools are required to build the compiler, notably fslex.exe, fsyacc.exe, FSharp.PowerPack.Build.Tasks.dll, FsSrGen.exe, FSharp.SRGen.Build.Tasks.dll, and the other tools found in the lkg directory.
  4. The overall bootstrapping process executes as follows
  • We first need an existing F# compiler. We use the one in the lkg directory. Let's assume this compiler has an FSharp.Core.dll with version X.
  • We use this compiler to compile the source in this distribution, to produce a "proto" compiler, dropped to the proto directory. When run, this compiler still relies on FSharp.Core.dll with version X.
  • We use the proto compiler to compile the source for FSharp.Core.dll in this distribution.
  • We use the proto compiler to compile the source for FSharp.Compiler.dll, fsc.exe, fsi.exe, and other binaries found in this distribution.

Configuring proxy server

If you are behind a proxy server, NuGet client tool must be configured to use it:

.nuget\nuget.exe config -set http_proxy=proxy.domain.com:8080 -ConfigFile .nuget\NuGet.Config
.nuget\nuget.exe config -set http_proxy.user=user_name -ConfigFile .nuget\NuGet.Config
.nuget\nuget.exe config -set http_proxy.password=user_password -ConfigFile .nuget\NuGet.Config

Where you should set proper proxy address, user name and password.

Resources

The primary technical guide to the core compiler code is The F# Compiler Technical Guide. Please read and contribute to that guide.