Release 5.9

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,8 +8,14 @@ If available, link to an existing issue this PR fixes. For example:
 
 ## TODO
 
+Feel free to open the PR and ask for help
+
 - [] New (API-)documentation for new features exist (Note: API-docs are enough, additional docs are in `help/markdown`)
 - [] unit or integration test exists (or short reasoning why it doesn't make sense)
+
+ > Note: Consider using the `CreateProcess` API which can be tested more easily, see https:/fsharp/FAKE/pull/2131/files#diff-4fb4a77e110fbbe8210205dfe022389b for an example (the changes in the `DotNet.Testing.NUnit` module)
+
+- [] boy scout rule: "leave the code behind in a better state than you found it" (fix warnings, obsolete members or code-style in the places you worked in) 
 - [] (if new module) the module has been linked from the "Modules" menu, edit `help/templates/template.cshtml`, linking to the API-reference is fine.
 - [] (if new module) the module is in the correct namespace
 - [] (if new module) the module is added to Fake.sln (`dotnet sln Fake.sln add src/app/Fake.*/Fake.*.fsproj`)

.gitlab-ci.yml

@@ -18,6 +18,7 @@ do_build:
 
  variables:
  TERM: "xterm-256color"
+ FAKE_DETAILED_ERRORS: "true"
  MSBUILDDISABLENODEREUSE: "1"
  BuildInParallel: "false"
  LANG: "C"

.travis.yml

@@ -3,7 +3,7 @@ sudo: required
 dist: trusty # Ubuntu 14.04
 dotnet : 2.1.402
 env:
- - HOME=/home/travis APPDATA=/home/travis LocalAppData=/home/travis
+ - FAKE_DETAILED_ERRORS=true HOME=/home/travis APPDATA=/home/travis LocalAppData=/home/travis
 
 
 before_install:

.vscode/launch.json

@@ -4,17 +4,20 @@
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
+
  {
  "name": "Debug Build Script",
  "type": "coreclr",
  "request": "launch",
- "preLaunchTask": "dotnet:build:fake.sln",
+ "preLaunchTask": "dotnet:build:fake-netcore.fsproj",
  "program": "${workspaceRoot}/src/app/Fake.netcore/bin/Debug/netcoreapp2.1/fake.dll",
  "args": [
  "run",
- "build.fsx",
  "--fsiargs",
- "--debug:portable --optimize-"
+ "--debug:portable --optimize-",
+ "build.fsx",
+ "-st",
+ "DownloadPaket"
  ],
  "cwd": "${workspaceRoot}",
  "stopAtEntry": false,

.vscode/tasks.json

@@ -26,6 +26,29 @@
  "dotnet:restore:fake.sln"
  ]
  },
