F# ProjectScaffold

A prototypical F# library (file system layout and tooling), recommended by the F# Software Foundation.

This scaffolding can be used to generate the suggested structure of a typical F# library. (NOTE: this layout needs adjusting when authoring a Type Provider. In that case you should use a separate Tests solution)

Technologies

Area	Technologies
Platforms	Linux, Windows, OSX
Build Automation	FAKE
Unit Testing	NUnit
Package Formats	Nuget packages
Documentation Authoring	Markdown, HTML and F# Literate Scripts
Source Code Linking	SourceLink
Continuous Build and Test	Travis (Linux/OSX) and AppVeyor (Windows)
Default Package Hosting	nuget.org
Default Documentation Hosting	GitHub Pages

Initializing

Run

./build.sh

or

./build.cmd

You will be prompted for the name of your project and some other details. The project structure will then be generated from templates.

Build and Release

After initialization, you can

• Open, edit, build and test using ProjectName.sln
• Build and test release binaries using build.cmd or build.sh
• Build and test release packages using build.cmd Release or build.sh Release
• Build and publish release docs using build.cmd ReleaseDocs or build.sh ReleaseDocs
• Add assets to the GitHub releases (Look into the Release target in build.fsx)
• Publish packages using build.cmd Release or build.sh Release (and specify the NugetAccessKey)

Structure

Summary of solution folders

