I wrote this article right after I successfully created my first FlubuCore build script. So this article is for beginners, and it won't show you anything advanced. (Last update: 2020-5-27)
When I found FlubuCore, just like I found new flavors of instant noodles at supermarkets, I always want to try them. So here I am.
FlubuCore means Fluent Builder Core. You can tell from the name that it's a build system with fluent API calls, and it supports .NET Core.
While FlubuCore also support "traditional" .NET Framework, I only care about .NET Core. So I will focus on .NET Core in this article. You can find more information about .NET Framework support from FlubuCore document.
OK! Here we go.
👉 I was using v5.1.8 in this article.
After the global tool is installed, you can run your build script from command line.
Reminder: when you update FlubuCore packages from your build project, don't forget to update this global tool as well. You can use the following command to update it:
Now open your solution in Visual Studio, and add a new project with Class Library (.NET Core) template. Use "Build" as the project name, and place it under the root of your repository. The following figure shows a directory layout I preferred:
Expand folders a little bit, it looks like:
(root)
+ build
build.csproj
BuildScript.cs
+ source
- BuildAll.sln
+ MyApp
+ ClassLibrary1
+ doc
+ output
In which "output" folder is for build output, and it will be created during build process. Usually we add "output" to the ignore list of a Git repository.
You can also place your build project under "source" directory. No matter how you structure your project folders, the important thing is to make sure FlubuCore can find your build script and solution file.
After the build project is created, you need to add FlubuCore package reference to it.
👉 It was v4.3.7 when I started this article, and then updated to v5.1.8. You can check "Include prerelease" if you want some new features.
Now add a class named "BuildScript". You can paste the following code sample to your "BuildScript.cs" file:
This build script provides three targets:
The
It's worth to mention that, usually we don't need to specify output directory for a "build" task ("
Once your build script is ready, make sure it compiles with no errors, then you can move on to the next step and run your build script with flubu command line tool.
In which "
The build process looks like:
Note there are messages telling you FlubuCore has found your build script file 'build/BuildScript.cs' and that it will use it. As mentioned earlier, if you follow FlubuCore's conventions for naming and file location, things will be easier.
The official document has a list of default (automatic searched) files and directory names, shown as below (the item with bold and colorful font is my preference):
FlubuCore command line tool has an option to help you create .flubu file, simply type
After you answered questions and closed the program, you can find a ".flubu" file created at current directory. The content of .flubu file looks like:
Despite the content of .flubu file is pretty simple, it can make your life a lot easier. Specifically, when FlubuCore starts to run a build script, it searches .flubu file automatically, and it keeps searching it all the way up through parent directories until that file is found or reached the root directory of current drive. The location where a .flubu file is found will be used as the "work directory" during a build process, and a correct "work directory" is crucial for us to use relative path in our build scripts. You don't want to move your build scripts to other machines only to see them failed because some files are not found.
I hope this article can help you get started with FlubuCore. Enjoy!
If you like it, don't forget to give it a "star" on GitHub.
For more information, see FlubuCore online document.
💬 If you'd like to read Chinese version, here is the link: FlubuCore 入門：建置 .NET Core 專案
💬 Thanks to Marko Zorec (author of FlubuCore) for fixing grammar errors and typos.
Why FlubuCore?
About two years ago, I wrote two articles about using Nuke, which is an open-source build automation system. Since then, I've used Nuke to build my .NET projects.When I found FlubuCore, just like I found new flavors of instant noodles at supermarkets, I always want to try them. So here I am.
FlubuCore means Fluent Builder Core. You can tell from the name that it's a build system with fluent API calls, and it supports .NET Core.
While FlubuCore also support "traditional" .NET Framework, I only care about .NET Core. So I will focus on .NET Core in this article. You can find more information about .NET Framework support from FlubuCore document.
OK! Here we go.
Installation
You can use the following command to install FlubuCore global tool:dotnet tool install --global FlubuCore.Tool
👉 I was using v5.1.8 in this article.
After the global tool is installed, you can run your build script from command line.
Reminder: when you update FlubuCore packages from your build project, don't forget to update this global tool as well. You can use the following command to update it:
dotnet tool update --global flubucore.toolAdding Build Script Project
One thing I like FlubuCore (and Nuke) is that we can write our build script with C#, just like what we do as usual. So the first step is adding a new project to your .NET solution, and it will be the "build project" for building your .NET solution.p.s. FlubuCore provides a project template that can help you create a build script. However, I prefer to do it "by hand" at the first time.While creating your build project, it's suggested that you follow conventions and name it build, Build, or _Build , and place it under your root of repository or source folder. Following conventions can save you some time and troubles. (There will be a list of common names later.）
Now open your solution in Visual Studio, and add a new project with Class Library (.NET Core) template. Use "Build" as the project name, and place it under the root of your repository. The following figure shows a directory layout I preferred:
Expand folders a little bit, it looks like:
(root)
+ build
build.csproj
BuildScript.cs
+ source
- BuildAll.sln
+ MyApp
+ ClassLibrary1
+ doc
+ output
In which "output" folder is for build output, and it will be created during build process. Usually we add "output" to the ignore list of a Git repository.
You can also place your build project under "source" directory. No matter how you structure your project folders, the important thing is to make sure FlubuCore can find your build script and solution file.
After the build project is created, you need to add FlubuCore package reference to it.
👉 It was v4.3.7 when I started this article, and then updated to v5.1.8. You can check "Include prerelease" if you want some new features.
Now add a class named "BuildScript". You can paste the following code sample to your "BuildScript.cs" file:
This build script provides three targets:
clean: To clean output directory (line 36 to 39).compile: To compile the solution (line 41 to 44). The product version is also specified with an text file ProductVersion.txt that contains one line of text indicating your product version, for example "1.3.2.0."publish: To publish the application (line 46 to 50).
The dependencies between these targets are specified with Depends method. In this example,
publish depends on compile, and compile depends on clean. That means when you run a "publish" build, clean will be executed first, then compile, and then publish.The
BuildConfiguration property is assigned to "Release" (line 25), which corresponds to a configuration stored in Visual Studio's Configuration Manager window.It's worth to mention that, usually we don't need to specify output directory for a "build" task ("
compile" target in the above example). By default, compiled binaries (.exe and .dll files) will be generated at project's bin/debug/[target-framework]/ folder, and it's suggested that we stick to that default behavior. On the other hand, while doing deploy, pack, or publish tasks, that's when we want to specify an output directory.Once your build script is ready, make sure it compiles with no errors, then you can move on to the next step and run your build script with flubu command line tool.
Run Your Build Script
Open console (command line) window, change current directory to the root of your repository, then enter the following command to run your build script:flubu compileIn which "
compile" is the target name corresponding to the string passed to CreateTarget method in BuildScript.cs shown earlier (line 40).The build process looks like:
Note there are messages telling you FlubuCore has found your build script file 'build/BuildScript.cs' and that it will use it. As mentioned earlier, if you follow FlubuCore's conventions for naming and file location, things will be easier.
The official document has a list of default (automatic searched) files and directory names, shown as below (the item with bold and colorful font is my preference):
- Build.cs
- BuildScript.cs
- DeployScript.cs
- DeploymentScript.cs
- _Build/Build.cs
- _Build/BuildScript.cs
- Build/Build.cs
- Build/BuildScript.cs
- _BuildScript/BuildScript.cs
- _BuildScripts/BuildScript.cs
- BuildScript/BuildScript.cs
- buildscript/deployscript.cs
- buildscripts/buildscript.cs
- buildscripts/deployscript.cs
- BuildScript/DeploymentScript.cs
- BuildScripts/DeploymentScript.cs
Using .flubu File
If FlubuCore couldn't find your build script files due to whatever reasons, you can tell FlubuCore where they are with a simple text file. Specifically, you create a text file named ".flubu" and place it under the root directory of your repository. In that file, you explicitly specify both of your build script file (.cs) and project file (.csproj) with relative paths.FlubuCore command line tool has an option to help you create .flubu file, simply type
flubu setup and answer questions, shown as the figure below:
After you answered questions and closed the program, you can find a ".flubu" file created at current directory. The content of .flubu file looks like:
build/BuildScript.csbuild/build.csproj
Despite the content of .flubu file is pretty simple, it can make your life a lot easier. Specifically, when FlubuCore starts to run a build script, it searches .flubu file automatically, and it keeps searching it all the way up through parent directories until that file is found or reached the root directory of current drive. The location where a .flubu file is found will be used as the "work directory" during a build process, and a correct "work directory" is crucial for us to use relative path in our build scripts. You don't want to move your build scripts to other machines only to see them failed because some files are not found.
👉 Bottom line: Use .flubu file and avoid full path (absolute path) in your build scripts.
I hope this article can help you get started with FlubuCore. Enjoy!
If you like it, don't forget to give it a "star" on GitHub.
For more information, see FlubuCore online document.