diff --git a/BUILDING.md b/BUILDING.md index 45206077..1fe2269b 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -19,19 +19,29 @@ You are expected to know your way around with go & git. If you are a casual user with no development experience, and no preliminary knowledge of go, building from source is probably not a good solution for you. -## Build the development environment +## Configure the development environment The first prerequisite of properly building distribution targets is to have a Go development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html) for proper setup. If done correctly, you should have a GOROOT and GOPATH set in the environment. -If a Go development environment is setup, one can use `go get` to install the -`registry` command from the current latest: +Next, fetch the code from the repository using git: - go get github.com/distribution/distribution/cmd/registry + git clone https://github.com/distribution/distribution + cd distribution -The above will install the source repository into the `GOPATH`. +If you are planning to create a pull request with changes, you may want to clone directly from your [fork](https://help.github.com/en/articles/about-forks). + +## Build and run from source + +First, build the binaries: + + $ make + + bin/registry + + bin/digest + + bin/registry-api-descriptor-template + + binaries Now create the directory for the registry data (this might require you to set permissions properly) @@ -42,75 +52,48 @@ Now create the directory for the registry data (this might require you to set pe The `registry` binary can then be run with the following: - $ $GOPATH/bin/registry --version - $GOPATH/bin/registry github.com/distribution/distribution v2.0.0-alpha.1+unknown + $ ./bin/registry --version + ./bin/registry github.com/distribution/distribution/v3 v2.7.0-1993-g8857a194 -> __NOTE:__ While you do not need to use `go get` to checkout the distribution -> project, for these build instructions to work, the project must be checked -> out in the correct location in the `GOPATH`. This should almost always be -> `$GOPATH/src/github.com/distribution/distribution`. - -The registry can be run with the default config using the following +The registry can be run with a development config using the following incantation: - $ $GOPATH/bin/registry serve $GOPATH/src/github.com/distribution/distribution/cmd/registry/config-example.yml - INFO[0000] endpoint local-5003 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown - INFO[0000] endpoint local-8083 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown - INFO[0000] listening on :5000 app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown - INFO[0000] debug server listening localhost:5001 + $ ./bin/registry serve cmd/registry/config-dev.yml + INFO[0000] debug server listening :5001 + WARN[0000] No HTTP secret provided - generated random secret. This may cause problems with uploads if multiple registries are behind a load-balancer. To provide a shared secret, fill in http.secret in the configuration file or set the REGISTRY_HTTP_SECRET environment variable. environment=development go.version=go1.18.3 instance.id=e837df62-a66c-4e04-a014-b063546e82e0 service=registry version=v2.7.0-1993-g8857a194 + INFO[0000] endpoint local-5003 disabled, skipping environment=development go.version=go1.18.3 instance.id=e837df62-a66c-4e04-a014-b063546e82e0 service=registry version=v2.7.0-1993-g8857a194 + INFO[0000] endpoint local-8083 disabled, skipping environment=development go.version=go1.18.3 instance.id=e837df62-a66c-4e04-a014-b063546e82e0 service=registry version=v2.7.0-1993-g8857a194 + INFO[0000] using inmemory blob descriptor cache environment=development go.version=go1.18.3 instance.id=e837df62-a66c-4e04-a014-b063546e82e0 service=registry version=v2.7.0-1993-g8857a194 + INFO[0000] providing prometheus metrics on /metrics + INFO[0000] listening on [::]:5000 environment=development go.version=go1.18.3 instance.id=e837df62-a66c-4e04-a014-b063546e82e0 service=registry version=v2.7.0-1993-g8857a194 If it is working, one should see the above log messages. -### Repeatable Builds +### Build reference -For the full development experience, one should `cd` into -`$GOPATH/src/github.com/distribution/distribution`. From there, the regular `go` -commands, such as `go test`, should work per package (please see -[Developing](#developing) if they don't work). +The regular `go` commands, such as `go test`, should work per package. A `Makefile` has been provided as a convenience to support repeatable builds. -Please install the following into `GOPATH` for it to work: - go get github.com/golang/lint/golint - -Once these commands are available in the `GOPATH`, run `make` to get a full -build: +Run `make` to build the binaries: $ make - + clean - + fmt - + vet - + lint - + build - github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar - github.com/sirupsen/logrus - github.com/docker/libtrust - ... - github.com/yvasiyarov/gorelic - github.com/distribution/distribution/registry/handlers - github.com/distribution/distribution/cmd/registry - + test - ... - ok github.com/distribution/distribution/digest 7.875s - ok github.com/distribution/distribution/manifest 0.028s - ok github.com/distribution/distribution/notifications 17.322s - ? github.com/distribution/distribution/registry [no test files] - ok github.com/distribution/distribution/registry/api/v2 0.101s - ? github.com/distribution/distribution/registry/auth [no test files] - ok github.com/distribution/distribution/registry/auth/silly 0.011s - ... - + /Users/sday/go/src/github.com/distribution/distribution/bin/registry - + /Users/sday/go/src/github.com/distribution/distribution/bin/registry-api-descriptor-template + + bin/registry + + bin/digest + + bin/registry-api-descriptor-template + binaries The above provides a repeatable build using the contents of the vendor -directory. This includes formatting, vetting, linting, building, -testing and generating tagged binaries. We can verify this worked by running +directory. We can verify this worked by running the registry binary generated in the "./bin" directory: $ ./bin/registry --version ./bin/registry github.com/distribution/distribution v2.0.0-alpha.2-80-g16d8b2c.m +Run `make test` to run all of the tests. + +Run `make validate` to run the validators, including the linter and vendor validation. You must have docker with the buildx plugin installed to run the validators. + ### Optional build tags Optional [build tags](http://golang.org/pkg/go/build/) can be provided using