Repository files navigation

Standing on the shoulders of giants, zarro is a zero- or low-conf orchestration for(primarily) dotnet/.NET build and test (eg at CI), but it's also so much more - sinceit's easy to add your own tasks, you can use zarro for whatever you like, but if you'relooking for CI build / test / coverage* for dotnet/.NET, this might be what you're lookingfor.

(* coverage works well for NUnit / .NET Framework, but I haven't found a nice processfor dotnet core - yet)

Zarro wraps msbuild, usinggulp orchestration under the hood. It does, however,take away the pain of:

• knowingwhere msbuild lives (since it consumesgulp-msbuild
• being able to use a specific version of msbuild (again, thanks togulp-msbuild)
• running tests viadotnet test or via the NUnit CLI runner, as appropriate
• running coverage reporting (.NET Framework) via OpenCover
• downloading local variants of tooling required for the above so that your CI serverdoesn't have to have them installed, or kept up to date
  • note: zarro will not download msbuild tooling, but should work fine with anyinstalled version of:
    • VS Community / Professional / Enterprise
    • VS Build Tools
    • dotnet sdk (dotnet kindly adds itself to the path)
• packing nuget packages, either from .nuspecs (.NET Framework) or directlyfrom the .csproj (dotnet core)

Perhaps (though the msbuild discovery is a bit of a PITA, especially since Microsoftlikes to keep us on our toes, mixing up exactlywhere that's installed to, eg invs2019. The real win comes from:

• out of the box, on a simple-ish repo, zarro should be able to build and test,as long as you use the naming convention of{Assembly}.Tests for test projects(though it will also findTest.{Assembly} and an ubiquitousTests assembluy)
• it's easy to add more tasks to your pipeline for further processing
• use thegulp orchestration framework to extend or override available tasks

Zarro has you covered here. The heart of Zarro was originally built for gulp 3.Version 4 came out and brokeeverything. I didn't feel like rewriting perfectlyacceptable tasks, but I did want to keep up with the latest version ofgulp andthe speed advantages that were promised. As such, Zarro can consume and adaptgulp 3 tasks to run under gulp 4.

1. npm init -y (if you don't already have apackage.json
2. npm install --save-dev zarro
3. start adding scripts! for example:

   "scripts": {"build":"zarro @","test":"zarro @","zarro":"zarro"}

(thetest-dotnet task should invoke zarro's inbuiltbuild task (and some earlierones to download tooling, as required) so that when test-time comes, assembliesare already built (required for .NET Framework / NUnit runner, and optimised fordotnet by performing the build and testing without rebuild)).

Add new custom tasks by invokingzarro --create-task to guide you throughthe process. This will create a skeleton task file for you underlocal-taskswith some of the boiler-plating already done.

There are an array of pre-defined tasks you get out of the box with zarro. I hope to eventuallyprovide more documentation for them, but runningzarro --tasks should tell you somethingsimilar to:

• help
  • shows help / usage
• help:environment
  • shows help about environment variables zarro observes (same as running with --help)
• build
  • attempts to build all found .net solutions
• test-dotnet
  • test .net projects based on conventions
    • test project names should match*.Tests or*.Test or plain oldTests
    • assumes test are nunit
• cover-dotnet
  • test with coverage
  • can use dotCover or OpenCover
• generate-reports
  • generate html reports from OpenCover results
• default-tools-installer
  • installs the default helper tooling from nuget
    • nunit cli
    • dotCover
    • OpenCover
    • ReportGenerator
• install-tools
  • called before build
  • defaults to install default tools
  • override with an empty task if not useful
• dotnet-publish
  • runs dotnet cli build with publish options
• nuget-restor
  • restores nuget packages
  • run automatically as part of build
• release-npm
  • perform guided release of npm packages
  • can do beta releases
  • will automatically
    • increment version
    • git commit
    • git tag
    • git push
• update-self
  • updates to zarro@latest
• update-git-submodules
  • updates all git submodules in the repo
• pretest
  • place-holder: override this to run something before testing
• verify-up-to-date
  • verifies that the current branch is up-to-date with the main one
    • will check against {remote}/{main branch} if possible

Zarro is designed to be zero- to low- conf. You can guide many aspects of availabletasks with environment variables. Runningnpm run zarro -- --show-env will show youall observed environment variables and where they are applicable. I suggest usingcross-env and applying these variables in one place, to keep things simpler. Forexample,NExpect does the following:

"scripts": {"zarro":"cross-env DOTNET_CORE=1 BUILD_EXCLUDE=src/PeanutButter/**/* PACK_INCLUDE=* PACK_EXCLUDE=*Tests*,CoreConsumer,src/PeanutButter/**/* TEST_EXCLUDE=src/PeanutButter/**/* zarro","build":"run-s\"zarro build\"","test":"run-s\"zarro test-dotnet\""}

in the above:

• DOTNET_CORE=1 instructs zarro to usedotnet instead of searching formsbuild
• BUILD_EXCLUDE=... instructs zarro to exclude everything under that folder, recursively(NExpect imports PeanutButter as a submodule to use some shared code without relyingon another package dependency)
• similarlyTEST_EXCLUDE excludes PeanutButter tests
• similarly,PACK_INCLUDE andPACK_EXCLUDE control nuget packing within NExpect

Zarro will automatically create a.zarro-defaults next to yourpackage.json if itis not found. In here, we can add key-value-pairs of environment variables to setwhen running zarro. These values will be overridden by any existing environment variables,so if you need to override a variable which is set on the hosting system, you shouldusecross-env as above. However, for many situations, specifying environment variablesin.zarro-defaults makes npm script setup a lot easier. For example, if we use.zarro-defaults,we can modify the example above:

Update package.json with:

"scripts": {"build":"zarro @","test":"zarro test-dotnet"}

Update .zarro-defaults to contain:

DOTNET_CORE=1BUILD_EXCLUDE=src/PeanutButter/**/*PACK_INCLUDE=*PACK_EXCLUDE=*Tests*,CoreConsumer,src/PeanutButter/**/*TEST_EXCLUDE=src/PeanutButter/**/*

Note also here the shorthand of@ - if a task has the same name as the npm scriptused to invoke it, this is a quick way to surface that task tonpm run -space.

Zarro will also search two folders:

• local-tasks
• override-tasksin the root of your repo, for extra tasks that you can access from your npm scripts.

These can be brand-new functionality you'd like to add to your repo's build system,or you canoverride existing tasks, if they don't suit you. For example, if thepacktask doesn't do exactly what you want, copypack.js fromnode_modules/zarro/gulp-tasksinto yourlocal-tasks folder and modify it to suit you. If you find a generic solutionto the problem you have which others might find useful or fix a bug, I'd like to knowabout it. PRs for fixes and extension tasks which others could use will be appreciated.

• a watcher to automatically recompile scss to .css
• orchestration of build / test of sub-projects that aren't .NET
• automatic version incrementing of packages before release
• committing, tagging and pushing new changes to GitHub
  • I've found that writing a meta task calledrelease can make it muchless painful to perform a release of my nuget packages, for example.This meta task would:
    • build
    • test
    • increment package versions
    • pack
    • push packages
    • commit the updates package definitions
    • tag the release
    • push the tag and changes to GitHub

Zarro provides some convenience functionality from baked-in modules. To access a module,the globalrequireModule function will resolve the correct location for you. Moduleslive under thegulp-tasks/modules folder. Most modules will return a single function,though there are some exceptions. Some modules may be of interest to custom tasks, eg:

• gulp
  • you shouldrequireModule("gulp") wherever you would have normallydonerequire("gulp"). This gets you the patched version of gulp 4 whichwill happily consume gulp 3 tasks and which has inbuilt support for helpfor your tasks on both gulp 3 and 4. Most importantly, if youdo not use thisexport, your tasks may not be correctly registered.
• env
  • provides a utility object to resolve environment variables for you
    • register can register an environment variable as known with a defaultvalue and help. Seeregister-environment-variables.ts for examples.When you use this function, you can have a central configuration fora default value for an environment variable and your environmentvariable will be displayed in the--show-env output
    • resolve resolves environment variables for you. It can be invoked withone or more variable names, so can be used to fall back from one variableonto another. It will also resolve back values if registered.
    • associate associates one or more variables with one or more tasks,primarily to show which tasks are affected by which variables whenrunning with--show-env
    • resolveArray can resolve an environment variable to an array for you,with an optionaldelimiter parameter, which defaults to comma
    • resolveNumber resolves a numeric value from the named environmentvalue or throws if the value can't be resolved as a number, effectivelystopping execution. If you're expecting a number (eg port or max threadcount) you can simplyresolveNumber and an invalid value would causeexecution to stop with a reasonable message
    • resolveFlag resolves boolean values from environment variables
      • true for: "yes", "true" or "1"
      • false for: "no", "false" or "0"
      • throws for unknown values
• system
  • function to run other process and get back stdio results from said processes
• resolve-masks
  • single function to resolve an array of masks that could be used in agulp.srcwhere those masks can be inclusive or exclusive
• find-local-nuget
  • provides a single function to find a locally-downloadednuget.exe, automaticallydownloading it if required. Use this if you need to usenuget.exe operationsand don't want to set up your build host with a pathednuget.exe
• git utilities
  • git-tag
  • git-push
  • git-push-tags
• string padding
  • pad
  • pad-left
  • pad-right

There are many more utilities in there, feel free to browse the source.

If you've made it thus far, some light history might be of interest. Zarro's corefunctionality comes from another repo of mine:gulp-taskswhich was traditionally consumed as a git submodule. However, it seems that a lotof people don't really "get" git submodules:

• people forget (or don't understand that they need to)git submodule update --init afteragit clone or agit pull. Some modern git clients are doing this for the user,but not all of them.
• people don't seem to understand how submodules are stored (literally just a hash andan url), so they don't pay attention when committing them. In particular, I have seenmy fair share of inadvertent "submodule wars" where changes upstream aren't appliedafter apull (ie, people forget to rungit submodule update --init), then theyre-commit back theold version of the module that they have locally. So fixes tendto become unfixed
• in addition,gulp-tasks requires dependencies to be installed in the hosting repo'spackage.json, meaning that (a) the hosting repo has to "know too much" about therequirements ofgulp-tasks and (b) upstream changes may require changes to a repo'spackage.json (and annpm install). Whilst this was (eventually) automated as partofgulp-tasks, it seems unnecessarily complex.
• the solution seemed clear: makegulp-tasks available via an npm package
• the name is inspired from the old bugzilla, which would proudly proclaim "zarro boogs"when there were zero bug matches for a query, because (a) names are hard and (b)zarro aims to be zero- to low-conf