What is it?
One of these extension points is the registration of IPackageInstaller's, which deal with installing tools and addins during the Cake Script execution. The DotNet Tool Module utilizes this extension point to allow tools to be resolved using the DotNet CLI, specifically, the
dotnet tool command.
dotnet tool command deals with the installation of tools. As a result, it only makes sense for this module to deal with tools, and not addins.
Why is this needed?
Out of the box, Cake has the ability to install tools and addins from any NuGet source. This is documented on the Cake Website. Recently, Larz White showed how it was possible to use an alternative package manager, namely Paket to install those tools and addins.
However, there are a growing number of tools that can be installed as Global DotNet Tools (there is a list of these compiled here by Nate McMaster). Cake itself, is actually published as a DotNet Global Tool. As part of your build process, you might want to have these tools installed, ready to be used. However, what I want to be able to do is to define the installation of these tools in the same way as I do my other tools and addins, so that everything is in the same place. For example, I want to put them right here:
/////////////////////////////////////////////////////////////////////////////// // TOOLS /////////////////////////////////////////////////////////////////////////////// #tool nuget:?package=coveralls.io&version=1.3.4 #tool nuget:?package=gitreleasemanager&version=0.5.0 #tool nuget:?package=GitVersion.CommandLine&version=3.6.2 #tool nuget:?package=JetBrains.ReSharper.CommandLineTools&version=2016.3.20161223.160402 #tool nuget:?package=ReSharperReports&version=0.2.0 #tool nuget:?package=KuduSync.NET&version=1.3.1 #tool nuget:?package=Wyam&version=0.16.1 #tool nuget:?package=gitlink&version=2.4.1 #tool nuget:?package=MSBuild.Extension.Pack&version=1.9.0
Along with all the other tools that I use in my build.
And that is what this Cake Module allows you to do. You can now add the following:
Which would install version 4.41.0 of the Octopus.DotNet.Cli package.
NOTE: What is different here is that
dotnet is being used, rather than
nuget. This is what causes Cake to defer to the DotNet Tool Module, rather than using NuGet to resolve the tool installation.
Due to the fact that Cake Modules are extending and altering the internals of the Cake, the Module Assembly needs to be loaded prior to the main Cake execution. As documented in the Module section of this page, you simply have to do the following:
./build.sh --bootstrap ./build.sh
This means that the first execution of Cake will inspect your Cake script for any module inclusions in your script, and if there are any, download and install them. And the second execution will then be able to use those modules, and complete the usage of the module.
An example of a Cake script which both includes the module definition for the DotNet Tool Module, and which also uses it, is shown below:
#module nuget:?package=Cake.DotNetTool.Module&version=0.1.0 #tool "dotnet:?package=Octopus.DotNet.Cli&version=4.41.0"
As mentioned above, installing a tool using the DotNet Tool Module is as simple as:
If the tool in question comes from a different source, you can change that as follows:
By default, the DotNet Tool Module will install a tool to the location of the defined Cake Tools folder (this is normally simply a
tools folder located beside the Cake Script that is being executed). It is possible to control the location of this tools folder in the normal way, and additionally, you can opt to install the DotNet Tool globally using:
Additional parameters that can be passed to the pre-processor directive include:
- Specifies which NuGet config file should be used during the execution
- Specifies the target framework to install the tool for. By default, the .NET Core SDK tries to choose the most appropriate target framework.
Finally, you can control the logging verbosity of the underlying
dotnet tool command by altering the overall verbosity of the Cake Script execution. i.e. running:
will cause the
dotnet tool command to be ran with diagnostic verbosity as well.
The parameters that can be used in this pre-processor directive come from the documentation which is available here.
You can find additional documentation for this module here:
The source code for this Module can be found here:
If you have any questions about this Module, then please feel to drop into the Gitter Chat room for all the addins and modules which exist in the cake-contrib organisation on GitHub:
Other Cake Modules
There are a number of other Cake Modules that perform similar functionality for other Package Managers, for example:comments powered by Disqus