Publish to crates.io

.devcontainer/Dockerfile

@@ -11,18 +11,16 @@ FROM rust:${RUST_IMAGE_LABEL} as base
 
 SHELL ["bash", "-c"]
 
-## Install linker and other utilities
-# RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-#     --mount=type=cache,target=/var/lib/apt,sharing=locked \
-#     apt-get update \
-#     && export DEBIAN_FRONTEND=noninteractive \
-#     && apt-get install -y --no-install-recommends mold clang \
-#     && apt-get autoremove -y \
-#     && apt-get clean -y \
-#     && rm -rf /var/lib/apt/lists/*
-## Alternatively, use `lld` instead of the `mold` linker
-## Configuration in .cargo/config.toml
-## If using the `slim` Rust image, you may need to install: curl pkg-config libssl-dev
+## Install utilities
+RUN apt-get update \
+    && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get install -y --no-install-recommends jq \
+    && apt-get autoremove -y \
+    && apt-get clean -y \
+    && rm -rf /var/lib/apt/lists/*
+## To cache:
+## --mount=type=cache,target=/var/cache/apt,sharing=locked \
+## --mount=type=cache,target=/var/lib/apt,sharing=locked \
 
 ## Update Rust if needed (note: `rustup update stable && rustup default stable` is required for Rust 1.74 -> Rust 1.75 somehow)
 RUN rustup update
@@ -83,7 +81,7 @@ ENTRYPOINT [ "./.devcontainer/dev.sh" ]
 CMD [ "sleep", "infinity" ]
 
 ## --------------------------------
-## Stage for Continuous Integration
+## Stage for Continuous Integration / Deployment
 FROM base as ci
 
 ## Copy the code in the container (in WORKDIR), excluding what is in .dockerignore
@@ -92,6 +90,10 @@ COPY . .
 ENV CARGO_TARGET_DIR=./target/
 
 ## Make sure the start scripts have permission to execute
-RUN chmod +x ./.devcontainer/ci.sh
+RUN chmod +x ./.devcontainer/ci.sh ./.devcontainer/publish.sh
 
+## `ci.sh` builds / tests the code and builds / tests the user guide.
+## The user guide HTML that has been built is exported
+## via the bind mount in `compose-ci.yaml` back to the CI host,
+## so that it could be deployed to GitHub Pages.
 ENTRYPOINT [ "./.devcontainer/ci.sh" ]

.devcontainer/ci.sh

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+#! /usr/bin/env bash
 set -eux
 set -o pipefail
 

.devcontainer/compose-ci.yaml

@@ -18,3 +18,12 @@ services:
         target: /code/userguide/book/
         bind:
           create_host_path: true
+    secrets:
+      - crates_token
+
+## crates_token secret is created as <project_name>_crates_token when the application is deployed,
+## by registering the content of the CRATES_TOKEN environment variable as a platform secret.
+## https://docs.docker.com/compose/compose-file/09-secrets/
+secrets:
+  crates_token:
+    environment: "CRATES_TOKEN"

.devcontainer/publish.sh

@@ -0,0 +1,58 @@
+#! /usr/bin/env bash
+set -eu
+set -o pipefail
+
+echo "This script packages and publishes the crate to https://crates.io/"
+echo "It is meant to run AFTER ci.sh"
+
+# https://pubs.opengroup.org/onlinepubs/9699919799/utilities/getopts.html
+yflag=
+while getopts y name
+do
+    case $name in
+    y)   yflag=1;;
+    ?)   printf "Usage: %s -y\nThe -y option is REQUIRED to confirm publication.\n" $0
+         exit 2;;
+    esac
+done
+shift $(($OPTIND - 1))
+
+## -z tests if the string has zero length
+if [ -z "$yflag" ]; then
+    echo "You MUST pass the -y option to confirm that you truly want to PUBLISH."
+    exit 1
+fi
+
+## if the CRATES_TOKEN env var is defined, build, then package and publish
+if [ ! -v CRATES_TOKEN ]; then
+  echo "The env. variable CRATES_TOKEN is not set."
+  exit 3
+fi
+
+echo "----------"
+CARGO_TOML_VERSION=$(cargo metadata --no-deps --locked --format-version 1 | jq '.packages | .[0] | .version')
+echo "Version in Cargo.toml: ${CARGO_TOML_VERSION}"
+
+CRATES_IO_VERSION=$(cargo search mdbook-utils | sed -E 's/^.*"(.*)".*$/\1/')
+echo "Version in crates.io: ${CRATES_IO_VERSION}"
+
+# GIT_TAG=$(git describe --tags $(git rev-list --tags --max-count=1))
+# echo "Git tag: ${GIT_TAG}"
+
+## TODO check that the last commit has been tagged, that the tag corresponds to the version in Cargo.toml,
+## and that the version number is larger than the one in crates.io.
+# https://stackoverflow.com/questions/1474115/how-to-find-the-tag-associated-with-a-given-git-commit
+# https://stackoverflow.com/questions/1404796/how-can-i-get-the-latest-tag-name-in-current-branch-in-git
+# git log --pretty=oneline
+# git tag
+# git describe --exact-match <commit-id>
+
+echo "----------"
+echo "Files that will be packaged:"
+cargo package --locked --list  # Print files included in a package.
+
+echo "----------"
+echo "Package & publish:"
+cargo publish --dry-run --locked --token ${CRATES_TOKEN}
+
+echo "----------"