Update building documentation (FerretDB#1713)

Closes FerretDB#735. Closes FerretDB#1447.
noisersup · Dec 28, 2022 · 1293a5e · 1293a5e
1 parent c50e834
commit 1293a5e
Show file tree

Hide file tree

Showing 39 changed files with 379 additions and 246 deletions.
diff --git a/.github/RELEASE_CHECKLIST.md b/.github/RELEASE_CHECKLIST.md
@@ -30,7 +30,9 @@
 
 ## Release
 
-1. Upload .deb and .rpm packages [from the CI build for the tag](https://github.com/FerretDB/FerretDB/actions/workflows/packages.yml?query=event%3Apush) to the draft release.
+1. Upload the binary and .deb and .rpm packages
+   [from the CI build for the tag](https://github.com/FerretDB/FerretDB/actions/workflows/packages.yml?query=event%3Apush)
+   to the draft release.
 2. Close milestone in issues.
 3. Publish release on GitHub.
 4. Announce it on Slack.

diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
@@ -47,9 +47,20 @@ jobs:
       - name: Run init
         run: bin/task init
 
+      - name: Build release binary
+        run: bin/task build-release
+
       - name: Build packages
         run: bin/task packages
 
+      - name: Upload ferretdb
+        uses: actions/upload-artifact@v3
+        with:
+          name: ferretdb
+          path: bin/ferretdb
+          retention-days: 14
+          if-no-files-found: error
+
       - name: Upload ferretdb.deb
         uses: actions/upload-artifact@v3
         with:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -66,6 +66,11 @@ you can reset the environment with `task env-reset`.
 
 You can see all available `task` tasks with `task -l`.
 
+### Building release binary
+
+To build a release binary, run `task build-release`.
+The result will be saved as `bin/ferretdb`.
+
 ## Contributing code
 
 ### Commands for contributing code

diff --git a/README.md b/README.md
@@ -81,6 +81,22 @@ They are not suitable for most production use-cases because they keep all data i
 You can also install with FerretDB with the `.deb` and `.rpm` packages
 provided for each [release](https://github.com/FerretDB/FerretDB/releases).
 
+## Building and packaging
+
+We strongly advise users not to build FerretDB themselves.
+Instead, use Docker images or .deb and .rpm packages provided by us.
+If you want to package FerretDB for your operating system or distribution,
+the recommended way is to use the `build-release` task;
+see our [instructions for contributors](CONTRIBUTING.md) for more details.
+FerretDB could also be built as any other Go program,
+but a few generated files and build tags could affect it.
+See [there](https://pkg.go.dev/github.com/FerretDB/FerretDB/build/version) for more details.
+
+## Documentation
+
+* [Documentation for users](https://docs.ferretdb.io/).
+* [Documentation for Go developers about embeddable FerretDB](https://pkg.go.dev/github.com/FerretDB/FerretDB/ferretdb).
+
 ## Community
 
 * Website and blog: [https://ferretdb.io](https://ferretdb.io/).

diff --git a/Taskfile.yml b/Taskfile.yml
@@ -9,7 +9,7 @@ vars:
   FUZZTIME: 15s
   FUZZCORPUS: ../fuzz-corpus
   RACEFLAG: -race={{and (ne OS "windows") (ne ARCH "arm")}}
-  BUILDTAGS: ferretdb_tigris
+  BUILDTAGS: ferretdb_debug,ferretdb_tigris
   SERVICES: postgres tigris mongodb
 
 tasks:
@@ -30,7 +30,23 @@ tasks:
   gen-version:
     run: once
     cmds:
-      - go generate -x ./internal/util/version
+      - go generate -x ./build/version
+
+  # do not change that target much; see "Building and packaging" in README.md
+  build-release:
+    desc: "Build bin/ferretdb{{exeExt}} (release build)"
+    deps: [gen-version]
+    cmds:
+      - go build -o=bin/ferretdb{{exeExt}} -trimpath -tags=ferretdb_tigris ./cmd/ferretdb
+    env:
+      CGO_ENABLED: 0
+
+  build-testcover:
+    desc: "Build bin/ferretdb-testcover{{exeExt}}"
+    run: once
+    deps: [gen-version]
+    cmds:
+      - go test -c -o=bin/ferretdb-testcover{{exeExt}} -trimpath {{.RACEFLAG}} -tags=ferretdb_testcover,{{.BUILDTAGS}} -coverpkg=./... ./cmd/ferretdb
 
   init-tools:
     dir: tools
@@ -52,10 +68,6 @@ tasks:
       - go mod tidy
       - go mod verify
 
-  # deprecated alias
-  init-clean:
-    deps: [env-reset]
-
   env-reset:
     desc: "Clean ALL Go and Docker data (caches, images, volumes), and reset environment"
     cmds:
@@ -233,13 +245,6 @@ tasks:
       - go run {{.RACEFLAG}} ./cmd/fuzztool corpus seed {{.FUZZCORPUS}}
       - go run {{.RACEFLAG}} ./cmd/fuzztool corpus {{.FUZZCORPUS}} generated
 
-  build-testcover:
-    desc: "Build bin/ferretdb-testcover"
-    run: once
-    deps: [gen-version]
-    cmds:
-      - go test -c -o=bin/ferretdb-testcover{{exeExt}} -trimpath {{.RACEFLAG}} -tags=ferretdb_testcover,{{.BUILDTAGS}} -coverpkg=./... ./cmd/ferretdb
-
   run:
     desc: "Run FerretDB"
     deps: [build-testcover]
@@ -283,7 +288,7 @@ tasks:
     cmds:
       - bin/golangci-lint{{exeExt}} run --config=.golangci.yml
       - bin/golangci-lint{{exeExt}} run --config=.golangci-new.yml
-      - bin/go-consistent{{exeExt}} -pedantic ./cmd/... ./internal/... ./ferretdb/...
+      - bin/go-consistent{{exeExt}} -pedantic ./cmd/... ./internal/... ./build/... ./ferretdb/...
       - bin/go-sumtype{{exeExt}} ./...
       - go vet -vettool=./bin/checkswitch{{exeExt}} ./...
       - bin/task{{exeExt}} -d integration integration-lint
@@ -365,9 +370,9 @@ tasks:
         --load .
     vars:
       VERSION:
-        sh: cat internal/util/version/gen/version.txt
+        sh: cat build/version/version.txt
       COMMIT:
-        sh: cat internal/util/version/gen/commit.txt
+        sh: cat build/version/commit.txt
 
   docker-push:
     deps: [gen-version]
@@ -382,9 +387,9 @@ tasks:
         --push .
     vars:
       VERSION:
-        sh: cat internal/util/version/gen/version.txt
+        sh: cat build/version/version.txt
       COMMIT:
-        sh: cat internal/util/version/gen/commit.txt
+        sh: cat build/version/commit.txt
 
   docker-push-release:
     cmds:
@@ -397,15 +402,14 @@ tasks:
               ghcr.io/ferretdb/ferretdb:{{trimPrefix "v" .VERSION}}
     vars:
       VERSION:
-        sh: cat internal/util/version/gen/version.txt
+        sh: cat build/version/version.txt
 
   packages:
     cmds:
       - task: packages-deb
       - task: packages-rpm
 
   packages-deb:
-    deps: [build-testcover]
     dir: build
     cmds:
       - ../bin/nfpm{{exeExt}} package --packager=deb --target=deb/ferretdb.deb
@@ -414,12 +418,11 @@ tasks:
         'dpkg -i /deb/ferretdb.deb && ferretdb --version'
     env:
       VERSION:
-        sh: cat ../internal/util/version/gen/version.txt
+        sh: cat ../build/version/version.txt
       GOARCH:
         sh: go env GOARCH
 
   packages-rpm:
-    deps: [build-testcover]
     dir: build
     cmds:
       - ../bin/nfpm{{exeExt}} package --packager=rpm --target=rpm/ferretdb.rpm
@@ -428,7 +431,7 @@ tasks:
         'rpm -i /rpm/ferretdb.rpm && ferretdb --version'
     env:
       VERSION:
-        sh: cat ../internal/util/version/gen/version.txt
+        sh: cat ../build/version/version.txt
       GOARCH:
         sh: go env GOARCH
 

diff --git a/build/deps/cockroach.Dockerfile b/build/deps/cockroach.Dockerfile
@@ -1 +1 @@
-FROM cockroachdb/cockroach:v22.2.0
+FROM cockroachdb/cockroach:v22.2.1
diff --git a/build/nfpm.yaml b/build/nfpm.yaml
@@ -12,5 +12,5 @@ description: >
 homepage: https://ferretdb.io
 license: Apache License 2.0
 contents:
-  - src: ../bin/ferretdb-testcover
+  - src: ../bin/ferretdb
     dst: /usr/bin/ferretdb
diff --git a/build/version/debug_off.go b/build/version/debug_off.go
@@ -0,0 +1,22 @@
+// Copyright 2021 FerretDB Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !(ferretdb_debug || ferretdb_testcover || race)
+
+package version
+
+// debugBuild is false if that's not a debug build.
+//
+// See package documentation for more details.
+const debugBuild = false
diff --git a/build/version/debug_on.go b/build/version/debug_on.go
@@ -0,0 +1,22 @@
+// Copyright 2021 FerretDB Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build ferretdb_debug || ferretdb_testcover || race
+
+package version
+
+// debugBuild is true if that's a debug build.
+//
+// See package documentation for more details.
+const debugBuild = true
diff --git a/internal/util/version/generate.go → build/version/generate.go b/internal/util/version/generate.go → build/version/generate.go
@@ -21,7 +21,6 @@ import (
 	"log"
 	"os"
 	"os/exec"
-	"path/filepath"
 	"strings"
 	"sync"
 
@@ -44,31 +43,31 @@ func runGit(args ...string) []byte {
 // saveFile stores the given bytes in the given file with logging.
 func saveFile(b []byte, filename string) {
 	log.Printf("%s: %s", filename, b)
-	must.NoError(os.WriteFile(filepath.Join("gen", filename), b, 0o666))
+	must.NoError(os.WriteFile(filename, b, 0o666))
 }
 
 func main() {
 	log.SetFlags(0)
 
 	var wg sync.WaitGroup
 
-	// git describe --tags --dirty > gen/version.txt
+	// git describe --dirty > version.txt
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
 
-		saveFile(runGit("describe", "--tags", "--dirty"), "version.txt")
+		saveFile(runGit("describe", "--dirty"), "version.txt")
 	}()
 
-	// git rev-parse HEAD > gen/commit.txt
+	// git rev-parse HEAD > commit.txt
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
 
 		saveFile(runGit("rev-parse", "HEAD"), "commit.txt")
 	}()
 
-	// git branch --show-current > gen/branch.txt
+	// git branch --show-current > branch.txt
 	wg.Add(1)
 	go func() {
 		defer wg.Done()

diff --git a/internal/util/version/gen/mongodb.txt → build/version/mongodb.txt b/internal/util/version/gen/mongodb.txt → build/version/mongodb.txt
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		FROM cockroachdb/cockroach:v22.2.0
		FROM cockroachdb/cockroach:v22.2.1