Using F# Interactive (FSI.EXE)

F# Interactive is the name of the command line interactive shell for F#. It runs on .NET 2.0 (Visual Studio 2005), .NET 1.x (Visual Studio 2003) and Mono. You can also use it as a tool window in Visual Studio 2005. Run it using ..\bin\fsi.exe. The WebCrawl, TermWalker and DirectX 3D Demo give examples of how to script. Note you can paste line-by-line into the top-level environment, or else use F# Interactive in Visual Studio or another shell-hosting environment such as those available in Emacs. You can also often compile scripts using fsc.exe.

Inputs to fsi.exe are terminated with ;; (nothing happens until you type this!). You generally don't need to enter this when using F# from Visual Studio as it is added automatically each time you send text for execution. This applies particularly when using the light syntax option when top-level expressions no longer need to be separated by ;;.

Common switches are:

t
   --no-gui           run a session without a GUI event loop.b
   -O3             run a session that produces maximally optimized code on-the-fly
   -I              add a path to search for compiled interface files
   -r              reference a DLL

Common meta-commands you can enter into fsi.exe are:

    #r <string>;;    dynamically reference the given DLL.
    #I <string>;;    add the given include path.
    #light;;         turn on the light syntax option syntax
    #use <string>;;  load the given file as if it had been entered from the command line
    #load <filename>;; compile the given file as a named module, then load
    #time;;          toggle timing on/off.
    #quit;;          quit the session.

The first three of these can also be used directly in F# source code files. It is also handy to quote filenames using 'verbatim strings', e.g.

    #r @"c:\Program Files\fsharp-1.9.4.19\bin\absil.dll";;

When you type an expression into F# Interactive, the last such expression is assigned into the variable it. This is purely an artefact of typing entries into F# Interactive. If you compile the same code with the command-line compiler or when loading a file into F# Interactive as a compilation unit the expression will simply be executed and its result discarded.

F# comes with a Visual Studio AddIn that lets you use 'F# Interactive' for use as a tool Window in Visual Studio 2005. The tool window is a Visual Studio AddIn, and should be managed via the AddIn Manager menu option found under the 'Tools' menu. You can also start up F# Interactive simply using 'Alt-Enter' (Note: this key must currently be bound manually on the Japanese edition of Visual Studio 2005)

To start the session, go to the AddIn manager and select 'F# Interactive for Visual Studio'. If it is already selected, then unselect it, close and reopen the AddIn manager and reselect it. Either way a new window should appear with an F# Interactive session.

The session is global to the instance of Visual Studio and text can be sent from any F# source code file (.fs, .fsi, .ml, .mli). Use the 'Alt-Return' combination to evaluate selected text, and 'Alt-Quote' (i.e. Alt-') to evaluate the current line of text without selecting it. History is available with the up/down arrows. These shortcuts may change in future releases.

File names are resolve relative to the scripts containing the reference. Visual F# Interactive sets the line and directory context of the session each time an entry is sent from Visual Studio.

To troubleshoot an installation:

  • Check fsi.exe starts up at the command prompt, including entering simple programs.
  • Check the 'bin' directory of your F# installation (e.g. FSharp-1.9.4.19\bin) is listed in the entries in your AddIn search path under 'Tools', 'Options' in Visual Studio.
F# Command Line - using the compiler

The fsc.exe compiler is a traditional command-line compiler with a set of command-line options similar to both the OCaml compiler and the C# compiler. Detailed help can be found by running "fsc -- help". Some of the common command-line flags are shown below, along with detailed instructions on the How to statically link the F# libary using the "--standalone" option. Also see the notes on using F# in conjunction with alternative CLI implementations.

The most common command-line options (FSC.EXE)
  • -o Name the output file.

  • -I Specify a directory for the search path for referenced assemblies.

  • -g Produce debugging information.

  • -O3 Turn on maximal optimization.

  • -a Produce a DLL.

  • -r Reference an F# or .NET DLL.

  • --keyfile Sign an assembly using the given keyfile. This must be done when creating DLLs that will be shared by multiple programs and installed in the "Global Assembly Cache" on target machines.  For example, the F# library itself is signed with a key.

The default is to build an executable. You can reference a C# or other .NET assembly simply by adding the DLL for the assembly to your command-line with the -r option.

For example, to reference the assembly System.Windows.Forms.dll you provide System.Windows.Forms.dll on your F# command-line:

fsc.exe -r System.Windows.Forms.dll -c mygui.ml

The DLLs for several assemblies in the .NET Redistributable are automatically added to every F# compilation. The .NET Framework installation directory for your machine is also searched when attempting to find named assemblies.

DLLs produced by F# can be used immediately from C# and other .NET languages without any further support files. Simply use /r:mydll.dll on the C#, VB or other .NET language command-line or add the assembly as a dependency in Visual Studio.

