diff --git a/docs/recipes/build/add-build-script.md b/docs/recipes/build/add-build-script.md new file mode 100644 index 00000000..1d7489ed --- /dev/null +++ b/docs/recipes/build/add-build-script.md @@ -0,0 +1,121 @@ +# How do I add build automation to the project? + +## FAKE +[Fake](https://fake.build/) is a DSL for build tasks that is modular, extensible and easy to start with. Fake allows you to easily build, bundle, deploy your app and more by executing a single command. + +> The standard template comes [with a FAKE project](../../../template-safe-commands) by default, so **this recipe only applies to the minimal template**. + +--- +#### 1. Create a build project + +Create a new console app called 'Build' at the root of your solution + +```fsharp +dotnet new console -lang f# -n Build -o . +``` + +> We are creating the project directly at the root of the solution in order to allow us to execute the build without needing to navigate into a subfolder. + +#### 2. Create a build script + +Open the project you just created in your IDE and rename the module it contains from `Program.fs` to `Build.fs`. + +This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really. + +> If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well + +Open `Build.fs` and paste in the following code. + +```fsharp +open Fake.Core +open Fake.IO +open System + +let redirect createProcess = + createProcess + |> CreateProcess.redirectOutputIfNotRedirected + |> CreateProcess.withOutputEvents Console.WriteLine Console.WriteLine + +let createProcess exe arg dir = + CreateProcess.fromRawCommandLine exe arg + |> CreateProcess.withWorkingDirectory dir + |> CreateProcess.ensureExitCode + +let dotnet = createProcess "dotnet" + +let npm = + let npmPath = + match ProcessUtils.tryFindFileOnPath "npm" with + | Some path -> path + | None -> failwith "npm was not found in path." + createProcess npmPath + +let run proc arg dir = + proc arg dir + |> Proc.run + |> ignore + +let execContext = Context.FakeExecutionContext.Create false "build.fsx" [ ] +Context.setExecutionContext (Context.RuntimeContext.Fake execContext) + +Target.create "Clean" (fun _ -> Shell.cleanDir (Path.getFullName "deploy")) + +Target.create "InstallClient" (fun _ -> run npm "install" ".") + +Target.create "Run" (fun _ -> + run dotnet "build" (Path.getFullName "src/Shared") + [ dotnet "watch run" (Path.getFullName "src/Server") + dotnet "fable watch --run npx vite" (Path.getFullName "src/Client") ] + |> Seq.toArray + |> Array.map redirect + |> Array.Parallel.map Proc.run + |> ignore +) + +open Fake.Core.TargetOperators + +let dependencies = [ + "Clean" + ==> "InstallClient" + ==> "Run" +] + +[] +let main args = + try + match args with + | [| target |] -> Target.runOrDefault target + | _ -> Target.runOrDefault "Run" + 0 + with e -> + printfn "%A" e + 1 +``` + +#### 3. Add the project to the solution + +Run the following command + +```bash +dotnet sln add Build.fsproj +``` +#### 4. Installing dependencies + +You will need to install the following dependencies: + +``` +Fake.Core.Target +Fake.IO.FileSystem +``` + +We recommend migrating to [Paket](https://fsprojects.github.io/Paket/). +It is possible to use FAKE without Paket, however this will not be covered in this recipe. + +#### 5. Run the app + +At the root of the solution, run `dotnet paket install` to install all your dependencies. + +If you now execute `dotnet run`, the default target will be run. This will build the app in development mode and launch it locally. + +To learn more about targets and FAKE in general, see [Getting Started with FAKE](https://fake.build/guide/getting-started.html#Minimal-Example). + diff --git a/docs/v4-recipes/build/add-build-script.md b/docs/v4-recipes/build/add-build-script.md index ff6c14dc..babdc51d 100644 --- a/docs/v4-recipes/build/add-build-script.md +++ b/docs/v4-recipes/build/add-build-script.md @@ -20,7 +20,7 @@ dotnet new console -lang f# -n Build -o . Open the project you just created in your IDE and rename the module it contains from `Program.fs` to `Build.fs`. -This renaming is't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really. +This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really. > If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well diff --git a/mkdocs.yml b/mkdocs.yml index f8a984dc..699e7407 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ nav: - Upgrade from V4 to V5: "recipes/upgrading/v4-to-v5.md" - Create a new Recipe: "recipes/template.md" - Build: + - Add build automation: "recipes/build/add-build-script.md" - Create a docker image: "recipes/build/docker-image.md" - Remove FAKE: "recipes/build/remove-fake.md" - Package my SAFE app for deployment: "recipes/build/bundle-app.md"