Guidance on how to get started with Cake

[gep13]

So, these are potentially some quite a naive questions but here goes...

I have been lurking around the Cake project for a while now, but I have never actually used it in anger, but I would like to change that 😸 With the recent inclusion of Mono support, I really feel that it would be a good time to start embracing it.

I have an existing open source project, namely GitReleaseManager that uses a psake script to orchestrate the build process, and I am looking for some guidance/best practices on how to get started using Cake.

I thought about asking these questions in the Gitter chat room, but then I thought that there might be too much info to put in there. If you want me to move this discussion to somewhere else, happy to do so.

Looking through my psake build script (which you can see here https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1) these are some of the main questions that I have:

• Should I be using the Cake Boostrapper to start the project?
• The CI build for GitReleaseManager is currently done using AppVeyor, and prior to making the call to psake, I inspect the AppVeyor variables to decide what psake task should be executed, as you can see here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/build.ps1#L27 Is this something that Cake has support for OOTB, or would this have to be created? If the latter, are there any samples somewhere of the best approach for doing this?
• As part of the build process, I invoke a number of exe's, for example OpenCover, NUnit, ReportGenerator, Coveralls, Coverity, etc. This is typically as simple as running the exe with some command line arguments. Am I right in saying that Cake has some "aliases" for doing this type of work? Are these exe's already supported? If not, can you provide a sample of the best approach for bootstrapping these exe's to make them Cake callable? If I were to get these exe's working with Cake, would that be a PR into the main Cake repo, or should these aliases, assuming that is the correct term, live outwith Cake? If so, is there a standard convention/naming, etc to be followed?
• Related to the above, another exe that I call is GitVersion. The main difference here is that this exe, depending on how it is invoked, returns some output to the command line, which I sometimes use within the build script, as you can see here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L421. Again, if an alias is the correct term, can this alias return the output of the called exe? And again, is there a sample of doing this?
• As part of the build process, I install a number of tools using Chocolatey. Is there a helper for doing this in Cake, in the same way that there is for calling into Nuget?
• Speaking of Nuget, what is the best approach for pushing packages to Nuget Feeds, as I do here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L421
• In my build script, I have a number of what I refer to as helper methods for creating directories, deleting folders, etc. I think I am right in saying you get these for free in Cake, but again, any samples of best practices for how to use these, and chaining these as part of build process?
• Am I right in saying that Cake can help with interfacing with AppVeyor REST API, or did I make that up? Within the build, I like to push results of failed portions of the build to the AppVeyor test section, and also to push artifacts, as shown here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L105 and here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L100 This is done using the AppVeyor PowerShell cmdlets. Does Cake already have some help in this area?
• Any help when it comes to XSL Transforms? https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L192
• Is there anything in my current build script that you think can be achieved in a better way using Cake? i.e. could the task dependencies be changed to improve the flow?

Thanks in advance!

[patriksvensson]

Hi @gep13,

This kind of feedback is extremely valuable and I really appreciate you taking the time to write this down!

It's a lot of (interesting) questions that might be good to clarify in a future blog post/tutorial/FAQ on the website.

---

1. Should I be using the Cake Boostrapper to start the project?

The bootstrapper is just for convenience, so there's no need to use it if you don't want to. I however prefer to use it since I don't want to store any binaries in the repository and it also helps me remember all command line switches, but that's just me. 😄

2. The CI build for GitReleaseManager is currently done using AppVeyor, and prior to making the call to psake, I inspect the AppVeyor variables to decide what psake task should be executed, as you can see here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/build.ps1#L27 Is this something that Cake has support for OOTB, or would this have to be created? If the latter, are there any samples somewhere of the best approach for doing this?

Yes, there's an alias for this available OOTB.

if(AppVeyor.Environment.ScheduledBuild) 
{
    // Do stuff
}

3. As part of the build process, I invoke a number of exe's, for example OpenCover, NUnit, ReportGenerator, Coveralls, Coverity, etc. This is typically as simple as running the exe with some command line arguments. Am I right in saying that Cake has some "aliases" for doing this type of work? Are these exe's already supported? If not, can you provide a sample of the best approach for bootstrapping these exe's to make them Cake callable? If I were to get these exe's working with Cake, would that be a PR into the main Cake repo, or should these aliases, assuming that is the correct term, live outwith Cake? If so, is there a standard convention/naming, etc to be followed?

Alas, only NUnit is available as an alias at the moment, but I've actually been thinking about adding support for OpenCover, ReportGenerator and Coverity. I've never used Coveralls before, but if it's a well known tool I wouldn't have anything against including it in Cake. Otherwise it can always be written as an addin.

I can write a guide how to implement a custom tool, but that will be longer than any answer I can provide here. If you want to read about aliases I've written down some basic stuff at http://cakebuild.net/docs/fundamentals/aliases. If you want to see an existing tool, I recommend to take a look at the Cake.Common.Tools namespace. Let me get back to you on this.

4. Related to the above, another exe that I call is GitVersion. The main difference here is that this exe, depending on how it is invoked, returns some output to the command line, which I sometimes use within the build script, as you can see here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L421. Again, if an alias is the correct term, can this alias return the output of the called exe? And again, is there a sample of doing this?

There is an alias in Cake that starts processes, and it also encapsulates logic for retrieving the output from the process.

IEnumerable<string> lines;
StartProcess("./program.exe", new ProcessSettings(), out lines);
var output = string.Join("\n", lines);

