You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document details more advanced options for developing in this codebase. It is not quite necessary to follow it, but it is likely that you'll find something you'll need from here.
4
4
5
-
Get the latest source code from the master branch by running this git command:
5
+
## Recommended workflow
6
6
7
-
git clone https://github.com/dotnet/fsharp.git
7
+
We recommend the following overall workflow when developing for this repository:
8
8
9
-
Before running the build scripts, ensure that you have cleaned up the visualfsharp repo by running this git command:
9
+
* Fork this repository
10
+
* Always work in your fork
11
+
* Always keep your fork up to date
10
12
11
-
git clean -xfd
13
+
This will make management of multiple forks and your own work easier over time.
12
14
13
-
This will remove any files that are not under version control. This is necessary only if you have already attempted to build the solution or have made other changes that might prevent it from building.
15
+
## Updating your fork
14
16
15
-
## Installing Dependencies and Building
17
+
We recommend the following commands to update your fork:
16
18
17
-
Follow the instructions below to build and develop the F# Compiler, Core Library and tools on Windows, macOS and Linux.
19
+
```
20
+
git checkout master
21
+
git clean -xdf
22
+
git fetch upstream
23
+
git rebase upstream/master
24
+
git push
25
+
```
18
26
19
-
-[Developing the F# Compiler (Windows)](#developing-the-f-compiler-windows)
20
-
-[Developing the F# Compiler (Linux/macOS)](#developing-the-f-compiler-linuxmacos)
21
-
-[Developing the Visual F# IDE Tools (Windows Only)](#developing-the-visual-f-ide-tools-windows-only)
Install the latest released [Visual Studio](https://www.visualstudio.com/downloads/), as that is what the `master` branch's tools are synced with. Select the following workloads:
32
38
33
-
1. It is recommended to run `build.cmd` in a command prompt with path set to have the location of MSBuild. If you have Visual Studio, we can 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).
39
+
* .NET desktop development (also check F# desktop support, as this will install some legacy templates)
40
+
* Visual Studio extension development
34
41
35
-
2. The command prompt must have Administrator rights (`Run as Administrator`).
42
+
Building is simple:
36
43
37
-
On Windows you can build the F# compiler and tools as follows:
38
-
39
-
Build.cmd
44
+
build.cmd
40
45
41
46
Desktop tests can be run with:
42
47
43
-
Build.cmd -test
48
+
build.cmd -test
44
49
45
-
Additional options are available via:
50
+
After you build the first time you can open and use this solution in Visual Studio:
46
51
47
-
Build.cmd /?
52
+
.\VisualFSharp.sln
53
+
54
+
If you don't have everything installed yet, you'll get prompted by Visual Studio to install a few more things. This is because we use a `.vsconfig` file that specifies all our dependencies.
48
55
49
-
After you build the first time you can open and use this solution:
56
+
## Developing on Windows - No Visual Studio
50
57
51
-
.\VisualFSharp.sln
58
+
We recommend installing the latest released Visual Studio and using that if you are on Windows. However, if you prefer not to do that, you will need to install the following:
52
59
53
-
If you are just developing the core compiler and library then building ``FSharp.sln`` will be enough.
If you do not have Visual Studio installed and want to simply build the compiler as a .NET Core application, use this:
63
+
You'll need to pass an additional flag to the build script:
56
64
57
-
Build.cmd -noVisualStudio
65
+
build.cmd -noVisualStudio
66
+
67
+
You can open `FSharp.sln` in your editor of choice.
58
68
59
-
###Developing the F# Compiler (Linux/macOS)
69
+
## Developing on Linux or macOS
60
70
61
71
For Linux/Mac:
62
72
@@ -65,140 +75,93 @@ For Linux/Mac:
65
75
Running tests:
66
76
67
77
./build.sh --test
78
+
79
+
You can then open `FSharp.sln` in your editor of choice.
68
80
69
-
### Developing the Visual F# IDE Tools (Windows Only)
70
-
71
-
To build and test Visual F# IDE Tools, install these requirements:
72
-
73
-
- Download [Visual Studio 2019](https://www.visualstudio.com/downloads/)
74
-
- Launch the Visual Studio Installer
75
-
- Under the **"Windows"** workload, select **".NET desktop development"**
76
-
- Select the optional component **"F# desktop language support"**
77
-
- Under the **"Other Toolsets"** workload, select **"Visual Studio extension development"**
81
+
## Testing from the command line
78
82
79
-
Steps to build:
83
+
You can find all test options as separate flags. For example:
80
84
81
-
Build.cmd -- build all F# components under the default configuration (Debug)
82
-
Build.cmd -configuration Release -- build all F# components as Release
83
-
Build.cmd -testDesktop -- build and test all net472 tests
85
+
```
86
+
build -testDesktop -- test all net472 target frameworks
87
+
build -testCoreClr -- test all netstandard and netcoreapp target frameworks
88
+
build -testFSharpQA -- test all F# Cambridge tests
89
+
build -testVs -- test all VS integration points
90
+
build -testFcs -- test F# compiler service components
91
+
build -testAll -- all of the above
92
+
```
84
93
85
-
All test options:
94
+
Running any of the above will build the latest changes and run tests against them.
86
95
87
-
-testDesktop -- test all net472 target frameworks
88
-
-testCoreClr -- test all netstandard and netcoreapp target frameworks
89
-
-testFSharpQA -- test all F# Cambridge tests
90
-
-testVs -- test all VS integration points
91
-
-testFcs -- test F# compiler service components
92
-
-testAll -- all of the above
96
+
## Updating FSComp.fs, FSComp.resx and XLF
93
97
94
-
Use ``VisualFSharp.sln`` if you're building the Visual F# IDE Tools.
95
-
96
-
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 issues [#2771](https://github.com/Microsoft/visualfsharp/issues/2771) and [#2773](https://github.com/Microsoft/visualfsharp/pull/2773).
97
-
98
-
Note ([#2351](https://github.com/Microsoft/visualfsharp/issues/2351)): if you face this error:
99
-
100
-
> error VSSDK1077: Unable to locate the extensions directory. "ExternalSettingsManager::GetScopePaths failed to initialize PkgDefManager for C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\devenv.exe".
101
-
102
-
Or hard crash on launch ("Unknown Error"), delete these folders:
103
-
104
-
-`%localappdata%\Microsoft\VisualStudio\16.0_(some number here)RoslynDev`
105
-
-`%localappdata%\Microsoft\VisualStudio\16.0_(some number here)`
106
-
107
-
#### [Optional] Install the Visual F# IDE Tools (Windows Only)
108
-
109
-
The new builds of the Visual F# IDE Tools can no longer be installed into Visual Studio 2015.
98
+
If your changes involve modifying the list of language keywords in any way, (e.g. when implementing a new keyword), the XLF localization files need to be synced with the corresponding resx files. This can be done automatically by running
110
99
111
-
You can install Visual Studio 2019 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
114
-
components installed in that VS installation. You can revert this step by disabling or uninstalling the addin.
104
+
This only works on Windows/.NETStandard framework, so changing this from any other platform requires editing and syncing all of the XLF files manually.
Restart Visual Studio, it should now be running your freshly-built Visual F# IDE Tools with updated F# Interactive.
114
+
First, ensure that `VisualFSharpFull` is the startup project.
127
115
128
-
#### [Optional] F5 testing of local changes
116
+
Then, use the **f5** or **ctrl+f5** keyboard shortcuts to test your tooling changes. The former will debug a new instance of Visual Studio. The latter will launch a new instance of Visual Studio, but with your changes installed.
129
117
130
-
To test your changes locally _without_ overwriting your default installed Visual F# tools, set the `VisualFSharp\Vsix\VisualFSharpFull`
131
-
project as the startup project. When you hit F5 a new instance of Visual Studio will be started in the `RoslynDev` hive with your
132
-
changes, but the root (default) hive will remain untouched. You can also start this hive automatically using
118
+
Alternatively, you can do this entirely via the command line if you prefer that:
133
119
134
120
devenv.exe /rootsuffix RoslynDev
135
121
136
-
Because this uses the "RoslynDev" hive you can simultaneously test changes to an appropriate build of Roslyn binaries.
137
-
138
-
#### [Optional] Rapid deployment of incremental changes to Visual F# IDE Tools components
139
-
140
-
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:
**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 16 is currently the only way to revert this step.**
131
+
It's important to use `Release` if you want to see if your changes have had a noticable performance impact.
149
132
150
-
For **Debug**:
133
+
### Performance and debugging
151
134
152
-
vsintegration\update-vsintegration.cmd debug
135
+
Use the `Debug` configuration to test your changes locally. It is the default. Do not use the `Release` configuration! Local development and testing of Visual Studio tooling is not designed for the `Release` configuration.
153
136
154
-
For **Release**:
137
+
### Troubleshooting a failed build of the tools
155
138
156
-
vsintegration\update-vsintegration.cmd release
139
+
You may run into an issue with a somewhat difficult or cryptic error message, like:
157
140
158
-
## Debugging the F# Compiler
159
-
160
-
See the "Debugging The Compiler" section of this [article](https://medium.com/@willie.tetlow/f-mentorship-week-1-36f51d3812d4)
161
-
162
-
## Notes
163
-
164
-
### Windows: Links to Additional frameworks
141
+
> error VSSDK1077: Unable to locate the extensions directory. "ExternalSettingsManager::GetScopePaths failed to initialize PkgDefManager for C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\devenv.exe".
1. The `update.cmd` script adds required strong name validation skips and NGens the compiler and libraries. This requires admin privileges.
174
-
1. The compiler binaries produced are "private" and strong-named signed with a test key.
175
-
1. 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.
176
-
1. The overall bootstrapping process executes as follows
177
-
- 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.
178
-
- 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.
179
-
- We use the proto compiler to compile the source for `FSharp.Core.dll` in this distribution.
180
-
- We use the proto compiler to compile the source for `FSharp.Compiler.dll`, `fsc.exe`, `fsi.exe`, and other binaries found in this distribution.
147
+
-`%localappdata%\Microsoft\VisualStudio\<version>_(some number here)RoslynDev`
148
+
-`%localappdata%\Microsoft\VisualStudio\<version>_(some number here)`
181
149
182
-
### Updating FSComp.fs, FSComp.resx and XLF
150
+
Where `<version>` corresponds to the latest Visual Studio version on your machine.
183
151
184
-
If your changes involve modifying the list of language keywords in any way, (e.g. when implementing a new keyword), the XLF localization files need to be synced with the corresponding resx files. This can be done automatically by running
The primary technical guide to the core compiler code is [The F# Compiler Technical Guide](https://fsharp.github.io/2015/09/29/fsharp-compiler-guide.html). Please read and contribute to that guide.
189
155
190
-
This only works on Windows/.NETStandard framework, so changing this from any other platform requires editing and syncing all of the XLF files manually.
156
+
See the "Debugging The Compiler" section of this [article](https://medium.com/@willie.tetlow/f-mentorship-week-1-36f51d3812d4) for some examples.
191
157
192
-
### Configuring proxy server
158
+
##Addendum: configuring a proxy server
193
159
194
160
If you are behind a proxy server, NuGet client tool must be configured to use it:
Where you should set proper proxy address, user name and password.
201
-
202
-
### Resources
203
-
204
-
The primary technical guide to the core compiler code is [The F# Compiler Technical Guide](https://fsharp.github.io/2015/09/29/fsharp-compiler-guide.html). Please read and contribute to that guide.
0 commit comments