Binaries produced with the --debug (-g) and -O (optimization) options are binary compatible, i.e., different binaries in a target application can be compiled with different debugging and optimization settings. Binaries do also have some decent versioning properties.  For example, you may add new functions and types to a module and the resulting DLL will be compatible with the original. You may also modify the interior definitions of a DLL, as long as you do not use cross-module optimization on clients of the DLL. If you use cross-module optimization then clients may have incorporated aspects of the definition of the values in the DLL into their own binary via inlining.

Statically linking the F# library using "--standalone"

The license under which you use the F# compiler may include a clause indicating that binaries produced by the compiler can be redistributed under different (e.g., perhaps commercial-use) conditions if they use the --standalone compiler option to statically link a copy of the F# library into the application. The rationale behind this is the wish to avoid the possiblity of users making mistakes in installing and deploying F# library components, so developers are requested to perform static linking.

The --standalone option will statically link the F# library and all transitively referenced DLLs that depend on the F# library into the assembly being generated (the "target assembly"). The assembly will typically be a .EXE representing a final application but may also be a DLL. Using this option does the following things:

  • It does a graph traversal of all static assembly dependencies beginning with the non-standalone version of the target assembly to determine all the assemblies which depend on the F# library (which along with F# forms the "static linking set").

  • It takes a copy of the code and metadata of each assembly in the static linking set and places this into the target assembly.

  • It renames all types in the target assembly whose name begins with Microsoft.FSharp to a type beginning with FSharp. It also makes all such types private to the target assembly.

  • It adjusts all external assembly references from the static linking set so that they refer to the assemblies referenced during compilation.

  • It disables the generation of the F# interface and optimization attributes.

There are some important restrictions on the use of this option:

  • None of the assemblies in the static linking set may include native code or native resources.

  • None of the assemblies in the static linking set may use COM interop.

  • Some details of debug information may be lost for assemblies in the static linking set.

  • None of the transtively referenced DLLs may itself be a component containing a statically linked F# library.

  • There must be no duplicate type names across any statically linked assemblies.

  • No code may use reflection on any of the types in those assemblies.

  • No code may export F# library types as part of its public API.

  • The application must have been tested using the "--standalone" option.

  • The user of the compiler must run the peverify.exe tool over the contents of the generated binary to ensure the static linking process has produced a valid binary.

This means that the application and its dependent DLLs must only use F# library types internally. It is typically simple to arrange this for an application that is an executable or a service, since these only have a small number of entry points (e.g. one implicit main entrypoint). If the application is a DLL then the application can still be written entirely in F#, but the signatures of exported modules should only include exportable types. Exportable types are abstract, record and discrimination types, types from other .NET assemblies and type abbreviations whose target is itself exportable. Tuple types, first-class function values and types defined in the F# library (apart from those mapped directly to .NET types from other assemblies) are not exportable. Record and discrimination types are only exportable if all their constituent types are exportable types. Values with top-level function types of the form v: typ -> ... typ -> typ may be exported, as long as each individual type is an exportable type.

Using F# in conjunction with other CLI implementations

F# produces CLI programs that conform to the relevant ECMA standards. To produce programs that run on the SSCLI 1.0, Mono 1.0 or other .NET implementations you should certainly be sure to use the "--cli-version 1.0" compiler option to the compiler.

Mono. The binary fscp10.exe in the distribution is a portable version of the F# compiler that works with the Mono CLI implementation, and applies the options --cli-version 1.0 by default. The installation script for F# on Mono (install-mono.sh) makes a copy of this file as bin/fsc.exe, i.e. makes it the default compiler when using Mono. It also installs the .NET 1.0 library DLLs to the GAC:

       gacutil -i bin/fslib10.dll
       gacutil -i bin/mllib10.dll

It also performs AOT compilation on the relevant DLLs.

        mono --aot bin/fslib10.dll
        mono --aot bin/mllib10.dll
        mono --aot bin/FSharp.Compiler10.dll

This will improve startup times for the compiler. (Note that as of Mono 1.1.17 AOT compilation could only be performed on .NET 1.0 binaries, one of the reasons why the .NET 1.0 version of the F# compiler is the default on Mono.)

The program in the original distribution called fsc.exe includes some components that connect to Windows native code. It will run correctly on Windows XP, Windows NT, Windows 2000 and so on. This version of the compiler works best if used on a machine that has an installation of Visual Studio 2005, a version of the Microsoft .NET Framework SDK and/or the Microsoft .NET Redistributable components. This is because the F# compiler detects the presence of these components to do several things:

  • Produce debug information files.

  • Support strong-name signing of assemblies.

  • The installation scripts use the components to support the automatic installation of the F# library components.

If an installation of the appropriate components cannot be found then the F# compiler will not support the above operations, but should continue to produce usable binaries.

Stephen Tse cross-compiles the fjavac idealized/formalized Java compiler using both OCaml and F#, and is one of the lead users of F# on Linux/Mono. He has written some notes on using this combination on the F# Wiki.

SSCLI. The F# compiler also makes an attempt to detect the above components when an installation of the SSCLI is available. This is determined by looking for sscoree.dll on the path. If both the SSCLI and an installation of the .NET Reditributable components are on the same machine then the use of the SSCLI can be forced by using the --sscli compiler option.