Merge pull request #3679 from Jamstah/building-doc-updates

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
+Next, fetch the code from the repository using git:
-`registry` command from the current latest:
 
-    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
+    $ ./bin/registry --version
-    $GOPATH/bin/registry github.com/distribution/distribution v2.0.0-alpha.1+unknown
+    ./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
+The registry can be run with a development config using the following
-> 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
 incantation:
 
-    $ $GOPATH/bin/registry serve $GOPATH/src/github.com/distribution/distribution/cmd/registry/config-example.yml
+    $ ./bin/registry serve cmd/registry/config-dev.yml
-    INFO[0000] endpoint local-5003 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    INFO[0000] debug server listening :5001
-    INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    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] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
+    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] debug server listening localhost:5001
+    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
+The regular `go` commands, such as `go test`, should work per package.
-`$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).
 
 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
+Run `make` to build the binaries:
-
-Once these commands are available in the `GOPATH`, run `make` to get a full
-build:
 
     $ make
-    + clean
+    + bin/registry
-    + fmt
+    + bin/digest
-    + vet
+    + bin/registry-api-descriptor-template
-    + 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
     + binaries
 
 The above provides a repeatable build using the contents of the vendor
-directory. This includes formatting, vetting, linting, building,
+directory. We can verify this worked by running
-testing and generating tagged binaries. 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