{"id":29605481,"url":"https://github.com/bufbuild/makego","last_synced_at":"2025-07-20T16:05:52.848Z","repository":{"id":37977394,"uuid":"222526599","full_name":"bufbuild/makego","owner":"bufbuild","description":"Makefile setup for our Golang projects.","archived":false,"fork":false,"pushed_at":"2025-07-10T19:18:55.000Z","size":388,"stargazers_count":104,"open_issues_count":0,"forks_count":14,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-07-11T04:59:32.938Z","etag":null,"topics":["docker","go","golang","make","makefile","protobuf","protoc","protocol-buffers"],"latest_commit_sha":null,"homepage":"https://buf.build","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bufbuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-11-18T19:23:22.000Z","updated_at":"2025-07-10T19:18:58.000Z","dependencies_parsed_at":"2023-02-17T23:00:30.585Z","dependency_job_id":"bdacfad8-460a-4743-b8e7-ebcd72aa89d7","html_url":"https://github.com/bufbuild/makego","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bufbuild/makego","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fmakego","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fmakego/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fmakego/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fmakego/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bufbuild","download_url":"https://codeload.github.com/bufbuild/makego/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fmakego/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266152534,"owners_count":23884522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","go","golang","make","makefile","protobuf","protoc","protocol-buffers"],"created_at":"2025-07-20T16:05:48.979Z","updated_at":"2025-07-20T16:05:52.832Z","avatar_url":"https://github.com/bufbuild.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Makego\n\n[![License](https://img.shields.io/github/license/bufbuild/makego?color=blue)](https://github.com/bufbuild/makego/blob/main/LICENSE)\n[![Release](https://img.shields.io/github/v/release/bufbuild/makego?include_prereleases)](https://github.com/bufbuild/makego/releases)\n[![CI](https://github.com/bufbuild/makego/workflows/ci/badge.svg)](https://github.com/bufbuild/makego/actions?workflow=ci)\n\nMakego is our Makefile setup for our Golang projects. This repository also functions as a template\nrepository for our Golang projects that use makego.\n\nMakego supports our development workflow, which includes Golang, Docker, and Protobuf primarily. All\nprojects should result in `make` working out of the box, as long as the system has Golang \u003e=1.13\ninstalled, and Docker installed if Docker is used. All other dependences (except for a few that we\nneed to document that most systems will have, such as `bash`, `curl`, and `git`) are installed by makego\nautomatically and cached on a per-project basis, including all Golang module downloads.\n\nMakego allows updating from this main (or your forked main) automatically, only copying the files\nyou need.\n\n## Notice\n\nMakego is primarily OSS as we use it in our OSS projects. Makego will likely have many breaking\nchanges, and **we do not provide support for it in any form**. You're obviously welcome\nto fork it and/or use components of it, however - the `MAKEGO_REMOTE` variable controls the remote location\nfor `make copyfrommakego`.\n\nIf you do use this, you should get familiar with the actual Makefiles contained in this project.\n\n## Status\n\nVery alpha. This will change a bunch. The documentation is incomplete as well.\n\n## Example\n\n[Buf](https://github.com/bufbuild/buf) uses this, and should be treated as the gold-standard example\nfor makego usage.\n\n## Layout\n\nThe following are controlled by makego, and should not be edited directly:\n\n- [make/go](make/go) - This is the \"actual\" makego library. This contains the Makefiles and scripts\n  that compromise makego's functionality.\n- [.dockerignore](.dockerignore) - The autogenerated [Docker](https://www.docker.com) ignore\n  file. If you do not include [make/go/docker.mk](make/go/docker.mk), you should delete this file\n  for your new Golang project.\n- [.gitignore](.gitignore) The autogenerated git ignore file.\n- [go.mod](go.mod), [go.sum](go.sum) - The Golang module files. These are autogenerated.\n\nOtherwise, you're free to choose your own layout, however you should generally do the following:\n\n- Have a file `make/PROJECT/all.mk` such as [make/foo/all.mk](make/foo/all.mk) that defines the\n  setup for your project. This should be the only file included in your [Makefile](Makefile).\n- Put your main packages in [cmd](cmd). For example, for a binary named `foo`, you should have\n  [cmd/foo](cmd/foo), and add `cmd/foo` to `GO_BINS` such as in [make/foo/all.mk](make/foo/all.mk).\n- If using Docker, put a Dockerfile per main package as [Dockerfile.foo](Dockerfile.foo).\n  Then add `foo` to `DOCKER_BINS` such as in [make/foo/all.mk](make/foo/all.mk).\n- Put generated files in any subdirectory named `gen`. Makego treats `gen` directories as special,\n  primarily by not linting them or using them for code coverage.\n\nOther files of relevance:\n\n- [.github](.github) - This is for GitHub Actions primarily, there is an example action at\n  [.github/workflows/ci.yaml](.github/workflows/ci.yaml).\n- [.envrc](.envrc) - This is for [direnv](https://direnv.net), which makego supports. This\n  generally should not be edited, however.\n- [LICENSE](LICENSE) - Our license. Replace with your own license.\n- [Makefile](Makefile) - The main Makefile. See below for setup.\n- [README.md](README.md) - This readme.\n- `.env` - This directory contains your individual environment, if you want. You can back this\n  up to with `make envbackup` and restore with `make envrestore`. The special file `.env/env.sh`\n  will be included with `make direnv`, which direnv calls via [.envrc](.envrc).\n- `.tmp` - This directory is used for temporary files such as coverage files and makego temporary\n  clones.\n\n## New Project Setup\n\nAssuming your actual remote is `github.com/eng/hello`:\n\n```bash\ngit clone https://github.com/bufbuild/makego hello\ncd ./hello\nrm -rf .git\ngit init\ngit remote add origin https://github.com/eng/hello\n```\n\nMove `make/foo` to `make/PROJECT`:\n\n```bash\nmv make/foo make/hello\n```\n\nThen edit the [Makefile](Makefile):\n\n```make\n# You can put make/go somewhere else if you want but we would not recommend it, however it\n# should work as all Makefile in make/go use this variable to know where things are\nMAKEGO := make/go\n# Change to your fork. Do not use ours.\nMAKEGO_REMOTE := https://github.com/eng/makego.git\n# Your project name\nPROJECT := hello\n# The Golang module\nGO_MODULE := github.com/eng/makego\n# The Docker organization. Optimally this is your Docker Hub organization, but makego\n# does not currently interact with Docker Hub.\nDOCKER_ORG := eng\n# The Docker project name, generally the same as PROJECT. The Docker image\n# $(DOCKER_ORG)/$(DOCKER_PROJECT)-workspace will be created.\nDOCKER_PROJECT := hello\n\n# This changes from make/foo/all.mk to make/hello/all.mk\ninclude make/hello/all.mk\n```\n\n\nUpdate everything and make sure everything builds:\n\n```bash\n# This also calls make generate and make all\nmake upgrade\n```\n\nFigure out the specific files you want (see \"Basic Concepts\" below), and only include\nthose files in `make/hello/all.mk`. When you're sure you are done, run `make updatemakego`\nto delete unnecessary files.\n\n```bash\n# CONFIRM=1 is just for protection\n# If you later want to restore all the files, you can do so by adding ALL=1 to this command\nmake updatemakego CONFIRM=1\n```\n\nThen, delete everything in this readme except potentially the badge links at the top (but if\nyou keep the badge links, update them for your repository). Also update the LICENSE for your use.\n\n## Basic concepts\n\nAll projects should have a `make/PROJECT/all.mk` file that defines your actual setup. This\nincludes files from `make/go` that you need, as well as any custom build commands See\n[make/buf/all.mk](https://github.com/bufbuild/buf/blob/main/make/buf/all.mk) for a\nreal-world example.\n\nThis file should all or some of these files, depending on what you need:\n\n- [make/go/bootstrap.mk](make/go/bootstrap.mk) - This always needs to be the first file\n  included. This defines functions that the rest of the files use.\n- [make/go/go.mk](make/go/go.mk) - This defines Golang functionality. All projects should\n  generally include this.\n- [make/go/docker.mk](make/go/docker.mk) - This defines Docker functionality. Only\n  include if you want to use Docker. If you do not use Docker, you can delete the `.dockerignore`\n  file and any Dockerfiles.\n\nAll other files are automatically included.\n\n## Development commands\n\nWe are not documenting all development commands, however some important ones of note:\n\n- `make all` - This is the default goal, and runs linting and testing.\n- `make ci` - This is the goal for CI, and downloads deps, and runs linting, testing, and code coverage.\n  Note that deps are downloaded automatically on a per-target basis, so the initial dep download really\n  shouldn't be needed.\n- `make generate` - Do all generation.\n- `make lint` - Do all linting.\n- `make build` - Go build.\n- `make test` - Go test.\n- `make cover` - Go code coverage.\n- `make install` - Install all Go binaries defined by `GO_BINS`.\n- `make dockerbuild` - Build all Docker images defined by `DOCKER_BINS`.\n- `make updatemakego` - Update from makego main.\n\n## Variables\n\nMakego is controlled by various environment variables. This list may get out of date, however\nas of this writing, this is what is required, settable, and settable at runtime.\n\n### Required\n\nThese variables should be defined in your Makefile and are required.\n\n- `MAKEGO` - The location of the `make/go` directory. Generally you should have this as `make/go`,\n  however we did make it settable so you can put the files somewhere else.\n- `MAKEGO_REMOTE` - The remote location for makego. You should point this at your fork. The\n  make target `make copyfrommakego` will copy makego to your current files.\n- `PROJECT` - Your project name. This is used for many things such as your config and cache\n  locations.\n- `GO_MODULE` - Your Golang module name.\n\nIf you use Docker, the following are also required.\n\n- `DOCKER_ORG` - The Docker organization. Optimally this is your Docker Hub organization, but makego\n  does not currently interact with Docker Hub.\n- `DOCKER_PROJECT` - The Docker project name, generally the same as `PROJECT`. The Docker image\n  `$(DOCKER_ORG)/$(DOCKER_PROJECT)-workspace` will be created.\n\n### Settable\n\nThese variables are settable in your Makefiles, but should be static, i.e. these are for\nproject-specific settings and not intended to be set on the command line.\n\n- `FILE_IGNORES` - The relative paths to files to add to `.dockerignore` and `.gitignore`. By\n  default, makego will add `.env`, `.tmp`, and any Golang binaries.\n  Note if you set this, you should do so by including the current value ie `FILE_IGNORES := $(FILE_IGNORES) .build/`.\n- `CACHE_BASE` - By default, makego caches to `~/.cache/$(PROJECT)`. Set this to change that.\n- `GO_BINS` - The relative paths to your Golang main packages, For example `cmd/foo`.\n  Note if you set this, you should do so by including the current value ie `GO_BINS := $(GO_BINS) cmd/bar`.\n- `GO_GET_PKGS` - Extra packages to get when running `make upgrade`.\n  For example, [make/buf/all.mk](https://github.com/bufbuild/buf/blob/main/make/buf/all.mk)\n  adds `master` for [github.com/jhump/protoreflect](https://github.com/jhump/protoreflect).\n  Note if you set this, you should do so by including the current value ie `GO_GET_PKGS := $(GO_GET_PKGS) github.com/foo/bar@v1.0.0`.\n- `GO_LINT_IGNORES` - Extra `grep` ignores for linting.\n  Note if you set this, you should do so by including the current value ie `GO_LINT_IGNORES := $(GO_LINT_IGNORES) \\/foobar\\/`.\n- `DOCKER_BINS` - This sets any Dockerfiles that are to be built. There should be a matching\n  `Dockerfile.binaryname` for each value.\n  Note if you set this, you should do so by including the current value ie `DOCKER_BINS := $(DOCKER_BINS) bar`.\n- `.*_VERSION` - This sets the version for dependencies, such as `ERRCHECK_VERSION := e14f8d59a22d460d56c5ee92507cd94c78fbf274`. We update these once in a while, but you can set your own as well to make sure your own\n  builds are deterministic. See the `dep_.*` files for the individual variables.\n\n### Runtime\n\nThese variables are meant to be set when invoking make targets on the command line.\n\n- `CONFIRM` - This is required to be set when running `make updatemakego`. This is to protect\n  against updating when not intended.\n- `ALL` - This results in all makego files being downloaded when running `make updatemakego`\n  instead of just the ones that you current have included.\n- `GOPKGS` - This controls what packages to build for Go commands. By default, this is `./...`. If\n  you only wanted to test `./internal/foo/...` for example, you could run `make test GOPKGS=./internal/foo/...`\n- `COVEROPEN` - This will result in the `cover.html` file being automatically opened after `make\n  cover` is run, for example `make cover COVEROPEN=1`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fmakego","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbufbuild%2Fmakego","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fmakego/lists"}