diff --git a/README.md b/README.md index 71f52a5..ed0e915 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ scripts/build.sh --release # also package release/job-search-- The build script builds the frontend and copies it into place for embedding (`npm run build` and `npm run sync` in `web/`, which need Node and npm; it runs `npm ci` first for a release, or when `web/node_modules` is missing). It -then runs `go generate ./...`, which needs `swag` installed (see +then runs `go generate ./...`, which needs `ocdsgen` and `swag` installed +(`scripts/install-dev-tools.sh`; see [Installation of dev tools](#installation-of-dev-tools)), and stamps the version from the latest git tag. A build from untagged commits is marked as a development build and isn't packaged unless `--force` is also given. @@ -246,24 +247,27 @@ Using a source called `example` as an illustration: ## Installation of dev tools -A number of tools have been used in the development of the project. Installation -of these tools can be done using `go install`. +`scripts/install-dev-tools.sh` installs everything needed to develop and +build the project: the Go tools below, with `go install`, and the frontend's +npm packages (`npm ci` in `web/`). It needs Go and Node.js 24 or later (with +npm), as the frontend's scripts run TypeScript directly. Run it again after +a tool's version in it changes. -To install the tools: ```bash -go install github.com/spf13/cobra-cli@latest -go install git.avsdev.uk/Go/go-ocds/cmd/ocdsgen@latest -go install github.com/pressly/goose/v3/cmd/goose@latest -go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest -go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc6 +scripts/install-dev-tools.sh ``` -`goose` creates new migration files (see `internal/store`); the migrations -themselves are applied by `job-search migrate`. `golangci-lint` uses the -project's `.golangci.json`. `swag` generates the API's OpenAPI 3.1 spec from -the handlers' comments (`swag init --v3.1`). Its v2, the version with OpenAPI -3 support, has only had release candidates so far, so it is pinned to one -rather than `@latest`. +| Tool | Version | Used for | +|---|---|---| +| `ocdsgen` (`git.avsdev.uk/Go/go-ocds`) | v1.0.0 | Generates the OCDS types in `internal/findatender/ocds` (`ocds_gen.go`) from `extensions.json`, run by `go generate` | +| `swag` | v2.0.0-rc6 | Generates the API's OpenAPI 3.1 description from the handlers' comments (`swag init --v3.1`), run by `go generate` | +| `golangci-lint` | latest | Lints the Go code with the project's `.golangci.json` | +| `goose` | latest | Creates new migration files (see `internal/store`); the migrations themselves are applied by `job-search migrate` | +| `cobra-cli` | latest | Adds cobra commands | -Ensure that the GOBIN path ($HOME/go/bin) is added to the environment before -running any of the tools. +The generators are pinned, as another version could generate different code. +`swag`'s v2, the version with OpenAPI 3 support, has only had release +candidates so far. `go generate ./...` and the build script run the +generators from PATH, so ensure that the GOBIN path (`$HOME/go/bin` by +default) is added to the environment before running any of the tools; the +script says if it isn't. diff --git a/internal/findatender/ocds/generate.go b/internal/findatender/ocds/generate.go index 25b431a..872e1d9 100644 --- a/internal/findatender/ocds/generate.go +++ b/internal/findatender/ocds/generate.go @@ -2,4 +2,4 @@ // the EU profile, UK extension, and the other extensions in extensions.json. package ocds -//go:generate go run git.avsdev.uk/Go/go-ocds/cmd/ocdsgen generate -c extensions.json -o ocds_gen.go -p ocds +//go:generate ocdsgen generate -c extensions.json -o ocds_gen.go -p ocds diff --git a/scripts/install-dev-tools.sh b/scripts/install-dev-tools.sh new file mode 100755 index 0000000..18c25f0 --- /dev/null +++ b/scripts/install-dev-tools.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash + +# Installs the tools needed to develop and build job-search: the Go tools +# (with go install, into $(go env GOBIN), or $(go env GOPATH)/bin), and the +# frontend's npm packages (with npm ci in web/). Run it from anywhere; run it +# again after a version below changes. + +set -euo pipefail + +cd "$(dirname "$0")/.." + +# The Go tools. A generator is pinned, as a different version could generate +# different code; the others follow their latest release. +GO_TOOLS=( + # Generates the OCDS types (internal/findatender/ocds) from extensions.json + "git.avsdev.uk/Go/go-ocds/cmd/ocdsgen@v1.0.0" + # Generates the API's OpenAPI 3.1 description; v2 is only a release + # candidate so far + "github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc6" + # Lints the Go code with .golangci.json + "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest" + # Creates migration files (internal/store/migrations) + "github.com/pressly/goose/v3/cmd/goose@latest" + # Adds cobra commands + "github.com/spf13/cobra-cli@latest" +) + +# The oldest Node.js the frontend's scripts run on: they run TypeScript +# directly. +NODE_MAJOR=24 + +for tool in "${GO_TOOLS[@]}"; do + echo "go install $tool" + go install "$tool" +done + +if ! command -v node >/dev/null || ! command -v npm >/dev/null; then + echo "Node.js $NODE_MAJOR or later (with npm) is needed for web/: install it, then run this again" >&2 + exit 1 +fi +node_version=$(node --version) +node_major=${node_version#v} +node_major=${node_major%%.*} +if (( node_major < NODE_MAJOR )); then + echo "Node.js $NODE_MAJOR or later is needed for web/, found $node_version" >&2 + exit 1 +fi + +echo "npm ci (web/)" +(cd web && npm ci) + +# go generate and the build script find the Go tools on PATH. +bin_dir=$(go env GOBIN) +if [[ -z $bin_dir ]]; then + bin_dir=$(go env GOPATH)/bin +fi +if [[ ":$PATH:" != *":$bin_dir:"* ]]; then + echo "Add $bin_dir to PATH, where the Go tools were installed" >&2 +fi + +echo "Installed the development tools"