Addin vs Tool

[mgnslndh]

I've been thinking a bit about addins and tools and have some random questions about them. Hopefully some can help me sort this out :)

What is the difference between an "addin" and a "tool"?

It seems to me that tools need not specifically be created for Cake but can be any NuGet package (or dotnet cli package) that will be downloaded and "installled". Executables delivered as part of the tool can be resolved and executed from Cake. Cake does not load any assemblies from tools.

Addins are of course also NuGet packages but assemblies in the lib folder will be loaded and their Cake aliases can be used from scripts. In Cake Frosting the equivalent of #addin is a <PackageReference>.

Did I get that mostly right?

Addins and Cake Frosting

1. Some addins are wrappers for executables and the executables need to be installed as tools.
2. Some addins contain the executable and do not require a separate tool to be installed.

How are the executables (tools) resolved for the second kind of addin in the context of Cake Frosting? Does Cake have support for resolving tools from the user's NuGet cache where they most likely will end up when using Cake Frosting?

Is the second case even "good practice" or common?

Documentation

Tools are not mentioned in the documentation about extending Cake. Wouldn't it make sense to have at least a pointer from "Extending Cake" to the section about tools in "Writing builds"?

[augustoproiete]

You got it right. We have documentation about tools and also how tool resolution works.

The #tool directive and the equivalent InstallTool in Frosting, downloads a NuGet package, expands it on disk and scan the files in the package, making them available to the Cake build (and addins) for easy lookup via tool resolution.

The #addin directive and the equivalent of PackageReference in Frosting, downloads a NuGet package, expands it on disk, scan the files for assemblies, and then loads them into the process.

Tool

If you have a NuGet package MyPackage that contains a tool MyTool.exe and you want to execute MyTool.exe you would do something like this:

#addin "nuget:?package=MyPackage&version=1.2.3"

var myToolExePath = Context.Tools.Resolve("MyTool.exe");

StartProcess(myToolExePath, new ProcessSettings
{
    Arguments = new ProcessArgumentBuilder()
        .Append("some argument")
});

Context.Tools.Resolve works for other files too that came with the package, so you can locate other files Context.Tools.Resolve("SomeFileInMyPackage.dll").

Addin

Addins can provide functionality by exposing aliases that simplify the execution of C# code that you would normally have to write it yourself (e.g. Cake.FileHelpers) or provide aliases that make it easier to execute command-line tools (e.g. Cake.7zip) using strongly-typed classes and IntelliSense, so that you don't have to do the manual and loosely-typed StartProcess above yourself.

In general, addins that are built with the purpose of wrapping command-line tools (such as Cake.7zip)) should not ship executables with it and should rely on tool resolution instead to find the right tool to run.

This allows a nice separation between tool version and addin version, where new versions of the tool can be used without having to release new versions of the Cake addin every time.

It also allows for different scenarios like:

1. All the tools are pre-installed on the build node or come pre-installed in a Docker image - in this case, if the addin ships with the .exe it's a waste of bandwidth and disk given that you'll use the pre-installed tool in the image

2. You have a more complex build scenario where different steps of the process rely on tools to be present, and you only need to install the tools once, at the start. e.g.

• dotnet cake step1.cake (includes a bunch of #tools directive to install them)
• dotnet cake step2.cake (uses some of the tools installed in step1)
• powershell step3.ps1 (uses some of the tools installed in step1)
• python step4.py (uses some of the tools installed in step1)
• dotnet cake step5.cake (uses some of the tools installed in step1)
• etc... You get the idea

[nils-a]

In addition to what Augusto wrote, I'd like to add:

Is the second case even "good practice" or common?

I have not seen this often, so I would not think it common. Also, I personally would not think it "good practice".