Tell macOS users to declare macOS 14 in pixi

src/components/home/QuickStart.astro

@@ -47,6 +47,11 @@ const commands = [
       ))}
     </div>
   </div>
+  <p class="note">
+    On macOS,{" "}
+    <a href="/GettingStarted.html#setup-a-workspace">declare macOS 14</a> after
+    <code>pixi init</code> to get the current builds.
+  </p>
 </div>
 
 <script src="../../scripts/copy-buttons.ts"></script>
@@ -112,6 +117,10 @@ const commands = [
     background: rgba(112, 192, 56, 0.18);
     color: #9fe06a;
   }
+  .note {
+    margin: 12px 0 0;
+    font-size: 13px;
+  }
   .term-body {
     padding: 16px;
     font-size: 13px;

src/content/docs/FAQ.md

@@ -110,6 +110,32 @@ linux = "5.15"
 
 Note: Set the glibc version to match the oldest machine or robot that needs to run your project, not necessarily your personal machine. You can check a machine's version by running `ldd --version`.
 
+## Why does pixi install older ROS packages on macOS?
+
+The current RoboStack builds need macOS 14 or newer.
+Pixi doesn't look at the macOS version of your machine: unless the workspace declares one, it solves for macOS 13.
+The solver then skips the newest builds and picks an older generation, without any error.
+
+You can spot this with `pixi list distro-mutex`.
+If the version is lower than the "Built against" mutex on the distro's package page, for example [Lyrical](/lyrical.html), you're on older builds.
+
+Declare macOS 14 for the workspace:
+
+```shell
+pixi workspace platform add osx-latest=osx-arm64 --osx 14
+pixi workspace platform rm osx-arm64
+```
+
+On an Intel Mac, replace `osx-arm64` with `osx-64` in both commands.
+Pixi updates the lockfile and the environment right away.
+
+You can also write it in the `pixi.toml` yourself and run `pixi install`:
+
+```toml
+[workspace]
+platforms = [{ name = "osx-latest", platform = "osx-arm64", macos = "14" }]
+```
+
 ## Why ROS and Conda?
 
 We tightly couple ROS with Conda, a cross-platform, language-agnostic package manager.

src/content/docs/GettingStarted.mdx

@@ -50,6 +50,32 @@ pixi init ros_ws --channel https://prefix.dev/robostack-lyrical
 cd ros_ws
 ```
 
+On macOS, also tell pixi to use macOS 14:
+
+```shell
+pixi workspace platform add osx-latest=osx-arm64 --osx 14
+pixi workspace platform rm osx-arm64
+```
+
+On an Intel Mac, replace `osx-arm64` with `osx-64` in both commands.
+Run them in this order: pixi won't remove the only platform of a workspace.
+
+<details>
+<summary>Why is this needed on macOS?</summary>
+
+The current RoboStack builds need macOS 14 or newer.
+Pixi doesn't look at the macOS version of your machine, it assumes macOS 13 unless the workspace says otherwise.
+Without this step it quietly installs an older generation of the ROS packages.
+
+The first command adds your platform again with macOS 14 declared, the second removes the default one.
+Your `pixi.toml` then has:
+
+```toml
+platforms = [{ name = "osx-latest", platform = "osx-arm64", macos = "14" }]
+```
+
+</details>
+
 <details>
 <summary>What did just happen?</summary>
 
@@ -163,7 +189,14 @@ You can replace the previous `pixi.toml` or use `pixi init` to create a new work
 name = "ros_ws"
 description = "Development environment for RoboStack ROS packages"
 channels = ["https://prefix.dev/conda-forge"]
-platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"]
+# RoboStack's macOS builds need macOS 14, pixi assumes 13 unless told otherwise
+platforms = [
+  "linux-64",
+  "linux-aarch64",
+  "win-64",
+  { name = "osx-64-latest", platform = "osx-64", macos = "14" },
+  { name = "osx-arm64-latest", platform = "osx-arm64", macos = "14" },
+]
 
 # This will automatically activate the ros workspace on activation
 [target.win.activation]