Should probably add an API call that returns the output as a string. Need to check with @devlead about this since he wrote it and probably knows more than I do 😄

5. As part of the build process, I install a number of tools using Chocolatey. Is there a helper for doing this in Cake, in the same way that there is for calling into Nuget?

Are you refering to the Powershell version of Chocolatey or choco.exe? I know that @SharpeRAD has written an addin to execute Powershell commands. If you mean choco.exe I would not have anything against adding support for it OOTB.

6. Speaking of Nuget, what is the best approach for pushing packages to Nuget Feeds, as I do here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L421

There is built in support for pushing packages to NuGet feeds in Cake.

// Get the path to the package.
var package = Directory("./artifacts") + File("Cake." + semVersion + ".nupkg");

// Push the package.
NuGetPush(package, new NuGetPushSettings {
    Source = "https://www.myget.org/F/cake/api/v2/package",
    ApiKey = apiKey
});

7. In my build script, I have a number of what I refer to as helper methods for creating directories, deleting folders, etc. I think I am right in saying you get these for free in Cake, but again, any samples of best practices for how to use these, and chaining these as part of build process?

Yes, I've added a lot of functionality for working with paths and the file system. Generally, all paths are represented by FilePath,DirectoryPath.FilePathCollection or DirectoryPathCollection.

var artifacts = new DirectoryPath("./artifacts");
var stuff = path.Combine(new DirectoryPath("stuff"));
var file = stuff.CombineWithFilePath(new FilePath("text.txt"));

These classes are kind of low level (for a build script), so I've also added aliases to combine them together. All functionality in Cake working with files or directories accepts a FilePath and/or DirectoryPath. Tools accepting paths also have a repsonsibility to make relative paths absolute to avoid errors.

var artifacts = Directory("./artifacts");
var stuff = artifacts + Directory("stuff");
var file = stuff + File("text.txt");

Which also can be written

var file = Directory("./artifacts/stuff") + File("text.txt");

I've also added implicit conversion operators from System.String so you can provide a string for methods that accept a FilePath or a DirectoryPath.

MethodThatAcceptsFilePath("./hello.txt");

8. Am I right in saying that Cake can help with interfacing with AppVeyor REST API, or did I make that up? Within the build, I like to push results of failed portions of the build to the AppVeyor test section, and also to push artifacts, as shown here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L105 and here: https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L100 This is done using the AppVeyor PowerShell cmdlets. Does Cake already have some help in this area?

Yes, there are methods built into Cake's utility library for doing this.

var file = File("./stuff.xml");
AppVeyor.UploadArtifact(file);

There is currently no support for reporting test results, but that wouldn't be difficult to add.

9. Any help when it comes to XSL Transforms? https://github.com/GitTools/GitReleaseManager/blob/develop/BuildScripts/default.ps1#L192

Yes! There is an alias for performing XSL transforms.

var xsl = File("./data.xsl");
var xml = File("./data.xml");
string result = XmlTransform(xsl, xml, 
    new XmlTransformationSettings() {
        // These settings have a billion options ;)
})

10. Is there anything in my current build script that you think can be achieved in a better way using Cake? i.e. could the task dependencies be changed to improve the flow?

I can take a look tomorrow after work and get back to you on this.

---

As I said before, great questions. I hope I didn't ramble too much when trying to answer them. I will get back to you about the missing tool support to see if we can find a solution 😄

/ Patrik

[gep13]

Wow! Thank you for such a detailed response, really appreciate it. Let me dissect some of it, and follow up with more 😸

@patriksvensson said...
I can take a look tomorrow after work and get back to you on this.

I would really appreciate that.

[gep13]

@patriksvensson if you have time tomorrow, some further input on this would be preferred to the CakeTest issue that I was having 😛

[patriksvensson]

@gep13 Absolutely. Sorry I've not answered this yet. Expect an answer tomorrow 😄

[patriksvensson]

@gep13,

I took some time on my lunch to convert the tasks (without content) to Cake tasks to better see how everything work together. I cannot see anything strange from the knowledge I have about your project.

https://gist.github.com/patriksvensson/b58652071427973a898b

if there's something I've forgotten about then tell me and I will answer as soon as I can.

Questions:

I see that you do a try-catch in some tasks (like ) and write some whether or not the task succeeded or failed. I see no rethrow though. Does this work as I think it do, or does psake fail the build if an error is written to stderr?

If you want to catch all errors you could either use a regular try-catch in the cake script as well, or use the HandleError task extension.

What I changed:

• I've added a constraint to the __EchoAppVeyorEnvironmentVariables task to not run if Cake isn't running on AppVeyor.
• Added the directories at the beginning of the script. This is to minimize the errors that might come with path manipulation in the tasks. I also output all paths as part as a task called "Show-Info". This is just for debugging purposes (and demonstration) and not crucial in any way. All tools supported by cake will make the provided path absolute, so you don't have to think about that. If you want to display the full path simply wrap the path in a MakeAbsolute call.

Optional things that can be done:

Well, everything I've written is optional, this is just more optional 😄
The build script becomes kind of large, so you could divide them into several one for brevity.

• build.cake
• private-tasks.cake

and then load them with the #load directive.

#load "private-tasks.cake"

[patriksvensson]

@gep13: Was this helpful? Anything else you need answer to?

[gep13]

@patriksvensson this was more than enough information! Couldn't have asked for much more! Thanks!