Folder	Description
.nuget	These files are used to get NuGet dependencies on a clean build and for other NuGet-related tasks including Visual Studio Package Restore. Do not put anything else in this directory. Do commit the contents of this directory to source control.
bin	The primary output directory for libraries and NuGet packages when using the build system (i.e. build.cmd and build.sh). It is also the target directory when building in Visual Studio or Xamarin Studio (Note: this has to be manually configured on a per-project basis, as has been done with the example project). Do not put anything else in this directory. Do not commit the contents of this directory to source control.
docs/content	Use this directory for all your literate documentation source files. These should be either F# scripts (ending in .fsx) or Markdown files (ending in .md). This project includes two sample documentation scripts. Feel free to extend and/or replace these files. For more information on generating documentation, please see FSharp.Formatting.
docs/files	Contains supporting assets needed for documentation generation. For instance, image files which are to be linked/embedded in the final documentation.
docs/output	Contains the final artifacts for both narrative and API documentation. This folder will be automatically created by the documenation generation process. Do not put anything else in this directory. Do not commit this directory to source control.
docs/tools	Contains tools used in the generation of both narrative documentation and API documentation. Edit generate.fsx to include the appropriate repository information (see the following table for more details).
docs/tools/templates	Contains the (default) Razor template used as part of generating documentation. You are encouraged to edit this template. You may also create additional templates, but that will require making edits to generate.fsx.
lib	Any libraries on which your project depends and which are NOT managed via NuGet should be kept in this directory. This typically includes custom builds of third-party software, private (i.e. to a company) codebases, and native libraries.
nuget	Stores the NuGet package specifications for your project, typically a .nuspec file. Also includes a publish.cmd file for manual deployment of packages to http://nuget.org.
packages	Contains any NuGet packages on which your project depends will be downloaded to this directory. Do not put anything else in this directory. Do not commit the contents of this directory to source control.
src	The actual codebase (e.g. one, or more, F# projects) in your solution. The project files are automatically renamed from (FSharp.ProjectTemplate) when initializing the project. NOTE: When you add projects to this directory, you will need to edit build.fsx and/or generate.fsx. You will also need to update your .sln file(s). NOTE: Do not place testing projects in this path. Testing files belong in the tests directory.
temp	This directory is used by the build process as a "scratch", or working, area. Do not put anything else in this directory. Do not commit the contents of this directory to source control.
tests	Contains any testing projects you might develop (i.e. libraries leveraging NUnit, xUnit, MBUnit, et cetera). The sample project included in this directory is configured to use NUnit. Further, build.fsx is coded to execute these test as part of the build process. NOTE: When you add aditional projects to this directory, you may need to edit build.fsx and/or generate.fsx. You will, likely, also need to update your .sln file(s).

Files

Summary of important solution files

Path	Description
.travis.yml	Specifies an automated continuous integration (CI) build-and-test on OSX using Travis. Enable your CI build at travis-ci.org by logging on there with your GitHub account and activating the project. If you enable this, then every pull request, commit, branch and tag of your project on GitHub will be built automatically. Builds of open source projects are free. The default build is on Mac OSX (you can also specify Linux by changing the default language).
appveyor.yml	A specification of an automated continuous integration (CI) build-and-test on Windows using AppVeyor. Enable your CI build at appveyor.com.
build.cmd and build.sh	A simple command script which allows the build to be started (i.e. calls build.fsx) from the command prompt or the file system explorer. It also fetches the latest version of F# Make, if it's not detected in packages.
build.fsx	This very important file runs the build process. It uses the F# Make library to manage many aspects of maintaining a solution. It contains a number of common tasks (i.e. build targets) such as directory cleaning, unit test execution, and NuGet package assembly. You are encouraged to adapt existing build targets and/or add new ones as necessary. However, if you are leveraging the default conventions, as setup in this scaffold project, you can start by simply supplying some values at the top of this file. They are as follows: project The name of your project, which is used in serveral places: in the generation of AssemblyInfo, as the name of a NuGet package, and for locating a directory under src. summary A short summary of your project, used as the description in AssemblyInfo. It also provides a short summary for your NuGet package. description A longer description of the project used as a description for your NuGet package (Note: line breaks are automatically cleaned up). authors A list of authors' names, as should be displayed in the NuGet package metadata. tags A string containing space-separated tags, as should be included in the NuGet package metadata. solutionFile The name of your solution file (sans-extension). It is used as part of the build process. testAssemblies A list of F# Make globbing patterns to be searched for unit-test assemblies. gitHome The URL of user profile hosting this project's GitHub repository. This is used for publishing documentation. gitName The name of this project's GitHub repository. This is used for publishing documentation. TODO: document list of included build targets.
FSharp.ProjectScaffold.sln	This is a standard Visual Studio solution file. Use it to collect you projects, including tests. Additionally, this example solution includes many of the important non-project files. It is compatible with Visual Studio 2012 and Visual Studio 2013.
LICENSE.txt	This file contains all the relevant legal-ese for your project.
RELEASE_NOTES.md	This file details verion-by-version changes in your code. It is used for documentation and to populate nuget package details. It uses a proper subset of Markdown, with a few simple conventions. More details of this format may be found in the documenation for F# Make's ReleaseNotesHelper.
README.md	Use this file to provide an overview of your repository.
docs/content/index.fsx	Use this file to provide a narrative overview of your project. You can write actual, executable F# code in this file. Additionally, you may use Markdown comments. As part of the build process, this file (along with any other *.fsx or *.md files in the docs/content directory) will be processed into HTML documentation. There is also a build target to deploy the generated documentation to a GitHub pages branch (assuming one has been setup in your repository). For further details about documentation generation, please see the FSharp.Formatting library.
docs/content/tutorial.fsx	This file follows the format of docs/content/index.fsx. It's mainly included to demonstrate that narrative documenation is not limited to a single file, and documentation files maybe hyperlinked to one another.
docs/tools/generate.fsx	This file controls the generation of narrative and API documentation. In most projects, you'll simply need to edit some values located at the top of the file. They are as follows: referenceBinaries A list of the binaries for which documentation should be cretaed. The files listed should each have a corresponding XMLDoc file, and reside in the bin folder (as handled by the build process). website The root URL to which generated documenation should be uploaded. In the included example, this points to the GitHub Pages root for this project. info A list of key/value pairs which further describe the details of your project. This list is exposed to template.cshtml for data-binding purposes. You may include any information deemed necessary. Note: the pairs defined in the included example are being used by the sample template.
docs/tools/templates/template.cshtml	This file provides the basic HTML layout for generated documentation. It uses the C# variant of the Razor templating engine, and leverages jQuery and Bootstrap. Change this file to alter the non-content portions of your documentation. Note: Much of the data passed to this template (i.e. items preceeded with '@') is configured in generate.fsx

---

Sample API documents available here.