go-make

Make framework

Introduction

Goal of go-make is to provide a simple, versioned build and test environment for "common go-projects" that make standard development tasks easy (see also Standard go-project for details). To accomplish this goal go-make provides default targets, tools, and configs for testing, linting, building, installing, updating, running, and releasing libraries, binaries, and container images.

go-make can be either run as command line tool or hooked into an existing project via a minimal Makefile. Technically go-make is just a thin wrapper around a very generic Makefile based on a standard go-project supporting different tools:

• gomock - go generating mocks.
• codacy - for code quality documentation.
• golangci-lint - for pre-commit linting.
• zally - for pre-commit API linting.
• gitleaks - for sensitive data scanning.
• grype - for security scanning.
• syft - for material listing.

The go-make wrapper provides the necessary version control for the Makefile and the config of the tools. The tools are automatically installed when needed in the configured (or latest) available version using a default or custom config file. All config files can be installed and customized (see Setup and customization).

Note: For many tools go-make accepts the risk that using the latest versions of tools, e.g. for linting, may break the build to allow cotinuous upgrading of dependencies by default. For tools were this is not desireable, e.g. for revive and golangci-lint the default import is version. Other tools can be versioned if needed (see manual for more information).

Installation

To install go-make simply use go install command (or any other means, e.g. curl to obtain a released binary):

go install github.com/tkrop/go-make@latest

The scripts and configs are automatically checked out in the version matching the wrapper. go-make has the following dependencies, that must be satisfied by the runtime environment, e.g. using ubuntu-20.04 or ubuntu-22.04:

• GNU make (^4.2).
• GNU bash (^5.0).
• GNU coreutils (^8.30)
• GNU findutils (^4.7)
• GNU awk (^5.0).
• GNU sed (^4.7)
• curl (^7)

Example usage

After installing go-make, all provided targets can executed by simply calling go-make <target> in the project repository on the command line, in another Makefile, in a github action, or any other delivery pipeline config script:

go-make all        # execute a whole build pipeline depending on the project.
go-make test lint  # execute only test 'test' and 'lint' steps of a pipeline.
go-make image      # execute minimal steps to create all container images.

For further examples see go-make manual.

Note: Many go-make targets can be customized via environment variables, that by default are defined via Makefile.vars (see also Modifying variables).

Makefile integration

If you like to integrate go-make into another Makefile you may find the Makefile provided in the config helpful that automatically installs go-make creates a set of phony targets to allow auto-completion and delegates the execution (see also Makefile).

The default Makefile can also be installed to a project from the config via go-make init-make to boot strap a project. Other available config files can be installed one by one using go-make init/<file>.

Shell integration

To setup command completion for go-make, add the following snippet to your .bashrc.

source <(go-make --completion=bash)

Makefile development

To extend the Makefile, you develop own receipts in a custom file called Makefile.ext that is included automatically. If you want to extend original receipts, you can use make install-make! to automatically replace the wrapper Makefile against the original Makefile.base and adding a local MANUAL.md to your project.

Standard go-Project

The Makefile.base provided in this project is based on a standard go-project setting some limitations. The standard go-project is defined to meet Zalando in-house requirements, but is general enough to be useful in open source projects too. It adheres to the following conventions:

1. All commands (services, jobs) are provided by a main.go placed as usual under cmd using the pattern cmd/<name>/main.go or in the root folder. In the latter case the project name is used as command name.

2. All source code files and package names following the go-standard only consist of lower case ASCII letters, hyphens (-), underscores (_), and dots (.). Files are ending with .go to be eligible.

3. Modules are placed in any sub-path of the repository, e.g. in pkg, app, internal are commonly used patterns, except for build and run. These are used by go-make as temporary folders to build commands and run commands and are cleaned up regularly.

4. The build target provides build context values to set up global variables in main and config packages.

   • Path - the formal package path of the command build.
   • Version - the version as provided by the VERSION-file in project root or via the (BUILD_)VERSION environ variables.
   • Revision - the actual full commit hash (git rev-parse HEAD).
   • Build - the current timestamp of the build (date --iso-8601=seconds).
   • Commit - the timestamp of the actual commit timestamp (git log -1 --date=iso8601-strict --format=%cd).
   • Dirty - the information whether build repository had uncommitted changes.

5. All container image build files must start with a common prefix (default is Dockerfile). The image name is derived from the organization and repository names and can contain an optional suffix, i.e <org>/<repo-name>(-<suffix>).

6. For running a command in a container image, make sure that the command is installed in the default execution directory of the container image - usually the root directory. The container image must either be generated with suffix matching the command or without suffix in common container.

All targets in the Makefile are designated to set up the go-project automatically, installing the necessary tools - except for the golang compiler and build environment -, and triggering the required targets as necessary.

Trouble Shooting

If we have published an non-working version of go-make and your project is not able to build, test, run, etc, the quickest way to reset the project Makefile working go-make version is to run:

go install github.com/tkrop/go-make@latest; go-make update;

If the latest version is not fixed yet, you can also try to move backward finding the last working tagged version.

Terms of usage

This software is open source as is under the MIT license. If you start using the software, please give it a star, so that I know to be more careful to keep changes non-breaking.

Building

The project is using itself for building as a proof of concept. So either run make all or go-make all. As fallback it is always possible to directly use the core Makefile calling:

make -f config/Makefile.base <target>...

You can also test the local build go-make application with the local config. The project compiles itself to use the local config by default.

Contributing

If you like to contribute, please create an issue and/or pull request with a proper description of your proposal or contribution. I will review it and provide feedback on it as soon as possible.