Add Taskfile to build package; Refactor docs tasks. (#46)

README.md

@@ -28,24 +28,32 @@ version >= 3.6.
 
 ## Building/Packaging
 
-To manually build a package for distribution, run the following steps. You will
-need a C++ compiler which supports `std::span` (e.g. `clang++` >= 7 or
-`g++` >= 10). The steps below will generate both a `.tar.gz` and `.whl` package
-under `./dist/`.
+To manually build a package for distribution, follow the steps below.
 
-```bash
-# 1. Create and enter a virtual environment
-python -m venv venv && . ./venv/bin/activate
+### Requirements
 
-# 2. Install development dependencies
-pip install -r requirements-dev.txt
+* A C++ compiler that supports C++20 and `std::span` (e.g. `clang++` >= 7 or
+  `g++` >= 10).
+* python3
+* python3-dev
+* python3-venv
+* [Task][18] >= 3.35.1
 
-# 3. Pull all submodules in preparation for building
-git submodule update --init --recursive
+### Build commands
 
-# 4. Build
-python -m build --outdir build/dist
-```
+* Build a Python wheel incrementally:
+
+  ```bash
+  task
+  ```
+  The command above will generate both a `.tar.gz` and `.whl` package under
+  `./build/dist/`.
+
+* Clean up the build:
+
+  ```bash
+  task clean
+  ```
 
 ## CLP IR Readers
 
@@ -302,3 +310,4 @@ other package management tools such as `apt-get`:
 [15]: https://docs.python.org/3/library/pickle.html
 [16]: https://pypi.org/project/clp-ffi-py/
 [17]: https://github.com/RaRe-Technologies/smart_open
+[18]: https://taskfile.dev/installation/

Taskfile.yml

@@ -0,0 +1,115 @@
+version: "3"
+
+includes:
+  docs:
+    taskfile: "docs/tasks.yml"
+
+vars:
+  # Paths
+  BUILD_DIR: "{{.ROOT_DIR}}/build"
+  WHEEL_BUILD_DIR: "{{.BUILD_DIR}}/dist"
+  WHEEL_VENV_DIR: "{{.BUILD_DIR}}/wheel-venv"
+
+tasks:
+  default:
+    deps: ["wheel"]
+
+  clean:
+    cmds:
+      - "rm -rf '{{.BUILD_DIR}}'"
+
+  wheel:
+    vars:
+      CHECKSUM_FILE: "{{.BUILD_DIR}}/{{.TASK}}.md5"
+      OUTPUT_DIR: "{{.WHEEL_BUILD_DIR}}"
+    deps:
+      - "submodules"
+      - "wheel-venv"
+    cmds:
+      - "rm -rf '{{.OUTPUT_DIR}}'"
+      - |-
+        . "{{.WHEEL_VENV_DIR}}/bin/activate"
+        python3 -m build --outdir "{{.OUTPUT_DIR}}"
+      # Checksum the generated files (this command must be last)
+      - |-
+        cd "{{.OUTPUT_DIR}}"
+        tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum > "{{.CHECKSUM_FILE}}"
+    sources:
+      - "{{.BUILD_DIR}}/submodules.md5"
+      - "{{.BUILD_DIR}}/wheel-venv.md5"
+      - "{{.TASKFILE}}"
+      - "clp_ffi_py/**/*"
+      - "src/**/*"
+    status:
+      - "test -f '{{.CHECKSUM_FILE}}'"
+      - >-
+        diff
+        <(cd '{{.OUTPUT_DIR}}' && tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum)
+        "{{.CHECKSUM_FILE}}"
+
+  build-venv:
+    internal: true
+    label: "{{.COMPONENT}}-{{.TASK}}"
+    requires:
+      vars:
+        - "COMPONENT"
+        - "OUTPUT_DIR"
+        - "REQUIREMENTS_FILE_PATH"
+    cmds:
+      - "rm -rf '{{.OUTPUT_DIR}}'"
+      - "python3 -m venv '{{.OUTPUT_DIR}}'"
+      - |-
+        . "{{.OUTPUT_DIR}}/bin/activate"
+        pip3 install -r "{{.REQUIREMENTS_FILE_PATH}}"
+
+  submodules:
+    internal: true
+    vars:
+      CHECKSUM_FILE: "{{.BUILD_DIR}}/{{.TASK}}.md5"
+      OUTPUT_DIR: "src/clp"
+    preconditions:
+      # Ensure there are no uncommitted changes to the submodules since the submodule update
+      # command might undo them. Specifically, the update command will undo any uncommitted changes
+      # to the commits that the submodules point to.
+      - sh: "git diff --quiet src/clp"
+        msg: "There are uncommitted changes to the submodules. Commit or stash them first."
+    cmds:
+      - "git submodule update --init --recursive"
+      # Checksum the generated files (this command must be last)
+      - |-
+        cd "{{.OUTPUT_DIR}}"
+        tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum > "{{.CHECKSUM_FILE}}"
+    sources:
+      - "{{.TASKFILE}}"
+      - ".gitmodules"
+    status:
+      - "test -f '{{.CHECKSUM_FILE}}'"
+      - >-
+        diff
+        <(cd '{{.OUTPUT_DIR}}' && tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum)
+        "{{.CHECKSUM_FILE}}"
+
+  wheel-venv:
+    internal: true
+    vars:
+      CHECKSUM_FILE: "{{.BUILD_DIR}}/{{.TASK}}.md5"
+      OUTPUT_DIR: "{{.WHEEL_VENV_DIR}}"
+    cmds:
+      - task: "build-venv"
+        vars:
+          COMPONENT: "wheel"
+          OUTPUT_DIR: "{{.OUTPUT_DIR}}"
+          REQUIREMENTS_FILE_PATH: "requirements-dev.txt"
+      # Checksum the generated files (this command must be last)
+      - |-
+        cd "{{.OUTPUT_DIR}}"
+        tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum > "{{.CHECKSUM_FILE}}"
+    sources:
+      - "{{.TASKFILE}}"
+      - "requirements-dev.txt"
+    status:
+      - "test -f '{{.CHECKSUM_FILE}}'"
+      - >-
+        diff
+        <(cd '{{.OUTPUT_DIR}}' && tar cf - {{.CHECKSUM_TAR_BASE_ARGS}} . | md5sum)
+        "{{.CHECKSUM_FILE}}"

docs/README.md

@@ -8,49 +8,44 @@ documentation website for this package:
 
 ## Requirements
 
-We use the following tools to build the site:
-
-* python3
-* python3-venv
-* [Task][1]
+* All the [requirements](../README.md#requirements) for building the Python
+  package.
+* [Node.js] >= 16 to be able to [view the output](#viewing-the-output)
 
 ## Build Commands
 
 * Build the site incrementally:
 
   ```shell
-  task
+  task docs:site
   ```
 
   * The output of the build will be in `../build/docs/html`.
   * API reference docs will be written to `src/api`.
 
-* Clean-up the build:
+* Clean up the build:
 
   ```shell
-  task clean
+  task docs:clean
   ```
 
 ## Viewing the Output
 
-You can use [Node.js' npm][2] with [http-server][3] to view the output:
-
 ```shell
-npx http-server ../build/docs/html -c-1
+task docs:serve
 ```
 
-We use `-c-1` to disable caching during development.
+The command above will install [http-server] and serve the built docs site.
 
-# Integration with [yscope-docs][4]
+# Integration with [yscope-docs]
 
-To support hosting on [docs.yscope.com][5], we need:
+To support hosting on [docs.yscope.com], we need:
 
 * `build.sh` which builds a clean version of the site and outputs it to
   `../build/docs/html`.
 * `build.sh` must be runnable from any directory.
 
-[1]: https://taskfile.dev/
-[2]: https://nodejs.org/en/download/current
-[3]: https://www.npmjs.com/package/http-server
-[4]: https://github.com/y-scope/yscope-docs
-[5]: https://docs.yscope.com
+[docs.yscope.com]: https://docs.yscope.com
+[http-server]: https://www.npmjs.com/package/http-server
+[Node.js]: https://nodejs.org/en/download/current
+[yscope-docs]: https://github.com/y-scope/yscope-docs

docs/build.sh

@@ -4,8 +4,8 @@
 set -eu
 
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
-pushd "$script_dir"
+pushd "$script_dir/.."
 
-task clean && task
+task clean && task docs:site
 
 popd