+ {
+ "label": "dotnet:restore:fake-netcore.fsproj", 
+ "group": "build",
+ "command": "dotnet restore src/app/Fake.netcore/Fake.netcore.fsproj",
+ "type": "shell",
+ "presentation": {
+ "reveal": "always"
+ },
+ "problemMatcher": "$msCompile"
+ },
+ {
+ "label": "dotnet:build:fake-netcore.fsproj", 
+ "group": "build",
+ "command": "dotnet build src/app/Fake.netcore/Fake.netcore.fsproj",
+ "type": "shell",
+ "presentation": {
+ "reveal": "always"
+ },
+ "problemMatcher": "$msCompile",
+ "dependsOn": [
+ "dotnet:restore:fake-netcore.fsproj"
+ ]
+ },
  {
  "label": "dotnet:run:unitTests", 
  "group": "test",

RELEASE_NOTES.md

@@ -1,5 +1,21 @@
 # Release Notes
 
+## 5.9.0 - 2018-10-13
+
+* ENHANCEMENT: Write NUnit arguments to an arguments file, fixes problems with long command lines - https:/fsharp/FAKE/pull/2114
+* ENHANCEMENT: Added `SpecFlowNext` module to `Fake.DotNet.Testing.SpecFlow` with improved API and missing arguments - https:/fsharp/FAKE/pull/2143
+* ENHANCEMENT (BREAKING): Updated and finalized the new (and undocumented) process API which is more unit-testable - https:/fsharp/FAKE/pull/2131 
+* ENHANCEMENT: Updated `Fake.Testing.ReportGenerator` to include `ClassFilter` and `FileFilter` - https:/fsharp/FAKE/pull/2120
+* ENHANCEMENT: Improve TeamCity integrations - https:/fsharp/FAKE/pull/2138
+* ENHANCEMENT: Update `Fake.Tools.Pickles` to include latest CLI additions - https:/fsharp/FAKE/pull/2133
+* ENHANCEMENT: The `Trace` module can now report build-state with a message - https:/fsharp/FAKE/pull/2139
+* ENHANCEMENT: The target module not supports a `Trace.WithContext` mode to retrieve the context and handle potenial problems manually - https:/fsharp/FAKE/pull/2140
+* ENHANCEMENT: The target module now allows to set the build-state by using the new `WithContext`-mode - https:/fsharp/FAKE/pull/2141
+* BUGFIX: Fix TeamCity (named) Artifact upload - https:/fsharp/FAKE/pull/2147
+* BUGFIX: AppVeyor module should not trace `appveyor.exe` calls - https:/fsharp/FAKE/pull/2137
+* BUGFIX: Always print the stack-trace when in verbose mode - https:/fsharp/FAKE/issues/2136
+* DOCUMENTATION: Some smaller fixes
+
 ## 5.8.5 - 2018-10-10
 
 * BUGFIX: PATH Variable was overwritten when using the `DotNet.Cli` module - https:/fsharp/FAKE/issues/2134

build.fsx

@@ -141,7 +141,11 @@ let chocoVersion =
  failwithf "%s" msg
  result
 
-Trace.setBuildNumber nugetVersion
+match TeamFoundation.Environment.SystemPullRequestIsFork with
+| None | Some false ->
+ Trace.setBuildNumber nugetVersion
+| _ ->
+ Trace.traceFAKE "Not setting buildNumber to '%s', because of https://developercommunity.visualstudio.com/content/problem/350007/build-from-github-pr-fork-error-tf400813-the-user-1.html" nugetVersion
 
 let dotnetSdk = lazy DotNet.install DotNet.Versions.FromGlobalJson
 let inline dtntWorkDir wd =

help/markdown/core-process.md

@@ -5,28 +5,162 @@
  <p>This documentation is for FAKE version 5.0 or later.</p>
 </div>
 
-[API-Reference](apidocs/v5/fake-core-process.html)
+[API-Reference CreateProcess](apidocs/v5/fake-core-createprocess.html)
+[API-Reference Proc](apidocs/v5/fake-core-proc.html)
+[API-Reference Process](apidocs/v5/fake-core-process.html)
+
+## Just start a process
+
+You can either use a list of arguments:
+
+```fsharp
+
+CreateProcess.fromRawCommand "./folder/mytool.exe" ["arg1"; "arg2"]
+|> Proc.run // start with the above configuration
+|> ignore // ignore exit code
+
+// Or
+
+[ "arg1"; "arg2"
+ "arg3" ]
+|> CreateProcess.fromRawCommand "./folder/mytool.exe"
+|> CreateProcess.withWorkingDirectory "./folder"
+|> Proc.run
+|> ignore
+
+```
+
+Or a properly escaped command line:
+
+```fsharp
+
+CreateProcess.fromRawWindowsCommandLine "./folder/mytool.exe" "arg1 arg2 arg3"
+|> Proc.run // start with the above configuration
+|> ignore // ignore exit code
+
+```
+
+## Evaluate exit code
+
+The most obvious way is:
+
+```fsharp
+let result =
+ [ "arg1"; "arg2"; "arg3" ]
+ |> CreateProcess.fromRawCommand "./folder/mytool.exe"
+ |> Proc.run
+
+if result.ExitCode <> 0 then failwith "Command failed"
+
+```
+
+To simplify your life you can "embed" the return code check into the `CreateProcess` instance (which allows to pass the instance through your application and fail appropriately):
+
+```fsharp
+
+[ "arg1"; "arg2"; "arg3" ]
+|> CreateProcess.fromRawCommand "./folder/mytool.exe"
+|> CreateProcess.ensureExitCode // will make sure to throw on error
+|> Proc.run
+|> ignore
+
+// The above is roughly equivalent to the following (which you can copy and edit to customize):
+
+[ "arg1"; "arg2"; "arg3" ]
+|> CreateProcess.fromRawCommand "./folder/mytool.exe"
+|> CreateProcess.addOnExited (fun data exitCode ->
+ if exitCode <> 0 then
+ // TODO: throw your own exception here
+ failwithf "Process exit code '%d' <> 0. Command Line: %s" exitCode r.CommandLine
+ else
+ data)
+|> Proc.run
+|> ignore
+
+```
+
+## Different ways to "run" or "start"
+
+The basic difference between "start" and "run" is:
+
+- "start" starts the process and returns after the process is started. This usually means the process is still running.
+- "run" waits for the started process to exit and returns the result. 
+
+The different ways to start or run a process are documented [here](/apidocs/v5/fake-core-proc.html).
 
 ## Running a command and analyse results
 
+Whatever processing option you choose in all cases you need to start process redirection:
+
 ```fsharp
+let result =
+ CreateProcess.fromRawCommand "./folder/mytool.exe" ["arg1"; "arg2"]
+ |> CreateProcess.redirectOutput
+ |> Proc.run
+```
 
-let fakeToolPath = "known/path/to/fake.exe"
-let directFakeInPath command workingDir target =
- let result =
- Process.execWithResult (fun (info:ProcStartInfo) ->
- { info with
- FileName = fakeToolPath
- WorkingDirectory = workingDir
- Arguments = command }
- |> Process.setEnvironmentVariable "target" target) (System.TimeSpan.FromMinutes 15.)
- if result.ExitCode <> 0 then
- let errors = String.Join(Environment.NewLine,result.Errors)
- printfn "%s" <| String.Join(Environment.NewLine,result.Messages)
- failwithf "FAKE Process exited with %d: %s" result.ExitCode errors
- String.Join(Environment.NewLine,result.Messages)
+This immediately changes the type of `result`, now you can access the output:
 
-let output = directFakeInPath "--version" "." "All"
+```fsharp
+if result.ExitCode <> 0 then
+ printfn "%s" result.Result.Output
+ failwithf "FAKE Process exited with %d: %s" result.ExitCode result.Result.Error
+let output = result.Result.Output
+// Parse output?
+```
+
+But even better you can make the 'process-call' type safe for others, by parsing the output:
+
+```fsharp
+
+type MySafeOutput = // ...
+let parseOutput (r:ProcessResult<ProcessOutput>) : MySafeOutput =
+ // use r.Result.Output, r.ExitCode and create MySafeOutput
+let startProcess () (*args*)=
+ CreateProcess.fromRawCommand "./folder/mytool.exe" ["arg1"; "arg2"]
+ |> CreateProcess.redirectOutput
+ |> CreateProcess.ensureExitCode // optional, if your parse function can handle output from failures as well
+ |> CreateProcess.map parseOutput
+
+// Usage:
+let myOutput : MySafeOutput =
+ startProcess()
+ |> Proc.run
 
 ```
 
+Additionally sometimes you need/want asynchronous results to have intermediate results.
+For example if you want that the user continuously "sees" the output as the process generates it:
+
+```fsharp
+
+let output =
+ CreateProcess.fromRawCommand "./folder/mytool.exe" ["arg1"; "arg2"]
+ |> CreateProcess.redirectOutput
+ |> CreateProcess.withOutputEventsNotNull Trace.trace Trace.traceError
+ |> Proc.run
+
+// "process" output
+```
+
+## Advanced usage scenarios
+
+
+Redirect output from one process `outgen.exe` to `processIn.exe`:
+
+
+```fsharp
+
+let input = StreamRef.Empty
+let p1 =
+ CreateProcess.fromRawCommand "processIn.exe" []
+ |> CreateProcess.withStandardInput (CreatePipe input)
+ |> Proc.start
+
+let p2 =
+ CreateProcess.fromRawCommand "outgen.exe" []
+ |> CreateProcess.withStandardOutput (UseStream(false, input.Value))
+ |> Proc.run
+
+
+```

help/markdown/core-targets.md

@@ -126,6 +126,44 @@ Everything after the target will be interpreted as argument for the target:
 
 You can access the arguments from every target executed along the way.
 
+## Setting build status
+
+You can set the build status automatically using `Target.updateBuildStatus`. To do this you need to use the `Target.WithContext` functions to run a target and retrieve the context information:
+
+Example: 
+
+```fsharp
+#r "paket:
+nuget Fake.Core.Target //"
+
+open Fake.Core
+
+// *** Define Targets ***
+Target.create "Clean" (fun p ->
+ Trace.trace " --- Cleaning stuff --- "
+)
+
+Target.create "Build" (fun _ ->
+ Trace.trace " --- Building the app --- "
+)
+
+Target.create "Deploy" (fun _ ->
+ Trace.trace " --- Deploying app --- "
+)
+
+open Fake.Core.TargetOperators
+
+// *** Define Dependencies ***
+"Clean"
+ ==> "Build"
+ ==> "Deploy"
+
+// *** Start Build ***
+let ctx = Target.WithContext.runOrDefault "Deploy"
+Target.updateBuildStatus ctx
+Target.raiseIfError ctx // important to have proper exit code on build failures.
+```
+
 ## Final targets
 
 Final targets can be used for TearDown functionality.

help/markdown/fake-dotnet-testing-specflow.md

@@ -11,9 +11,48 @@ SpecFlow is open source and provided under a BSD license. As part of the Cucumbe
 
 The package Fake.DotNet.Testing.SpecFlow is a bridge to the [SpecFlow] CLI (specflow.exe).
 
+**If you use SpecFlow in a version >= 2.4, then please use the SpecFlowNext module**
+
 [API-Reference](https://fake.build/apidocs/v5/fake-dotnet-testing-specflow.html)
 
-## Minimal working example
+## Minimal working example (v2.4+)
+
+```fsharp
+#r "paket:
+nuget Fake.Core.Target
+nuget Fake.DotNet.Testing.SpecFlow //"
+
+open Fake.Core
+open Fake.DotNet.Testing
+
+let specsProject = "IntegrationTests.csproj"
+
+Target.create "Regenerate Test Classes" (fun _ ->
+ specsProject |> SpecFlowNext.run id
+)
+
+Target.create "Create StepDefinition Report" (fun _ ->
+ specsProject
+ |> SpecFlowNext.run (fun p ->
+ { p with 
+ SubCommand = StepDefinitionReport
+ BinFolder = Some "bin/Debug"
+ OutputFile = Some "StepDefinitionReport.html" })
+)
+
+Target.create "Default" Target.DoNothing
+
+"Clean"
+==> "Regenerate Test Classes"
+==> "Build"
+==> "Run Integration Tests"
+==> "Create StepDefinition Report"
+==> "Default"
+
+Target.runOrDefault "Default"
+```
+
+## Minimal working example (pre v2.4)
 
 ```fsharp
 #r "paket: