feat(taskfile): Add more build tasks and rename others according to latest conventions: (#70)

- Change tasks to support building a subset of libraries through `ystdlib_LIBRARIES`.
- Add tasks for building debug and release versions.
- Add tasks for building examples.
- Rename tasks to begin with the verb.

Co-authored-by: kirkrodrigues <[email protected]>
Co-authored-by: Bingran Hu <[email protected]>

Author: 3 people

.gersemirc

@@ -3,6 +3,6 @@
 
 definitions:
   - "cmake/ystdlib-helpers.cmake"
-  - "build/deps/Catch2/Catch2-src/extras/Catch.cmake"
+  - "build/deps/Catch2-src/extras/Catch.cmake"
 line_length: 100
 list_expansion: "favour-expansion"

.github/workflows/code-linting-checks.yaml

@@ -37,6 +37,17 @@ jobs:
         shell: "bash"
         run: "npm install -g @go-task/cli"
 
+      - name: "Install uv"
+        shell: "bash"
+        run: |-
+          curl \
+            --fail \
+            --location \
+            --silent \
+            --show-error \
+            https://astral.sh/uv/0.8.4/install.sh \
+          | sh
+
       - name: "Run lint task"
         shell: "bash"
         run: "task lint:check"

.github/workflows/unit-tests.yaml

@@ -25,6 +25,9 @@ jobs:
           - "macos-15"
           - "ubuntu-22.04"
           - "ubuntu-24.04"
+        build_type:
+          - "debug"
+          - "release"
     runs-on: "${{matrix.os}}"
     steps:
       - uses: "actions/checkout@v4"
@@ -45,7 +48,7 @@ jobs:
           brew install coreutils
           brew install llvm@16
 
-      - name: "Run unit tests"
+      - name: "Run unit tests and examples"
         env: >-
           ${{
           'macos-14' == matrix.os
@@ -55,4 +58,8 @@ jobs:
           }')
           || fromJson('{}')
           }}
-        run: "task test-all"
+        # Currently unit tests rely on cassert and fail to compile in release mode.
+        run: |-
+          task test:run-debug
+          task examples:build-${{matrix.build_type}}
+          ./build/examples/${{matrix.build_type}}/linking-tests

README.md

@@ -43,6 +43,7 @@ Follow the steps below to develop and contribute to the project.
 * CMake 3.23 or higher
 * Python 3.10 or higher
 * [Task] 3.40.0 or higher
+* [uv] 0.7.10 or higher
 
 ## Set up
 Initialize and update submodules:
@@ -52,33 +53,32 @@ git submodule update --init --recursive
 
 If you want to open the project in an IDE, run the following command to install any necessary
 dependencies from source:
+
 ```shell
 task deps:install-all
 ```
 
 ## Building
 
