0.2.0: the argument vector is passed unaltered, and continuous integration runs

This implementation prepended the path to the argument vector, as the companion
implementation did, and for the same reason: they were written by one author
from one reading of a specification that did not settle the point. Clause 7.6 of
openkal 0.4 settles it, and this is that change, together with an assertion that
observes the vector a started program received rather than only its status.

That both implementations made the same choice is not evidence that the choice
was right. It is evidence that a second implementation by the same author tests
less than a second implementation by another, which is the limit of what these
two can establish between them.

Continuous integration here had never passed a step it appeared to run. The
workflow was copied from the companion implementation and ran an example in a
directory this repository does not contain, asserting three lines from a
program that is not here. The failure had been reported as an inability to
start a shell in a working directory, which reads as an infrastructure fault
rather than as a missing example.

It is replaced by the portable program, which is taken from the specification at
the version the manifest names. That program is the only cross-implementation
evidence available to this repository: no continuous integration for the
companion implementation runs on this platform, and none for this one runs on
that.

The assertion that the suites ran named two of the five present, and is now
derived from the files. The surface comparison is now --complete.

Author: speak-agent

.github/workflows/ci.yml

@@ -35,30 +35,76 @@ jobs:
           mcpp --version
           mcpp self config --mirror GLOBAL
 
+      # The version of the specification this implementation is written against
+      # is stated once, in the manifest, and read from there. The companion
+      # implementation stated it a second time in this file and the two drifted.
+      - name: Read the specification version from the manifest
+        run: |
+          v="$(sed -n 's/^openkal[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' mcpp.toml | head -1)"
+          test -n "$v" || { echo "the manifest does not name openkal" >&2; exit 1; }
+          echo "OPENKAL_VERSION=$v" >> "$GITHUB_ENV"
+          echo "written against openkal $v"
+
       - name: Conformance
         run: |
           mcpp test 2>&1 | tee conformance.log
