update README

README.md

@@ -3,7 +3,7 @@
 # Bazel zig cc toolchain
 
 This is a C/C++ toolchain that can (cross-)compile C/C++ programs. It contains
-clang-13, musl, glibc (versions 2-2.33, selectable), all in a ~40MB package.
+clang-13, musl, glibc (versions 2-2.34, selectable), all in a ~40MB package.
 Read
 [here](https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html)
 about zig-cc; the rest of the README will present how to use this toolchain
@@ -54,13 +54,46 @@ used, run:
 $ bazel query @zig_sdk//... | sed -En '/.*_toolchain$/ s/.*:(.*)_toolchain$/\1/p'
 ```
 
-## Compiling OS X executables
+# Known Issues in bazel-zig-cc
 
-MacOS SDK (`--sysroot`) may be necessary. Read [Jakub's comment][sysroot] about
-it. This section will be expanded once yours truly understands more about the
-requirements and limitations of linking on OSX.
+These are the things you may stumble into when using bazel-zig-cc. I am
+unlikely to implement them, but patches implementing those will be accepted.
+See [Questions & Contributions](#questions-amp-contributions) on how to
+contribute.
 
-# Known Issues
+## OSX: sysroot
+
+MacOS SDK (`--sysroot`) may be necessary for non-trivial programs (and is
+required for all cgo darwin/arm64 ones). Read [Jakub's comment][sysroot] about
+it. Support for OSX sysroot is currently not implemented.
+
+## OSX: different OS targets (Catalina -- Monterey)
+
+Since [zig 0.9.0](https://ziglang.org/download/0.9.0/release-notes.html#macOS)
+zig may target macos.10 (Catalina), macos.11 (Big Sur) or macos.12 (Monterey).
+It currently targets the lowest version.
+
+## Zig cache
+
+Currently zig cache is in `$HOME` so `bazel clean --expunge` does not clear the
+zig cache. Zig's cache should be stored somewhere in the project's path.
+
+## Alternative download URLs
+
+Currently zig is downloaded from [dl.jakstys.lt](https://dl.jakstys.lt/zig/),
+which is nuts. One should provide a way to specify alternative URLs for the zig
+toolchain.
+
+## Bazel toolchain target locations
+
+The path to Bazel toolchains is `@zig_sdk//:<toolchain>_toolchain`. It should
+be moved to `@zig_sdk//toolchain:<toolchain>` or similar; so the user-facing
+targets are in their own namespace.
+
+# Known Issues in upstream
+
+This section lists issues that I've stumbled into when using `zig cc`, and
+is outside of control bazel-zig-cc's control.
 
 ## using glibc 2.27 or older
 
@@ -72,7 +105,7 @@ Background: when glibc 2.27 or older is selected, it may miss `fcntl64`. A
 workaround is applied for `x86_64`, but not for aarch64. The same workaround
 may apply to aarch64, but the author didn't find a need to test it (yet).
 
-# Closed issues
+# Closed upstream issues
 
 - [ziglang/zig misplaced relocated glibc stubs (pthread_sigmask) #7667](https://github.com/ziglang/zig/issues/7667) (CLOSED, thanks mjonaitis and andrewrk)
 - [ziglang/zig macho: fail if requested -framework is not found #10312](https://github.com/ziglang/zig/pull/10312) (CLOSED, thanks kubkon)
@@ -134,15 +167,6 @@ how CI does it.
 This section lists things that I think will happen at some point: either by
 myself, or my colleagues, or outside contributors.
 
-* Move Zig cache path to bazel root, so `bazel clean --expunge` clears the zig
-  cache.
-* Provide a way to specify alternative URLs for the zig toolchain (currently
-  zig is downloaded from jakstys.lt, which is nuts).
-* Rename `@zig_sdk//:<toolchain>_toolchain` to
-  `@zig_sdk//toolchain:<toolchain>` or similar; so the user-facing targets are
-  in their own namespace.
-* Provide a way to specify sysroot for Darwin (OSX). See [#Compiling OS X
-  executables](#compiling-os-x-executables) for an ongoing discussion.
 
 # Questions & Contributions