A prototypical F# library (file system layout and tooling), recommended by the F# Foundation.
This sample demonstrates the suggested structure of a typical F# solution. (NOTE: this layout should NOT be used when authoring a Type Provider. For more details about doing so, please read this.) It also showcase a few popular F#-centric libraries (e.g. F# Make), as well as using some more general libraries (e.g. NUnit) from within F#.
Folder | Descritpion |
---|---|
.nuget |
This directory, and the files it contains, are used to bootstrap the build process. Specifically, it enables the acquistion of NuGet dependencies on a clean build. It is further used by the build process when performing other NuGet-related tasks. These tools also facilitate the Package Restore functionality inside of Visual Studio. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory be committed to source control. |
bin |
This directory is the primary output directory for libraries and NuGet packages when using the build system
(i.e. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control. |
docs/content |
Use this directory for all your narratvie documentation source files.
Said files should be either F# scripts (ending in |
docs/files |
Use this directory to house any supporting assets needed for documentation generation. For instance, this directory might be where you place image files which are to be linked/embedded in the final documentation. |
docs/output |
This directory will contain the final artifacts for both narrative and API documentation. This folder will be automatically created by the documenation generation process. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control. |
docs/tools |
This directory contains tools used in the generation of both narrative documentation and API documentation.
The main interaction with the content of this directory consists of editing |
docs/tools/templates |
This directory 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 |
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 |
You should use this directory to store any artifacts required to produce a NuGet package for your project.
This typically includes a |
packages |
Any NuGet packages on which your project depends will be downloaded to this directory. Additionally, packages required by the build process will be stored here. It is strongly advised that the contents of this directory NOT be committed to source control. |
src |
Use this directory to house the actual codebase (e.g. one, or more, Visual Studio F# projects) in your solution. A good way to get started is to rename the project included in this sample (FSharp.ProjectTemplate). Alternately, delete the sample project and create your own. NOTE: When you rename the sample project, or add aditional projects to this directory, you may need to edit NOTE: you should NOT place testing porjects in this path. Testing files belong in the |
temp |
This directory is used by the build process as a "scratch", or working, area. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control. |
tests |
Use this directory to house 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, NOTE: When you rename the sample project, or add aditional projects to this directory, you may need to edit |
Path | Descritpion |
---|---|
build.cmd |
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:
|
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 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:
|
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 |