-          # A suite that discovered nothing reports success. Both cases are
-          # asserted to have run.
-          grep -q 'conformance_stream ... ok' conformance.log
-          grep -q 'conformance_memory ... ok' conformance.log
+
+          # A suite that discovered nothing reports success, so every suite is
+          # asserted to have run. The list is derived from the files present
+          # rather than written out here: a hand-written list names the suites
+          # that existed when it was written, and a suite added afterwards
+          # escapes the assertion silently. This assertion named two of five.
+          missing=0
+          for f in tests/*.cpp; do
+            name="$(basename "$f" .cpp)"
+            if ! grep -q "^$name \.\.\. ok" conformance.log; then
+              echo "suite did not run, or did not pass: $name" >&2
+              missing=1
+            fi
+          done
+          test "$missing" -eq 0
+
+      - name: The specification, at the version the manifest names
+        uses: actions/checkout@v4
+        with:
+          repository: mcpplibs/openkal
+          ref: ${{ env.OPENKAL_VERSION }}
+          path: .spec
 
       - name: The exported surface matches the specification
-        env:
-          OPENKAL_VERSION: 0.3.0
         run: |
-          # Clause 9.3. The list is fetched from the specification repository at
-          # the version this implementation is written against, so that the
-          # comparison has one source rather than a copy that can drift.
-          base="https://raw.githubusercontent.com/mcpplibs/openkal/$OPENKAL_VERSION"
-          curl -fsSL --retry 3 --retry-all-errors -o SURFACE.txt "$base/SURFACE.txt"
-          curl -fsSL --retry 3 --retry-all-errors -o check-surface.sh "$base/tools/check-surface.sh"
-          bash check-surface.sh --complete SURFACE.txt $(find target -name '*.o' | tr '\n' ' ')
+          # Clause 9.3. The list and the checker come from the specification
+          # itself rather than from a copy kept here, so that the comparison has
+          # one source. --complete because this implementation claims every
+          # interface: a name it fails to export is a failure, not an interface
+          # it declines to provide.
+          bash .spec/tools/check-surface.sh --complete .spec/SURFACE.txt \
+            $(find target -name '*.o' | tr '\n' ' ')
 
-      - name: The example runs
-        working-directory: examples/hello
+      # The program is taken from the specification rather than copied here. A
+      # copy in each implementation is a copy that can diverge, and the value of
+      # the program is precisely that every implementation runs the same one.
+      #
+      # The manifest is written here because naming the implementation is the
+      # manifest's job and not the program's, which is the arrangement the
+      # program exists to demonstrate.
+      - name: The portable program runs
         run: |
+          sed -i 's|^openkal = ".*"$|openkal = { path = ".spec" }|' mcpp.toml
+          cat > .spec/examples/portable/mcpp.toml <<'TOML'
+          [package]
+          name    = "portable"
+          version = "0.1.0"
+
+          [dependencies]
+          openkal = { path = "../.." }
+          openkal-macos = { path = "../../.." }
+          TOML
+          cd .spec/examples/portable
           mcpp run 2>&1 | tee run.log
-          grep -q 'openkal: hello' run.log
-          grep -q 'openkal: allocation succeeded' run.log
-          grep -q 'openkal: vectored writes unavailable' run.log
+          # Both directions: that the program reported, and that nothing it
+          # observed failed to hold. Asserting only the first would pass for a
+          # program that printed its failures.
+          grep -q 'openkal: the portable program, above eight interfaces' run.log
+          grep -q 'openkal: observations that did not hold: 0' run.log
+          ! grep -q 'NOT HELD' run.log

mcpp.toml

@@ -1,11 +1,11 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-macos"
-version     = "0.1.0"
+version     = "0.2.0"
 description = "An implementation of openkal for macOS. Its purpose is as much to test the specification as to be used: a specification satisfied only by the system it was written against has not been shown to be portable."
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-macos"
 
 [dependencies]
-openkal = "0.3.0"
+openkal = "0.4.0"

src/process.cpp

@@ -69,7 +69,10 @@ int kal_process_spawn(kal_dir base,
     if (!p.ok) return kal_err_invalid;
 
     vector args, envs;
-    args.add(p.buf, path_len);                       // the started program's own name
+    // The vector is passed unaltered. Clause 7.6: argv[0] is the name the
+    // started program observes as its own, and it is the caller's to choose —
+    // the started program reads it through kal_env_arg(0), so a caller that did
+    // not supply it could not predict what the program would read.
     for (kal_uintptr i = 0; i < argc; ++i) args.add(argv[i], argv_lens[i]);
     for (kal_uintptr i = 0; i < envc; ++i) envs.add(envp[i], envp_lens[i]);
     if (!args.ok || !envs.ok) return kal_err_no_memory;

tests/conformance_process_task.cpp

@@ -85,6 +85,39 @@ int main() {
             check(status != 0, "a non-zero status is reported as such");
             kal_process_close(q);
         }
+
+        // Clause 7.6: the vector is passed unaltered, and argv[0] is the name
+        // the started program observes as its own.
+        //
+        // The programs started above ignore their arguments, so they cannot
+        // distinguish an implementation that passes the vector from one that
+        // prepends the path — which is how that defect survived a suite that
+        // started programs and read their statuses. A shell does distinguish
+        // them: `sh -c <script>` takes $0 from its own argv[0] when no further
+        // argument is given, so the script observes the name the caller chose.
+        // An implementation that prepended the path would give the shell an
+        // extra argument, which it would read as a script file to open, and the
+        // status would be non-zero.
+        const char* sh_paths[] = { "bin/sh", "usr/bin/sh" };
+        const kal_uintptr sh_lens[] = { 6, 10 };
+        const char* script = "test \"$0\" = openkal-observed-argv0";
+        kal_uintptr script_len = 0; while (script[script_len]) ++script_len;
+
+        kal_process r{};
+        const char*       rargv[] = { "openkal-observed-argv0", "-c", script };
+        const kal_uintptr rlens[] = { 22, 2, script_len };
+        int rrc = kal_err_invalid;
+        for (int i = 0; i < 2 && rrc != kal_ok; ++i)
+            rrc = kal_process_spawn(slash, sh_paths[i], sh_lens[i], rargv, rlens, 3,
+                                    nullptr, nullptr, 0, nullptr, &r);
+        check(rrc == kal_ok, "a shell is started");
+        if (rrc == kal_ok) {
+            int status = -1, terminated = -1;
+            kal_process_wait(r, &status, &terminated);
+            check(status == 0 && terminated == 0,
+                  "the started program observes the argument vector the caller supplied, unaltered");
+            kal_process_close(r);
+        }
     }
 
     // A name that ascends is refused here as it is in the file system.