Introduction to Paket for F#

F# has a great dependency management tool called Paket.
It's easy to setup and use, whether you're working with F# projects or F# scripts.

In this blog post, we'll create a solution, and project from the ground up using Paket for dependency management. We'll then convert our F# cli app into a .fsx script.

You can find the completed code at this repository:
https://github.com/karanveersp/paket-guide

Paket Overview

Paket is a dependency management tool similar to npm in node, and pip in python.
It can be used to reference NuGet packages, files on GitHub, or any HTTP accessible file.

With a few cli commands (outlined below), you can easily add and update dependencies for your F# project. While dependencies for F# projects are easy enough to manage using NuGet and IDE features,
managing dependencies for F# scripts is challenging.

That's where I feel Paket really shines, and streamlines the process of acquiring and consuming libraries from .fsx scripts.

You can find the official docs here: https://fsprojects.github.io/Paket/

Initializing a Project

We are going to create a solution and a project to compute and display the size of a given directory in gigabytes.
It's a simple enough program which doesn't really need any external libraries to write.

However, I found a nice library we can use to output colorful text using printfn. The library is located here: https://www.nuget.org/packages/BlackFox.ColoredPrintf/

Basically, we'll output the result in one color, and any errors in red.

The following steps are pretty generic which can be referenced for initializing any Paket-based project.

1 - Create a new directory and initialize a solution.

   mkdir PaketGuide
   cd PaketGuide
   dotnet new sln

2 - Install Paket as a local tool.

   dotnet new tool-manifest
   dotnet tool install paket
   dotnet tool restore

3 - Initialize Paket. This generates a file that will contain references to our dependencies.

   dotnet paket init

4 - Initialize a git repository, and create a .gitignore file with the following entries.

   git init

   # Paket
   .paket/
   paket-files/

5 - Create a F# console project and include it in the solution.

   dotnet new console -lang F# -o DirectorySizeCli
   dotnet sln add --project DirectorySizeCli\DirectorySizeCli.fsproj

Paket Files

There are three important files to be aware of to use Paket.

• paket.dependencies - Specifies dependencies and versions for entire codebase. Resides in solution root (same level as .sln file).
• paket.references - Specifies a subset of dependencies for a project in a solution. Resides in project root (same level as .fsproj file).
• paket.lock - A lock file generated by Paket. It contains all the versions of all transitive dependencies which can be used to get reproducible builds.

The paket.dependencies and paket.references files can be manually edited.
The paket.lock file should be left alone and only edited by Paket.

These three files should be committed into source control.

Commands Cheat Sheet

The following table summarizes the most important commands.

Command	Description
dotnet paket init	Generate a new paket.dependencies file.
dotnet paket add	Add a new dependency. By default, it is added to the solution, and then referenced from a project via a paket.references file. Creates a paket.dependencies file as well.
dotnet paket install	Run after updating paket.dependencies file with new package references. Updates lock file, and refreshes all projects that specify paket dependencies to import references.
dotnet paket update	Updates references to latest versions of all dependent packages.
dotnet paket restore	Takes current paket.lock file and updates all projects to reference correction versions of NuGet packages. Should be called by your build script.
dotnet paket outdated	List dependencies that have updates.
dotnet paket generate-load-scripts --framework net6.0	This command is used to generate include scripts which can be loaded in .fsx files or F# interactive.

Directory Size App

We're going to write a simple app to print the size of a given directory.

open System
open System.IO
open System.Linq

/// Converts bytes to gigabytes
let toGb numBytes = (float numBytes) * 1e-9

/// Returns the size of a directory in gigabytes.
let getDirectorySize dirPath =
    DirectoryInfo(dirPath)
        .EnumerateFiles("*", SearchOption.AllDirectories)
        .Sum(fun fi -> fi.Length)
    |> toGb

let dirPath = Environment.GetCommandLineArgs().[1]

try
    dirPath
    |> getDirectorySize
    |> sprintf "The size is: %.3f gb"
    |> printfn "%s"
with
| :? DirectoryNotFoundException as ex -> printfn $"{ex}{ex.StackTrace}"

The two functions at the start do our heavy lifting. We create a simple pipeline from the command line argument to print the directory size.

A try...with block is added to detect invalid directories. If the provided directory isn't found, the exception and stack trace are printed.

It's a useful app but a bit boring! Some color ought to spice it up. Lets use Paket to add the following dependencies to our project.

dotnet paket add BlackFox.ColoredPrintf --version 1.0.5
dotnet paket add FSharp.Core --version 6.0.1

This will add an entries to the paket.dependencies and paket.references files.

You can remove the extra frameworks if you'd like to keep things minimalistic.

The paket.dependencies file should look like this.

source https://api.nuget.org/v3/index.json

storage: none
framework: net6.0
nuget BlackFox.ColoredPrintf 1.0.5
nuget FSharp.Core 6.0.1