-The library can be built directly using [CMake](#using-cmake) or indirectly using
-[Task](#using-task).
+The library can be built via [Task](#building-using-task) or directly with
+[CMake](#building-using-cmake).
 
-### Using Task
+### <a id="building-using-task" />Using Task
 
-To build all targets:
-```shell
-task build:all
-```
+To build all libraries:
 
-To build an executable containing all unit tests:
 ```shell
-task build:unit-test-all
+task ystdlib:build-release
 ```
 
-To build an executable containing a single library's unit tests:
+To build a subset of libraries, set the [`ystdlib_LIBRARIES` parameter](#ystdlib_libraries). For
+example:
+
 ```shell
-task build:unit-test-<lib_name>
+task ystdlib:build-release ystdlib_LIBRARIES="containers;io_interface"
 ```
 
-### Using CMake
+### <a id="building-using-cmake" />Using CMake
 
 To build all libraries, run:
 
@@ -87,37 +87,57 @@ cmake -S . -B ./build
 cmake --build ./build
 ```
 
-To build a subset of libraries, set the variable `ystdlib_LIBRARIES` to a semicolon-separated (`;`)
-list of library names. The library names match their [directory name in src/](./src/ystdlib). For
+To build a subset of libraries, set the [`ystdlib_LIBRARIES` parameter](#ystdlib_libraries). For
 example:
 
 ```shell
 cmake -S . -B ./build -Dystdlib_LIBRARIES="containers;io_interface"
 cmake --build ./build
 ```
 
-> [!NOTE]
-> Internal dependencies of the libraries you choose will be automatically built, even if you don't
-> explicitly specify them. In the example, specifying `io_interface` automatically adds
-> `wrapped_facade_headers` to the build.
-
 ## Installing
 
-After [building](#building), install with:
+The library can be installed via [Task](#installing-using-task) or directly with
+[CMake](#installing-using-cmake).
+
+### <a id="installing-using-task" />Using Task
+
+To build and install all libraries, run:
+
+```shell
+task ystdlib:install-release INSTALL_PREFIX="$HOME/.local"
+```
+
+To build and install a subset of libraries, set the
+[`ystdlib_LIBRARIES` parameter](#ystdlib_libraries). For example:
+
+```shell
+task ystdlib:install-release \
+    INSTALL_PREFIX="$HOME/.local" \
+    ystdlib_LIBRARIES="containers;io_interface"
+```
+
+### <a id="installing-using-cmake" />Using CMake
+
+After [building](#building-using-cmake), to install all built libraries, run:
 
 ```shell
 cmake --install "./build" --prefix "$HOME/.local"
 ```
 
 ## Testing
+
 To build and run all unit tests:
+
 ```shell
-task test-all
+task test:run-debug
 ```
 
-To build and run unit tests for a specific library:
+To build and run unit tests for a subset of libraries, set the
+[`ystdlib_LIBRARIES` parameter](#ystdlib_libraries). For example:
+
 ```shell
-task test-<lib_name>
+task test:run-debug ystdlib_LIBRARIES="containers;io_interface"
 ```
 
 When generating a testing target, the CMake variable `BUILD_TESTING` is followed (unless overruled
@@ -144,4 +164,39 @@ task -a
 ```
 Look for all tasks under the `lint` namespace (identified by the `lint:` prefix).
 
+## Build and install parameters
+
+The following parameters are common between multiple tasks and CMake.
+
+### `ystdlib_LIBRARIES`
+
+The parameter/variable `ystdlib_LIBRARIES` can be used to target a subset of libraries, by setting
+it to a semicolon-separated (`;`) list of library names. The library names match their
+[directory name in `src/`](./src/ystdlib).
+
+> [!NOTE]
+> Internal dependencies of the libraries you choose will be automatically built, even if you don't
+> explicitly specify them. In the following examples, specifying `io_interface` automatically adds
+> `wrapped_facade_headers` to the build.
+
+#### Using Task
+
+Set by adding it after the task name. For example:
+
+```shell
+task ystdlib:build-release ystdlib_LIBRARIES="containers;io_interface"
+```
+
+Not all tasks support `ystdlib_LIBRARIES`. You can check if a task supports it by reading its
+description (run `task -a` to view all tasks and descriptions).
+
+#### Using CMake
+
+Set using the `-D` flag in the generation step. For example:
+
+```shell
+cmake -S . -B ./build -Dystdlib_LIBRARIES="containers;io_interface"
+```
+
 [Task]: https://taskfile.dev
+[uv]: https://docs.astral.sh/uv

examples/README.md

@@ -5,13 +5,33 @@ This directory contains example programs that demonstrate how to use the ystdlib
 The example program `linking-tests` references all of ystdlib's library targets to ensure they can
 be installed and linked correctly.
 
-## Requirements
+## Building
+
+### Using Task
+
+#### Requirements
+
+See the [ystdlib Requirements section](../README.md#requirements).
+
+#### Commands
+
+```shell
+# debug build
+task examples:build-debug
+
+# release build
+task examples:build-release
+```
+
+### Using CMake
+
+#### Requirements
 
 [Build](../README.md#building) and [install](../README.md#installing) ystdlib. The commands below
 assume you've built and installed ystdlib to `./build/examples/ystdlib`. If you installed it to a
 different location, adjust the paths accordingly.
 
-## Building
+#### Commands
 
 ```shell
 cmake -S "./examples" -B "./build/examples" -Dystdlib_ROOT="./build/examples/ystdlib"

taskfile.yaml

@@ -4,26 +4,25 @@ set: ["u", "pipefail"]
 shopt: ["globstar"]
 
 includes:
-  build: "./taskfiles/build.yaml"
   deps: "./taskfiles/deps.yaml"
+  examples: "./taskfiles/examples.yaml"
   lint: "./taskfiles/lint.yaml"
-  utils: "tools/yscope-dev-utils/exports/taskfiles/utils/utils.yaml"
+  test: "./taskfiles/test.yaml"
+  ystdlib: "./taskfiles/ystdlib.yaml"
 
 vars:
-  G_BUILD_DIR: "{{.ROOT_DIR}}/build"
-  G_CPP_SRC_DIR: "{{.ROOT_DIR}}/src"
-  G_DEPS_DIR: "{{.G_BUILD_DIR}}/deps"
-
-  # These should be kept in-sync with its usage in CMakeLists.txt
-  G_DEPS_CMAKE_SETTINGS_DIR: "{{.G_DEPS_DIR}}/cmake-settings"
-  G_DEPS_CMAKE_SETTINGS_FILE: "{{.G_DEPS_CMAKE_SETTINGS_DIR}}/all.cmake"
+  # General variables
+  # This must match the package name in CMakeLists.txt.
+  G_CMAKE_PACKAGE_NAME: "ystdlib"
 
-  G_TEST_BIN_DIR: "{{.G_BUILD_DIR}}/testbin"
-  G_TEST_TARGET_SUFFIXES:
-    - "all"
-    - "containers"
-    - "error_handling"
-    - "wrapped_facade_headers"
+  # Build directories
+  G_BUILD_DIR: "{{.ROOT_DIR}}/build"
+  G_EXAMPLES_BUILD_DIR: "{{.G_BUILD_DIR}}/examples"
+  G_EXAMPLES_DEBUG_BUILD_DIR: "{{.G_EXAMPLES_BUILD_DIR}}/debug"
+  G_EXAMPLES_RELEASE_BUILD_DIR: "{{.G_EXAMPLES_BUILD_DIR}}/release"
+  G_YSTDLIB_BUILD_DIR: "{{.G_BUILD_DIR}}/{{.G_CMAKE_PACKAGE_NAME}}"
+  G_YSTDLIB_DEBUG_BUILD_DIR: "{{.G_YSTDLIB_BUILD_DIR}}/debug"
+  G_YSTDLIB_RELEASE_BUILD_DIR: "{{.G_YSTDLIB_BUILD_DIR}}/release"
 
 tasks:
   clean:
@@ -37,13 +36,3 @@ tasks:
     run: "once"
     cmds:
       - "mkdir -p '{{.G_BUILD_DIR}}'"
-
-  test-*:
-    desc: "Runs unit tests for the specified test target."
-    vars:
-      TEST_TARGET: >-
-        {{printf "unit-test-%s" (index .MATCH 0)}}
-    deps:
-      - "build:{{.TEST_TARGET}}"
-    cmds:
-      - "{{.G_TEST_BIN_DIR}}/{{.TEST_TARGET}}"