{"id":13472937,"url":"https://github.com/cloudflare/hellogopher","last_synced_at":"2025-05-15T12:06:58.822Z","repository":{"id":64167182,"uuid":"79571917","full_name":"cloudflare/hellogopher","owner":"cloudflare","description":"Hellogopher: \"just clone and make\" your conventional Go project","archived":false,"fork":false,"pushed_at":"2024-09-25T05:13:09.000Z","size":129,"stargazers_count":1147,"open_issues_count":9,"forks_count":59,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-11T23:01:50.478Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2017-01-20T15:42:28.000Z","updated_at":"2025-04-04T02:22:44.000Z","dependencies_parsed_at":"2024-01-13T10:41:34.001Z","dependency_job_id":"5577bbeb-3bef-4432-9c29-7725565079c2","html_url":"https://github.com/cloudflare/hellogopher","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fhellogopher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fhellogopher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fhellogopher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fhellogopher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/hellogopher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337616,"owners_count":22054254,"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":[],"created_at":"2024-07-31T16:00:59.354Z","updated_at":"2025-05-15T12:06:53.754Z","avatar_url":"https://github.com/cloudflare.png","language":"Makefile","funding_links":[],"categories":["Makefile","Libraries"],"sub_categories":[],"readme":"# Hellogopher: \"just clone and `make`\"\n\nHellogopher is a Makefile that makes your conventional Go project build from anywhere, for anyone, with just `make`.\n\n## Quickstart\n\n```\nwget https://raw.githubusercontent.com/cloudflare/hellogopher/master/Makefile\n$EDITOR Makefile # modify IMPORT_PATH\nmake setup\ngit add Makefile .gitignore vendor/\n```\n\nYou can now just clone the repository anywhere, and `make` it. `go get` still works as usual.\n\n```\n$ make\n$ ./bin/hello\nHello, world!\n\n$ make test\n$ make cover\n```\n\nIf you get `cannot find package` errors, you need to read the *Vendoring* section.\n\n![demo](https://cloud.githubusercontent.com/assets/1225294/22173691/f2d297ce-dfca-11e6-910f-11b416e4e75a.gif)\n\n### What is `IMPORT_PATH`?\n\n`IMPORT_PATH` is the absolute unique name of your repository. It's usually where it can be found, too. For example `github.com/FiloSottile/example`.\n\nYou use the `IMPORT_PATH` any time you want to refer to your code: in the Makefile, with `import`, with `go get`.\n\nIf your `IMPORT_PATH` is `github.com/FiloSottile/example`, the code in the root of your repository is `github.com/FiloSottile/example` (and it will compile to a binary named `example`), the code in the folder `foo` is `github.com/FiloSottile/example/foo`, `cmd/bar` is `github.com/FiloSottile/example/cmd/bar`, and so on.\n\nIf you change the `IMPORT_PATH` you have to run `make clean`.\n\nIf you don't care about `go get`, for example if the code is **embedded inside some other non-Go codebase**, you can just pick an arbitrary one like `company.com/bigprogram/smallgotool`.\n\n### Vendoring\n\nA hellogopher project uses the official Go vendoring style: third-party packages go in `./vendor/`, like `./vendor/github.com/fatih/color`. The Makefile will intentionally ignore your system GOPATH to force you to vendor.\n\nHellogopher has no opinions on how you populate the vendor folder, but a tool that is guaranteed to work as flexibly as hellogopher is [gvt](https://github.com/FiloSottile/gvt). If you use `make setup` you'll find gvt in `./bin/gvt`.\n\nDon't forget to check the vendor folder into your VCS.\n\n```\n./bin/gvt fetch github.com/fatih/color\ngit add vendor/\n```\n\n### Using editors and other tools\n\nAll the tools used by the Makefile have been vetted and fixed to work out of the box. However, most other tools (`gometalinter`, `guru`, ...) and editors are very likely not to work unless you place the repository at `$GOPATH/src/$IMPORT_PATH`.\n\nThe point of hellogopher is not to be an universal wrapper or the only tool you use, but to get you started easily before you learn GOPATH.\n\n## Why\n\nGo developers should know and use GOPATH. But **it shouldn't be the first thing they are exposed to**. At Cloudflare we noticed it was the main cause of friction for novice or casual Go users. They expect to **just clone a repository anywhere, and be able to build it**.\n\nHellogopher allows non-Go developers to easily build the project in any environment, and provides enough tools (`test`, `cover`, `format`) for the casual contributor.\n\nStill, a hellogopher project is just a **standard `go get`-able project**. Regular Go developers should place the repository at its proper place in the GOPATH, so they can use all other tools that expect a GOPATH. (And they can still benefit from the convenience methods like `make cover` and the vendoring enforcement.)\n\nHellogopher makes your install instructions look like this:\n\n```\ngo get -u github.com/FiloSottile/zcash-mini\n - or -\ngit clone https://github.com/FiloSottile/zcash-mini\ncd zcash-mini \u0026\u0026 make \u0026\u0026 sudo cp ./bin/zcash-mini /usr/local/bin/\n```\n\nIt achieves similar results to [gb](https://getgb.io/), but preserving the conventional structure of a Go project. It works similarly to the Camlistore build system but without the temporary copies.\n\n## Features\n\nA hellogopher-based project is a proper Go repository, so you can `go get` it and import it from other packages.  But *at the same time* it includes a powerful Makefile that isolates the build from the system and works from anywhere, without having to setup a GOPATH.\n\n### make\n\nA standard build target builds a binary and places it in `bin/`.\n\nVersion and build time are injected at link time.\n\nAll operations take full advantage of **incremental builds**.\n\nThe system GOPATH is ignored, so only vendored dependencies are used.\n\n### make test\n\n`make test` runs `go vet` and `go test -race` on all packages, excluding those matching a pattern in `IGNORED_PACKAGES`.\n\n`GODEBUG=cgocheck=2` is set so that the (expensive) full suite of cgo checks are run during tests. It has no effect if you don't use cgo.\n\nIt installs the race libraries (in the hidden GOPATH) just so it does not have to compile them the next time.\n\n### make cover\n\n`make cover` aggregates the coverage of all tests over all packages. That is, it runs the test suite of all packages, each time collecting the coverage over all packages, and then aggregates all those reports into one.\n\nIt prints detailed statistics and opens the full HTML report in the browser.\n\n*Note: `make cover` does not exit 1 on failure.*\n\n### make format\n\n`make format` runs `goimports` on all non-ignored packages.\n\n### Version and build information\n\n`make build` uses `VERSION_FLAGS` which is generated from the build version (git tag and hash) and the time of the build.\n\nFor these to be accessible to your Go application you need to include the following in your `main.go`:\n\n```go\n// Version and BuildTime are filled in during build by the Makefile\nvar (\n\tVersion   = \"N/A\"\n\tBuildTime = \"N/A\"\n)\n```\n\nAn example of this can be seen in the [subdirs example](https://github.com/cloudflare/hellogopher/blob/master/_examples/subdirs/cmd/hello/main.go).\n\n\n### CI mode\n\nCI mode is enabled if the environment variable `CI` is set to 1.\n\nThe `make test` full verbose output is both sent to stdout/stderr, and saved in `.GOPATH/test/vet.txt` and `.GOPATH/test/output.txt`.\n\nThe `make cover` HTML report is saved in `.GOPATH/cover/all.html`.\n\n### Cross-compiling\n\nYou can cross-compile easily with `GOOS=linux make`. The generated binary will end up in `bin/OS_ARCH/`, like `bin/linux_amd64/hello`.\n\nHellogopher works nicely also if you share a folder between architectures, for example with Docker for Mac.\n\n## Tips and FAQ\n\nDon't use **relative imports** (the ones starting with `./`). Just don't. No, really.\n\n**If you get `cannot find package` errors,** read [the Vendoring section](https://github.com/cloudflare/hellogopher/blob/master/README.md#vendoring).\n\nBinary targets are **.PHONY** because hellogopher uses the Go native incremental build support.\n\nBinaries will be **named after the folder they are in**. If your `package main` is in the repository root and not in a subfolder, the binary will be named after the repository name. This is a fundamental concept of Go.\n\n**If code is not in the project root**, add the sub-path to `$(IMPORT_PATH)` in the build target. There's an example called `otherbin` in a new hellogopher. But a hellogopher project is just a [normal Go project](https://golang.org/doc/code.html#Organization), so no need for `src/` folders within repositories.\n\nTo **exclude a package** from `make test`/`cover`/`list`/`format` add its name (or a part of it) to `IGNORED_PACKAGES`. By default vendored packages are excluded. You might need to do this if you have 3rd party code outside of `vendor/`, too.\n\nIf you add Makefile binary targets don't forget the **`.GOPATH/.ok`** dependency.\n\nIf you need to `go build` a lone **`.go` file** instead of a package, first stop and think if it shouldn't be a package instead.  Then if you insist build them like this:\n\n```\ngo build $(GOPATH)/src/$(IMPORT_PATH)/my/go/file.go\n```\n\nTo run the Makefile verbosely, **printing commands and build progress**, set `V := 1` at the top of the Makefile. You can use `make $TARGET V=1` and `make $TARGET V=` to control this on a per-call basis.\n\n## How does this work?\n\n*You don't need to read, understand or like this to use hellogopher.*\n\nThe trick to the magic Makefile is that it creates a GOPATH in .GOPATH, and places a\nsymlink back to the root of the repo at the position where your package is supposed to be.\n\nFor example, `.GOPATH/src/github.com/FiloSottile/example -\u003e ../../../..`.\n\nIt then uses .GOPATH as the GOPATH, and runs `go install`.\n\nThe GOPATH is permanent and local, and changes don't need to be synced since it uses a symlink to the repo. So incremental builds just work.\n\nThere are a lot of workarounds to make the symlink work, but they all revolve around the fact that `./...` does not traverse the symlink. So instead we first cd into it, and run `go list ./...` from that perspective. Similarly, goimports needs to know that the files are relative to the GOPATH to recognize the vendor folder, so we pass prefixed paths to it.\n\nThis is a bit complex, but the idea is that if you use other tools, you'll place the package in the right place in your system GOPATH and not use the symlink trick.  All the work to make the Makefile tools work with symlinks has already been done for you :)\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fhellogopher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fhellogopher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fhellogopher/lists"}