From 96478ed0168ca68e0108d0c76d30276c4b9ddc5f Mon Sep 17 00:00:00 2001 From: Remo Rechkemmer <59358383+monacoremo@users.noreply.github.com> Date: Mon, 28 Dec 2020 13:23:12 +0100 Subject: [PATCH] Add docs to all checked shell scripts in nix --- nix/UPGRADE.md | 4 +- nix/devtools.nix | 64 ++++++++++++++++--- nix/docker/default.nix | 7 +- nix/nixpkgs-upgrade.nix | 10 ++- .../checked-shell-script.nix | 12 ++-- nix/release/default.nix | 37 ++++++++--- nix/style.nix | 21 +++++- nix/tests.nix | 46 ++++++++++--- 8 files changed, 161 insertions(+), 40 deletions(-) diff --git a/nix/UPGRADE.md b/nix/UPGRADE.md index 1983bd18b..c561a804a 100644 --- a/nix/UPGRADE.md +++ b/nix/UPGRADE.md @@ -5,7 +5,7 @@ should be a very simple operation. ```bash # Update pinned version of Nixpkgs -nix-shell --run nixpkgs-upgrade > nix/nixpkgs-version.nix +nix-shell --run postgrest-nixpkgs-upgrade # Verify that everything builds nix-build @@ -27,7 +27,7 @@ the complete Git repository. To upgrade it to the current `master` of nix-shell # Run the utility script to pin the latest revision in master -nixpkgs-upgrade > nix/nixpkgs-version.nix +postgrest-nixpkgs-upgrade # Exit the nix-shell with Ctrl-d diff --git a/nix/devtools.nix b/nix/devtools.nix index 38ad2c523..5aeaf7de0 100644 --- a/nix/devtools.nix +++ b/nix/devtools.nix @@ -9,7 +9,20 @@ }: let watch = - checkedShellScript "postgrest-watch" + checkedShellScript + { + name = "postgrest-watch"; + docs = + '' + Watch the project for changes and reinvoke the given command. + + Example: + + postgrest-watch postgrest-test-io + + ''; + inRootDir = true; + } '' while true; do (! ${silver-searcher}/bin/ag -l . | ${entr}/bin/entr -dr "$@") @@ -17,28 +30,63 @@ let ''; pushCachix = - checkedShellScript "postgrest-push-cachix" + checkedShellScript + { + name = "postgrest-push-cachix"; + docs = '' + Push all build artifacts to cachix. + + Requires that the CACHIX_SIGNING_KEY for postgrest is set as an + environment variable. + ''; + inRootDir = true; + } '' - nix-store -qR --include-outputs "$(nix-instantiate)" \ - | cachix push postgrest + nix-store -qR --include-outputs "$(nix-instantiate)" | cachix push postgrest ''; build = - checkedShellScript "postgrest-build" + checkedShellScript + { + name = "postgrest-build"; + docs = "Build PostgREST interactively using cabal-install."; + inRootDir = true; + } ''exec ${cabal-install}/bin/cabal v2-build ${devCabalOptions} "$@"''; run = - checkedShellScript "postgrest-run" + checkedShellScript + { + name = "postgrest-run"; + docs = "Run PostgREST after buidling it interactively with cabal-install"; + inRootDir = true; + } ''exec ${cabal-install}/bin/cabal v2-run ${devCabalOptions} --verbose=0 -- postgrest "$@"''; clean = - checkedShellScript "postgrest-clean" + checkedShellScript + { + name = "postgrest-clean"; + docs = "Clean the PostgREST project, including all cabal-install artifacts."; + inRootDir = true; + } '' ${cabal-install}/bin/cabal v2-clean ''; check = - checkedShellScript "postgrest-check" + checkedShellScript + { + name = "postgrest-check"; + docs = + '' + Run most checks that will also run on CI. + + This currently excludes the memory tests, as those are particularly + expensive. + ''; + inRootDir = true; + } '' ${tests}/bin/postgrest-test-spec-all ${tests}/bin/postgrest-test-spec-idempotence diff --git a/nix/docker/default.nix b/nix/docker/default.nix index f88523292..28c28c779 100644 --- a/nix/docker/default.nix +++ b/nix/docker/default.nix @@ -28,9 +28,12 @@ let }; }; - # Helper script for loading the image. load = - checkedShellScript "postgrest-docker-load" + checkedShellScript + { + name = "postgrest-docker-load"; + docs = "Load the PostgREST image into Docker."; + } '' docker load -i ${image} ''; diff --git a/nix/nixpkgs-upgrade.nix b/nix/nixpkgs-upgrade.nix index 3ebe2e538..e903dcc53 100644 --- a/nix/nixpkgs-upgrade.nix +++ b/nix/nixpkgs-upgrade.nix @@ -10,7 +10,7 @@ # to pin. let name = - "nixpkgs-upgrade"; + "postgrest-nixpkgs-upgrade"; refUrl = https://api.github.com/repos/nixos/nixpkgs/git/ref/heads/nixpkgs-unstable; @@ -23,14 +23,18 @@ let script = checkedShellScript - name + { + inherit name; + docs = "Pin the newest unstable version of Nixpkgs."; + inRootDir = true; + } '' commitHash="$(${curl}/bin/curl "${refUrl}" -H "${githubV3Header}" | ${jq}/bin/jq -r .object.sha)" tarballUrl="${tarballUrlBase}$commitHash.tar.gz" tarballHash="$(${nix}/bin/nix-prefetch-url --unpack "$tarballUrl")" currentDate="$(date --iso)" - cat << EOF + cat > nix/nixpkgs-version.nix << EOF # Pinned version of Nixpkgs, generated with ${name}. { date = "$currentDate"; diff --git a/nix/overlays/checked-shell-script/checked-shell-script.nix b/nix/overlays/checked-shell-script/checked-shell-script.nix index 37fd6ef36..a776e0c69 100644 --- a/nix/overlays/checked-shell-script/checked-shell-script.nix +++ b/nix/overlays/checked-shell-script/checked-shell-script.nix @@ -2,13 +2,15 @@ # directly, or use the .bin attribute to get the script in a bin/ directory, # to be used in a path for example. { git +, lib , runCommand , runtimeShell , shellcheck , stdenv , writeTextFile }: -name: text: +{ name, docs, inRootDir ? false }: text: +# TODO: do something sensible with docs, e.g. provide automated --help let bin = writeTextFile { @@ -20,7 +22,8 @@ let '' #!${runtimeShell} set -euo pipefail - + '' + + lib.optionalString inRootDir '' cd "$(${git}/bin/git rev-parse --show-toplevel)" if test ! -f postgrest.cabal; then @@ -28,9 +31,8 @@ let "run this command somewhere in the PostgREST repo." exit 1 fi - - ${text} - ''; + '' + + text; checkPhase = '' diff --git a/nix/release/default.nix b/nix/release/default.nix index 9f9efc24a..d9fd2c25e 100644 --- a/nix/release/default.nix +++ b/nix/release/default.nix @@ -9,9 +9,13 @@ , checkedShellScript }: let - # Script for publishing a new release on GitHub. github = - checkedShellScript "postgrest-release-github" + checkedShellScript + { + name = "postgrest-release-github"; + docs = "Push a new release to GitHub."; + inRootDir = true; + } '' version=$1 @@ -43,17 +47,29 @@ let fi ''; - # Wrapper for login with docker. $DOCKER_USER/$DOCKER_PASS vars come from CircleCI. - # The DOCKER_USER is not the same as DOCKER_REPO because we use the https://hub.docker.com/u/postgrestbot account for uploading to dockerhub. dockerLogin = - checkedShellScript "postgrest-docker-login" + checkedShellScript + { + name = "postgrest-docker-login"; + docs = + '' + Log in to Docker Hub using the DOCKER_USER and DOCKER_PASS env vars. + + Those env vars are usually provided by CircleCI. The DOCKER_USER is + not the same as DOCKER_REPO because we use the + https://hub.docker.com/u/postgrestbot account for uploading to dockerhub. + ''; + } '' docker login -u "$DOCKER_USER" -p "$DOCKER_PASS" ''; - # Script for publishing a new release on Docker Hub. dockerHub = - checkedShellScript "postgrest-release-dockerhub" + checkedShellScript + { + name = "postgrest-release-dockerhub"; + docs = "Push a new release to Docker Hub"; + } '' version=$1 @@ -74,7 +90,6 @@ let fi ''; - # Script for updating the repository description on Docker Hub. dockerHubDescription = let description = @@ -83,7 +98,11 @@ let fullDescription = ./docker-hub-full-description.md; in - checkedShellScript "postgrest-release-dockerhubdescription" + checkedShellScript + { + name = "postgrest-release-dockerhubdescription"; + docs = "Update the repository description on Docker Hub."; + } '' # Login to Docker Hub and get a token. token="$( diff --git a/nix/style.nix b/nix/style.nix index 5f26f50f4..74083ff26 100644 --- a/nix/style.nix +++ b/nix/style.nix @@ -9,7 +9,12 @@ }: let style = - checkedShellScript "postgrest-style" + checkedShellScript + { + name = "postgrest-style"; + docs = "Automatically format Haskell, Nix and Python files."; + inRootDir = true; + } '' # Format Nix files ${nixpkgs-fmt}/bin/nixpkgs-fmt . > /dev/null 2> /dev/null @@ -25,7 +30,12 @@ let # Script to check whether any uncommited changes result from postgrest-style styleCheck = - checkedShellScript "postgrest-style-check" + checkedShellScript + { + name = "postgrest-style-check"; + docs = "Check whether postgrest-style results in any uncommited changes."; + inRootDir = true; + } '' ${style} @@ -33,7 +43,12 @@ let ''; lint = - checkedShellScript "postgrest-lint" + checkedShellScript + { + name = "postgrest-lint"; + docs = "Lint all Haskell files."; + inRootDir = true; + } '' # Lint Haskell files # --vimgrep fixes a bug in ag: https://github.com/ggreer/the_silver_searcher/issues/753 diff --git a/nix/tests.nix b/nix/tests.nix index 087d9d744..2b2555f69 100644 --- a/nix/tests.nix +++ b/nix/tests.nix @@ -22,11 +22,16 @@ let # Wrap the `test/with_tmp_db` script with the required dependencies from Nix. withTmpDb = postgresql: - checkedShellScript "postgrest-test-${postgresql.name}" + checkedShellScript + { + name = "postgrest-test-withtmpdb-${postgresql.name}"; + docs = "Run the given command in a temporary database"; + inRootDir = true; + } '' export PATH=${postgresql}/bin:"$PATH" - exec ${../test/with_tmp_db} "$@" + exec test/with_tmp_db "$@" ''; # Script to run the Haskell test suite against a specific version of @@ -34,7 +39,11 @@ let testSpec = name: postgresql: checkedShellScript - name + { + inherit name; + docs = "Run the Haskell test suite against ${postgresql.name}."; + inRootDir = true; + } '' env="$(cat ${postgrest.env})" export PATH="$env/bin:$PATH" @@ -61,7 +70,11 @@ let testSpecIdempotence = name: postgrestql: checkedShellScript - name + { + inherit name; + docs = "Check that the Haskell tests can be run multiple times against the same db."; + inRootDir = true; + } '' env="$(cat ${postgrest.env})" export PATH="$env/bin:$PATH" @@ -85,7 +98,12 @@ let testRunners = map (test: "${test}/bin/${test.name}") testSpecVersions; in - checkedShellScript "postgrest-test-spec-all" + checkedShellScript + { + name = "postgrest-test-spec-all"; + docs = "Run the Haskell tests against all supported PostgreSQL versions."; + inRootDir = true; + } (lib.concatStringsSep "\n" testRunners); ioTestPython = @@ -101,7 +119,11 @@ let testIO = name: postgresql: checkedShellScript - name + { + inherit name; + docs = "Run the pytest-based IO tests."; + inRootDir = true; + } '' env="$(cat ${postgrest.env})" export PATH="$env/bin:$PATH" @@ -114,7 +136,11 @@ let testMemory = name: postgresql: checkedShellScript - name + { + inherit name; + docs = "Run the memory tests."; + inRootDir = true; + } '' export PATH="${postgrestProfiled}/bin:${curl}/bin:$PATH" @@ -124,7 +150,11 @@ let dumpSchema = name: postgresql: checkedShellScript - name + { + inherit name; + docs = "Dump the loaded schema's DbStructure as a yaml file."; + inRootDir = true; + } '' env="$(cat ${postgrest.env})" export PATH="$env/bin:$PATH"