Run dotnet restore inside your DirectorySizeCli project directory.
We're ready to dive into some color!

Lets create a new .fs file for our Console module.

If you're using VSCode with the ionide extension as I am, then you can use it to add a new file above Program.fs.

The ColoredPrintf library allows specifying the foreground and background colors using a very concise syntax.

colorprintfn "$red[Hello!]"

The above function will print a red Hello! in the terminal. If you want to change the background, it can be included with a semicolon.

colorprintfn "$red;yellow[Hello!]"

It produces output like the following.

We want some functions that will take a string and output a string in some conventional color that corresponds to the type of message. Include this in Console.fs.

module Console

open BlackFox.ColoredPrintf

let complete = colorprintfn "$magenta[%s]"
let ok = colorprintfn "$green[%s]"
let info = colorprintfn "$cyan[%s]"
let warn = colorprintfn "$yellow[%s]"
let error = colorprintfn "$red[%s]"

Back in Program.fs, open the new Console module, and replace the printfn function with the Console counterparts.

open Console

//...

try
    dirPath
    |> getDirectorySize
    |> sprintf "The size is: %.3f gb"
    |> Console.info
with
| :? DirectoryNotFoundException as ex -> Console.error $"{ex}{ex.StackTrace}"

Run the code using a directory of your choosing as a command line argument.

dotnet run C:\users\karan\csharp

Now that cyan looks sweet!

Lets run a test for the exception case. What a glorious wall of red...

Dependencies in Scripts

Managing dependencies for F# and C# projects is straightforward using the above commands.
But what if you write some F# scripts (.fsx files) which need to use external packages?
Those can be directly invoked using dotnet fsi myscript.fsx and are often sufficient for simple tasks that don't need the full project structure.

Paket offers a command to generate F# and C# include scripts that reference installed packages. These include scripts can be used in F# Interactive (FSI) or .fsx files to load packages.

When the dotnet paket generate-load-scripts command is run, it creates .fsx files under .paket/load/.

The generated load scripts reference DLLs from installed packages using #r preprocessing directives.
Those are tedious to write, and Paket helps us out here.

The dotnet paket generate-load-scripts command only works after packages have been restored. But we don't want to keep re-running this command whenever we add a new package.

To generate load scripts when installing packages, place generate_load_scripts: true at the top of the paket.dependencies file.

generate_load_scripts: true
source https://api.nuget.org/v3/index.json

storage: none
framework: net6.0
nuget BlackFox.ColoredPrintf 1.0.5
nuget FSharp.Core 6.0.1

In a .fsx file you can then reference the external package.

#load @".paket/load/BlackFox.ColoredPrintf.fsx"

open BlackFox.ColoredPrintf

Lets create two files in our solution root, Console.fsx and DirSize.fsx.

Add the following into Console.fsx.

#load @".paket/load/BlackFox.ColoredPrintf.fsx"

module Console =
    open BlackFox.ColoredPrintf

    let complete = colorprintfn "$magenta[%s]"
    let ok = colorprintfn "$green[%s]"
    let info = colorprintfn "$cyan[%s]"
    let warn = colorprintfn "$yellow[%s]"
    let error = colorprintfn "$red[%s]"

DirSize.fsx loads this Console.fsx script. Note that our command line arg index is incremented by 1.
This is because FSI script arguments contain the fsi program itself, and the script as the first two arguments.
The command line arg is the third argument, so index 2.

Example: fsi script.fsx arg1 arg2...

#load "Console.fsx"

open Console
open System
open System.IO
open System.Linq


/// Converts bytes to gigabytes
let toGb numBytes = (float numBytes) * 1e-9

/// Returns the size of a directory in gigabytes.
let getDirectorySize dirPath =
    DirectoryInfo(dirPath)
        .EnumerateFiles("*", SearchOption.AllDirectories)
        .Sum(fun fi -> fi.Length)
    |> toGb

let dirPath = Environment.GetCommandLineArgs().[2]

try
    dirPath
    |> getDirectorySize
    |> sprintf "The size is: %.3f gb"
    |> Console.info
with
| :? DirectoryNotFoundException as ex -> Console.error $"{ex}{ex.StackTrace}"

You can run the script using dotnet fsi to make sure the output is the same as the CLI app.

dotnet fsi DirSize.fsx C:\users\karan\csharp

Conclusion

We've just built a project using Paket from scratch, and used a script to load a dependency.

I know that when I got started using F# scripts, importing libraries was incredibly awkward. Using pip with Python was just smoother and easier, so I just gave up. Once I discovered Paket, I was able to take my F# scripts as far as any Python script.

This was a basic example using NuGet, but I'm eager to explore the ability to reference files on GitHub and how easy that makes sharing libraries. Great topic for a future post.

I hope that this blog post helps you become confident with using Paket and F#.

Happy scripting!