cert-manager Make Tooling

This directory contains tools and scripts used to create development and testing environments for cert-manager, centered around the use of GNU Make.

Most tasks that a developer might encounter day-to-day are documented in make help; you can view that documentation by changing to the root of a cert-manager checkout and simply running:

make help

If you think that the documentation in make help is insufficient or that an important make target isn't documented, we'd consider that a bug. Please feel free to raise an issue!

Most of the rest of the documentation for the cert-manager build system is on the cert-manager website:

• Building cert-manager - A guide to different commands which are useful for building cert-manager components locally.
• CRDs - Information on updating, verifying and generating code centered around the cert-manager CRDs.
• Developing with Kind - Setting up a local development cluster using Kind
• Running End-to-End Tests - Details on cert-manager's end-to-end test suite and how it can be run

Changing the Makefiles

When adding or changing a make target, you might want to consider a few questions which could have a significant effect on the performance of your changes.

Should it be documented?

If you want your target to appear when a user runs make help, you can add a documentation comment to it which starts with ##.

.PHONY: kind-version
## kind-version prints the version of kind.
##
## Bet you didn't expect that, huh?
##
## @category Development
kind-version: | $(NEEDS_KIND)
	@$(KIND) --version

Categories are loosely defined; check the output of make help for examples of the kinds of categories we already have.

Regular comments above a target should start with a single #.

Should it be .PHONY?

A phony target is one that is not really the name of a file; rather it is just a name for a recipe to be executed when you make an explicit request.

The GNU Make documentation gives the above definition for .PHONY targets, and is worth reading if you're adding a new target since getting this wrong can lead to either spurious rebuilds or unexpected failures to execute your target.

Put short: If a target doesn't create a file with the same name as the target, it should be .PHONY.

Mark the target as .PHONY by adding the declaration directly above the target, with any documentation comments in between. For example:

.PHONY: my-target
## Does something awesome!
##
## @category Awesomeness
my-target:
	@echo Something awesome!

Target Dependencies / Prerequisites

Make has two types of dependency: "normal" and "order-only".

When creating or changing a target, you should choose the type based on what your dependency is.

⚠️ If your dependency is a .PHONY target, you should think very hard about whether to include it. A .PHONY dependency will force your target to be rebuilt every single time. That's rarely what you want.

If your dependency is a directory or a tool, it should likely be order-only since you don't want to rebuild your target when those dependencies change.

Otherwise, your dependency should be normal.

For example:

$(BINDIR)/awesome-stuff/my-file: README.md | $(BINDIR)/awesome-stuff $(NEEDS_KIND)
	# write the kind version to $(BINDIR)/awesome-stuff/my-file
	$(KIND) --version > $@
	# append README.md
	cat README.md >> $@

This target will be rebuilt if README.md changes, but not if the installed version of kind changes or the $(BINDIR)/awesome-stuff folder changes.

The dependencies you'll need will inevitably depend on the target you're writing. If in doubt, feel free to ask!

Tool Dependencies

The scripts used by make commonly require additional tooling, such as access to kubectl, helm, kind and a bunch of other things.

The build system is capable of downloading and provisioning most of these tools without any user interaction. For example, if an end-to-end test requires kind, then kind will be downloaded and that version will be used regardless of whether you have kind installed on your system.

Usually, that's what you want; it ensures that you're using the exact same tools - at the same versions - as other developers.

Some tools must be installed locally, however. The build system will alert you if a required tool cannot be found, and these tools are documented on the website.

Specifically, note that you can choose to use your system version of Go or to download a vendored copy.