Merge pull request #1989 from kblohm/fakeTemplate

WIP: Dotnet new template

build.fsx

@@ -997,6 +997,17 @@ Target.create "_DotNetPackage" (fun _ ->
                 else c.Common
         } |> dtntSmpl) "Fake.sln"
 
+    // pack template
+    let templateProj = appDir @@ "fake-template"
+    DotNet.pack (fun c ->
+    { c with
+        Configuration = DotNet.Release
+        OutputPath = Some nugetDir
+        Common =
+            if CircleCi.isCircleCi then
+                { c.Common with CustomParams = Some "/m:1" }
+            else c.Common
+    } |> dtntSmpl) templateProj
     // TODO: Check if we run the test in the current build!
     Directory.ensure "temp"
     let testZip = "temp/tests.zip"

help/markdown/fake-dotnetcore.md

@@ -28,14 +28,14 @@ Just install the corresponding package for your system:
 
   - There are [other ways to get started](fake-gettingstarted.html#Install-FAKE) if chocolatey / an administrator-cmd or global installation is not an option.
 
-- Windows (dotnet sdk global tool)
+- Dotnet sdk global tool
 
   - Install the .NET sdk (at least `2.1.300`)
   - Install FAKE
 
     <pre>
         <code class="lang-bash">
-        dotnet tool install fake-cli -g --version=5.0.0-*
+        dotnet tool install fake-cli -g --version=5.*
         </code>
     </pre>
 
@@ -50,6 +50,21 @@ now you can use
 
 This is basically it. You can now execute fake commands. Follow the [minimal example below](fake-dotnetcore.html#Minimal-example) for a quick start.
 
+## FAKE Template
+Use the FAKE `dotnet new` template. See [FAKE template]("fake-template.html") for more information.
+
+- Install the template:
+
+  <pre><code class="lang-bash">
+  dotnet new -i "fake-template::*"
+  </code></pre
+
+- Run the template:
+
+  <pre><code class="lang-bash">
+  dotnet new fake
+  </code></pre>
+
 ## CLI
 
 See [Fake command line](fake-commandline.html)
@@ -146,7 +161,3 @@ Get the latest binaries from chocolatey: https://chocolatey.org/packages/fake
 
 Get the latest dotnet-fake cli tool by adding `<DotNetCliToolReference Include="dotnet-fake" Version="5.*" />` to your dependencies (https://www.nuget.org/packages/dotnet-fake)
 
-<div class="alert alert-info">
-    <h5>INFO</h5>
-    <p> Note that `Version="5.*"` is working only after we released the first stable release. For now use `Version="5.0.0-*"` to get the latest non-stable release</p>
-</div>

help/markdown/fake-gettingstarted.md

@@ -16,18 +16,37 @@ In this tutorial you will learn how to set up a complete build infrastructure wi
 
 "FAKE - F# Make" is completely written in F# and all build scripts will also be written in F#, but this doesn't imply that you have to learn programming in F#. In fact the "FAKE - F# Make" syntax is hopefully very easy to learn.
 
-There are various ways to install FAKE 5
-
-* Install the 'fake' or 'fake-netcore' package for you system (currenty chocolatey)
+There are various ways to install FAKE 5:
+
+* Install FAKE as a global dotnet tool: 
+    * To install FAKE globally, run:
+        <pre><code class="lang-bash">
+        dotnet tool install fake-cli -g
+        </code></pre>
+    * To install FAKE into `your_tool_path`, run:
+        <pre><code class="lang-bash">
+        dotnet tool install fake-cli --tool-path your_tool_path
+        </code></pre>
+
+    Use `--version` to specify the version of FAKE. See the [`global_tool` branch of `fake-bootstrap`](https://github.com/FakeBuild/fake-bootstrap/tree/global_tool) for ideas to bootstrap in your CI process.
+
+* Bootstrap via the [fake dotnet new template](fake-template.html). The template bootstraps FAKE and sets up a basic build-script.
+    * To install the template run:
+        <pre><code class="lang-bash">
+        dotnet new -i "fake-template::*"
+        </code></pre>
+    * Then run the template with:
+        <pre><code class="lang-bash">
+        dotnet new fake
+        </code></pre>
+
+    See the [template](fake-template.html) page for more information.
+
+* Install the 'fake' or 'fake-netcore' package for you system (currenty chocolatey).  
   Example `choco install fake -pre`
 
-* Use it as dotnet tool: Add `<DotNetCliToolReference Include="dotnet-fake" Version="5.0.0-*" />` to your dependencies and run `dotnet fake ...` instead of `fake ...`, see [this example](https://github.com/FakeBuild/fake-bootstrap/blob/master/dotnet-fake.csproj)
+* Use it as dotnet tool: Add `<DotNetCliToolReference Include="dotnet-fake" Version="5.*" />` to your dependencies and run `dotnet fake ...` instead of `fake ...`, see [this example](https://github.com/FakeBuild/fake-bootstrap/blob/master/dotnet-fake.csproj)
 
-* Install fake as a global dotnet tool: run `dotnet tool install fake-cli -g --version=5.0.0-*` to install fake globally or `dotnet tool install fake-cli --tool-path your_tool_path --version=5.0.0-*` to install fake into `your_tool_path`. Use `--version` to specify the version of fake. See the [`global_tool` branch of `fake-bootstrap`](https://github.com/FakeBuild/fake-bootstrap/tree/global_tool) for ideas to bootstrap in your CI process.
-<div class="alert alert-info">
-    <h5>INFO</h5>
-    <p>As FAKE 5 is still in pre-release, you have to specify the <code>--version</code> parameter.</p>
-</div>
 
 * Bootstrap via shell script (fake.cmd/fake.sh),
   see this [example project](https://github.com/FakeBuild/fake-bootstrap)

help/markdown/fake-template.md

@@ -0,0 +1,49 @@
+# Fake Template
+
+The Fake template bootstraps FAKE and sets up a basic build-script.
+
+## Installation
+
+Run 
+<pre><code class="lang-bash">
+dotnet new -i "fake-template::*"
+</code></pre>
+to install or update the template.
+
+## Usage
+After you installed the template you can setup FAKE by running:
+<pre><code class="lang-bash">
+dotnet new fake
+</code></pre>
+This will create a default `build.fsx` file, a `paket.dependencies` file used to mangage your build dependencies and two shell scripts `fake.sh` and `fake.cmd`. The shell scripts are used to bootstrap and run FAKE. All of the arguments are passed direcly to FAKE so you can run:
+<pre><code class="lang-bash">
+.\fake.cmd build
+</code></pre>
+to run your build. Have a look [this](fake-commandline.html) for the available command-line options. [This page](fake-gettingstarted.html#Example-Compiling-and-building-your-NET-application) additional information on how to use a build script.
+
+## Options
+
+### --script-name
+Specifies the name of the generated build-script. Defaults to `build.fsx`.
+
+### --bootstrap
+Specifies your prefered way to bootstrap FAKE.
+
+- `tool` (default) - Installs the FAKE dotnet sdk global tool into the `tool--path` folder
+- `project` - Creates a `build.proj` and uses `DotNetCliToolReference` to bootstrap FAKE
+- `none` - Does not bootstrap FAKE. Use this if you want to use a global installation of FAKE
+
+### --dependencies
+Specifies your prefered way to define the nuget packages used in your build:
+
+- `file` (default) - Creates a `paket.dependencies` file to define build dependencies
+- `inline` - Defines build dependencies inside the build script
+- `none` - Use this if you already have a `paket.dependencies` in your folder
+
+### --tool-path 
+Specifies the folder for the fake-cli tool. This parameter is only applicable when `tool` is used for bootstrapping. Defaults to `.fake`.
+
+### --version
+Specifies the version of FAKE to install. Defaults to `5.*`. This parameter is only applicable when either `tool` or `project` is used for bootstrapping.
+
+

help/templates/template.cshtml

@@ -54,6 +54,7 @@
                                                         <li><a href="/fake-cache.html">Build script caching</a></li>
                                                         <li><a href="/fake-commandline.html">Running FAKE from command line</a></li>
                                                         <li><a href="/fake-dotnetcore.html">FAKE 5 quickstart</a></li>
+                                                        <li><a href="/fake-template.html">FAKE Template</a></li>
                                                         <li><a href="/fake-migrate-to-fake-5.html">FAKE 5 migration</a></li>
                                                         <li><a href="/fake-debugging.html">Debugging Scripts</a></li>
                                                     </ul>

src/app/fake-template/Content/.template.config/template.json

@@ -0,0 +1,94 @@
+{
+    "identity": "Fake.Template",
+    "shortName": "fake",
+    "name": "FAKE - Template",
+    "classifications": ["build", "FAKE"],
+    "symbols": {
+        "script-name": {
+            "type": "parameter",
+            "description": "Name of the generated build-script",
+            "dataType": "string",
+            "defaultValue": "build.fsx",
+            "FileRename": "build.fsx",
+            "replaces": "(build.fsx)"
+        },
+        "bootstrap": {
+            "type": "parameter",
+            "dataType": "choice",
+            "defaultValue": "tool",
+            "choices": [{
+                    "choice": "project",
+                    "description": "Creates a build.proj file to bootstrap FAKE"
+                },
+                {
+                    "choice": "tool",
+                    "description": "Uses the FAKE dotnet sdk global tool to bootstrap FAKE. The tool is installed into 'tool--path'"
+                },
+                {
+                    "choice": "none",
+                    "description": "Does not bootstrap FAKE. Use this if you want to use a global installation of FAKE"
+                }
+            ]
+        },
+        "dependencies": {
+            "type": "parameter",
+            "dataType": "choice",
+            "defaultValue": "file",
+            "choices": [{
+                    "choice": "file",
+                    "description": "Use paket.dependencies file to define build dependencies"
+                },
+                {
+                    "choice": "inline",
+                    "description": "Define build dependencies inside the build script"
+                },
+                {
+                    "choice": "none",
+                    "description": "No dependencies are created. Use this if you already have a paket.dependencies file in your folder"
+                }
+            ]
+        },
+        "tool-path": {
+            "type": "parameter",
+            "description": "Folder for the FAKE dotnet sdk global tool. This parameter is only applicable when 'tool' is used for bootstrapping",
+            "dataType": "string",
+            "defaultValue": ".fake",
+            "replaces": "(ToolPath)"
+        },
+        "version": {
+            "type": "parameter",
+            "description": "Version of FAKE to install. This parameter is only applicable when either 'tool' or 'project' is used for bootstrapping",
+            "dataType": "string",
+            "defaultValue": "5.*",
+            "replaces": "(version)"
+        }
+    },
+    "sources": [{
+        "exclude": "**/.template.config/**/*",
+        "modifiers": [{
+                "exclude": "**/fake.tool.*",
+                "condition": "(bootstrap != \"tool\")"
+            },
+            {
+                "rename": {
+                    "fake.tool.sh": "fake.sh",
+                    "fake.tool.cmd": "fake.cmd"
+                }
+            },
+            {
+                "exclude": ["**/fake.proj.*", "**/build.proj"],
+                "condition": "(bootstrap != \"project\")"
+            },
+            {
+                "rename": {
+                    "fake.proj.sh": "fake.sh",
+                    "fake.proj.cmd": "fake.cmd"
+                }
+            },
+            {
+                "exclude": "**/paket.dependencies",
+                "condition": "(dependencies != \"file\")"
+            }
+        ]
+    }]
+}

src/app/fake-template/Content/build.fsx

@@ -0,0 +1,33 @@
+//#if (dependencies == "inline")
+#r "paket:
+    source https://api.nuget.org/v3/index.json
+    nuget Fake.DotNet.Cli
+    nuget Fake.IO.FileSystem
+    nuget Fake.Core.Target //"
+//#endif
+#load ".fake/(build.fsx)/intellisense.fsx"
+open Fake.Core
+open Fake.DotNet
+open Fake.IO
+open Fake.IO.FileSystemOperators
+open Fake.IO.Globbing.Operators
+open Fake.Core.TargetOperators
+
+Target.create "Clean" (fun _ ->
+    !! "src/**/bin"
+    ++ "src/**/obj"
+    |> Shell.cleanDirs 
+)
+
+Target.create "Build" (fun _ ->
+    !! "src/**/*.*proj"
+    |> Seq.iter (DotNet.build id)
+)
+
+Target.create "All" ignore
+
+"Clean"
+  ==> "Build"
+  ==> "All"
+
+Target.runOrDefault "All"

src/app/fake-template/Content/build.proj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFramework>netstandard2.0</TargetFramework>
+    </PropertyGroup>
+    <ItemGroup>
+        <DotNetCliToolReference Include="dotnet-fake" Version="(version)" />
+    </ItemGroup>
+</Project>

src/app/fake-template/Content/fake.proj.cmd

@@ -0,0 +1,2 @@
+dotnet restore build.proj
+dotnet fake %*

src/app/fake-template/Content/fake.proj.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -eu
+set -o pipefail
+
+dotnet restore build.proj
+dotnet fake "$@"

src/app/fake-template/Content/fake.tool.cmd

@@ -0,0 +1,7 @@
+SET TOOL_PATH=(ToolPath)
+
+IF NOT EXIST "%TOOL_PATH%\fake.exe" (
+  dotnet tool install fake-cli --tool-path ./%TOOL_PATH% --version (version)
+)
+
+"%TOOL_PATH%/fake.exe" %*

src/app/fake-template/Content/fake.tool.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -eu
+set -o pipefail
+
+TOOL_PATH=(ToolPath)
+
+if ! [ -e $TOOL_PATH/fake ] 
+then
+  dotnet tool install fake-cli --tool-path $TOOL_PATH --version (version)
+fi
+$TOOL_PATH/fake "$@"

src/app/fake-template/Content/paket.dependencies

@@ -0,0 +1,6 @@
+// [ FAKE GROUP ]
+group Build
+    source https://api.nuget.org/v3/index.json
+    nuget Fake.DotNet.Cli
+    nuget Fake.IO.FileSystem
+    nuget Fake.Core.Target

src/app/fake-template/fake-template.proj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <NeutralLanguage>en-US</NeutralLanguage>
+        <PackageType>Template</PackageType>
+        <PackProjectInputFile>$(MSBuildProjectFullPath)</PackProjectInputFile>
+        <NoBuild>true</NoBuild>
+        <IncludeBuildOutput>false</IncludeBuildOutput>
+        <TargetFramework>netstandard2.0</TargetFramework>
+        <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
+    </PropertyGroup>
+    <PropertyGroup>
+        <ExcludeFromPackage>
+        Content/packages/**/*;
+        Content/bin/**/*;
+        Content/obj/**/*;
+        Content/src/bin/**/*;
+        Content/src/obj/**/*;
+        </ExcludeFromPackage>
+    </PropertyGroup>
+    <ItemGroup>
+        <Content Include="Content/**/*" Exclude="$(ExcludeFromPackage)">
+            <PackagePath>Content\</PackagePath>
+        </Content>
+    </ItemGroup>
+</Project>