tools-island: the fixture reaches the boundary through a seam module

Every example under `examples/09-heterogeneous` puts a module of the
project between the consumer and the island: `app.cppm` imports the
boundary and turns pointers and a count back into spans, and it is the one
place a backend can be exchanged. The fixture reached the generated module
from `src/main.cpp`, which is not a module unit -- so its import said
nothing about the case the examples are in, where one module interface
written by the project imports a module interface written into the build
directory during the same build.

`src/app.cppm` is that seam, and `src/main.cpp` now names no boundary
symbol at all. Both properties are asserted: a consumer that named
`saxpy_device` would mean the seam is not hiding which island is
underneath.

Both legs build and run with it.

Author: Sunrisepeak

.github/workflows/ci.yml

@@ -243,10 +243,21 @@ jobs:
           # island reads the generated header through the compiler's
           # forced-include flag -- so a project using this generator has no
           # header in its source tree and no line naming one.
-          if grep -rn '#include' src/main.cpp src/kernels/saxpy.c src/cpu/saxpy.c; then
+          if grep -rn '#include' src/main.cpp src/app.cppm src/kernels/saxpy.c src/cpu/saxpy.c; then
             echo "FAIL: a source names an include; the generator exists to remove it"
             exit 1
           fi
+          # THE SEAM IS A MODULE OF THIS PROJECT IMPORTING THE GENERATED ONE.
+          # `main.cpp` is not a module unit, so its import said nothing about
+          # ordering two module interfaces where one is written during the
+          # build. `src/app.cppm` is, and it is the shape every example under
+          # examples/09-heterogeneous has.
+          grep -q '^import island_interface.kernels;' src/app.cppm \
+            || { echo "FAIL: the seam no longer imports the generated module"; exit 1; }
+          if grep -q 'saxpy_device\|scale_device' src/main.cpp; then
+            echo "FAIL: the consumer names a boundary symbol; the seam exists to hide it"
+            exit 1
+          fi
           # AND THE CHECK THAT INCLUDE USED TO DO IS STILL THERE. The compiler
           # sees the declarations, so a definition whose signature drifted from
           # the generated header fails where it was written rather than at the

README.md

@@ -297,6 +297,13 @@ Two files come out of that one marked declaration: the `extern "C"` header the
 device translation unit includes, guards and `__cplusplus` dance included, and
 the module the C++ side imports.
 
+The C++ side is usually a **seam module** of the project rather than a consumer
+directly: `app.cppm` imports the generated module and turns pointers and a count
+back into spans, and it is the one place a backend can be exchanged. That means
+one module interface of the project imports a module interface written into the
+build directory during the same build; the ordering comes from the scan seeing
+the import, and nothing has to be declared for it.
+
 **Three layers, and each overrides the one above.** `scan` reads the marked
 declarations out of the island, which puts the signature beside the definition;
 `emit` takes a list directly, for entry points a scan cannot see; and a project

tests/island-interface/mcpp.toml

@@ -39,7 +39,7 @@ plugins = { path = "../..", features = ["tools-island"], host-module = true }
 # disk in either build, and the manifest decides which one is compiled.
 [build]
 accel   = "vulkan1.2"
-sources = ["src/*.cpp"]
+sources = ["src/*.cppm", "src/*.cpp"]
 
 [target.'cfg(accelerator = "vulkan")'.build]
 sources = ["src/kernels/*.c"]

tests/island-interface/src/app.cppm

@@ -0,0 +1,35 @@
+// The seam: a module of this project that imports the GENERATED module.
+//
+// This is the shape every example under `examples/09-heterogeneous` has, and it
+// is the one the fixture was missing. `src/main.cpp` is not a module unit, so
+// its `import` said nothing about the case that matters here -- a module
+// interface written by this project importing a module interface written into
+// the build directory during the same build. The two have to be ordered, and
+// the ordering comes from the scan seeing the import rather than from anything
+// this file declares.
+//
+// It is also where the boundary stops being C. Above this line callers pass
+// spans; below it, pointers and a count, which is the one shape every device
+// API agrees on.
+export module island_interface.app;
+
+import std;
+import island_interface.kernels;
+
+export namespace island_interface {
+
+std::optional<std::vector<float>>
+saxpy(float a, std::span<const float> x, std::span<const float> y) {
+    if (x.size() != y.size()) return std::nullopt;
+    std::vector<float> out(x.size());
+    if (saxpy_device(a, x.data(), y.data(), out.data(),
+                     static_cast<unsigned>(x.size())) != 0)
+        return std::nullopt;
+    return out;
+}
+
+bool scale(float a, std::span<float> v) {
+    return scale_device(a, v.data(), static_cast<unsigned>(v.size())) == 0;
+}
+
+} // namespace island_interface

tests/island-interface/src/main.cpp

@@ -1,28 +1,34 @@
-// The C++ side. It imports the generated module and includes nothing: the
-// header exists for the island's compiler, which does not read modules.
+// The consumer. It imports the SEAM, not the generated module, and includes
+// nothing: the generated header exists for the island's compiler, which does
+// not read modules.
+//
+// Nothing here names `saxpy_device`. That is the property the seam exists for:
+// which island is underneath -- the device half or the host one -- is not
+// visible from this file, and neither is the fact that a boundary was
+// generated at all.
 import std;
-import island_interface.kernels;
+import island_interface.app;
 
 int main() {
-    float x[4] = {1, 2, 3, 4};
-    float y[4] = {10, 20, 30, 40};
-    float out[4] = {};
+    const std::vector<float> x{1, 2, 3, 4};
+    const std::vector<float> y{10, 20, 30, 40};
 
-    if (saxpy_device(2.0f, x, y, out, 4) != 0) {
-        std::cout << "BAD: saxpy_device failed\n";
+    auto out = island_interface::saxpy(2.0f, x, y);
+    if (!out) {
+        std::cout << "BAD: saxpy failed\n";
         return 1;
     }
-    if (scale_device(0.5f, out, 4) != 0) {
-        std::cout << "BAD: scale_device failed\n";
+    if (!island_interface::scale(0.5f, *out)) {
+        std::cout << "BAD: scale failed\n";
         return 1;
     }
 
     // (2*1+10)/2, (2*2+20)/2, (2*3+30)/2, (2*4+40)/2
     const float want[4] = {6, 12, 18, 24};
-    bool ok = true;
-    for (int i = 0; i < 4; ++i) {
-        std::cout << std::format("out[{}]={} ", i, out[i]);
-        if (out[i] != want[i]) ok = false;
+    bool ok = out->size() == 4;
+    for (std::size_t i = 0; ok && i < out->size(); ++i) {
+        std::cout << std::format("out[{}]={} ", i, (*out)[i]);
+        if ((*out)[i] != want[i]) ok = false;
     }
     std::cout << "\n";
     // Two entry points rather than one, because a generator that re-exported