Installing on macOS

Version 1.0.0-beta for macOS is the archive oxl-1.0.0-beta-macos-arm64.tar.xz on the release page (next to it lies the checksum file oxl-1.0.0-beta-macos-arm64.tar.xz.sha256). It has the same layout as the Linux archive (see installing from the archive), minus what is Linux-specific.

What is inside (the same checks are made by scripts/test_release.sh on the archive): bin/oxl and bin/oxl-docs, the bundled libLLVM.dylib and libclang.dylib with the clang resource headers for import c (lib/oxl/lib, lib/oxl/clang), the standard library, liboxlrt.a and the static libraries it needs (OpenSSL, nghttp2, SQLite, PCRE2, libpq in lib/oxl/runtime/lib, named relatively in lib/oxl/runtime/link.flags), the documentation site, the VS Code extension and the licenses; the PDFs are separate release files. All four Mach-O files are arm64, built for macOS 14.0, signed ad hoc, and depend only on each other and on system libraries (/usr/lib, /System). Programs built with oxl build depend on libSystem/libc++ only.

Requirements#

A Mac with an Apple chip (arm64), macOS 14 or newer (the release is built for MACOSX_DEPLOYMENT_TARGET=14.0).
Xcode Command Line Tools: xcode-select --install (linker, SDK, dsymutil, codesign, lldb-dap). Neither full Xcode nor Homebrew is needed.

Installation#

xcode-select --install                             # once; if the tools are already there the command says so

mkdir -p ~/Downloads/oxl-dl && cd ~/Downloads/oxl-dl
curl -LO https://github.com/DesCaldnd/OxwaldLink/releases/download/v1.0.0-beta/oxl-1.0.0-beta-macos-arm64.tar.xz
curl -LO https://github.com/DesCaldnd/OxwaldLink/releases/download/v1.0.0-beta/oxl-1.0.0-beta-macos-arm64.tar.xz.sha256
shasum -a 256 -c oxl-1.0.0-beta-macos-arm64.tar.xz.sha256       # oxl-1.0.0-beta-macos-arm64.tar.xz: OK

mkdir -p ~/opt && tar -C ~/opt -xJf oxl-1.0.0-beta-macos-arm64.tar.xz          # no sudo needed
xattr -dr com.apple.quarantine ~/opt/oxl-1.0.0-beta                            # why: see below

echo 'export PATH="$HOME/opt/oxl-1.0.0-beta/bin:$PATH"' >> ~/.zprofile         # zsh is the default shell
export PATH="$HOME/opt/oxl-1.0.0-beta/bin:$PATH"                               # for the current window
oxl --version

The installation may live elsewhere (for example /usr/local/oxl-1.0.0-beta with sudo): oxl finds the standard library and the runtime next to itself. For bash use ~/.bash_profile instead of ~/.zprofile.

Why `xattr`: ad hoc signing and notarization#

The executables and libraries of the archive are signed ad hoc (codesign -s -): the signature makes arm64 code runnable at all but is not tied to a developer account. The archive is not notarized by Apple. A file downloaded by a browser gets the attribute com.apple.quarantine, and Gatekeeper refuses to run non-notarized programs ("cannot verify the developer", "is damaged"). xattr -dr com.apple.quarantine <directory> removes the mark from the whole unpacked tree; check the checksum (shasum) first, to be sure the archive is the one published in the release. An archive fetched with curl usually gets no mark, and the command is harmless then. If the archive came from a browser, the mark is on the archive and tar copies it to every unpacked file: either run xattr -d com.apple.quarantine oxl-1.0.0-beta-macos-arm64.tar.xz before unpacking, or xattr -dr on the tree as above. Do this before the first start of oxl: a quarantined start is blocked by Gatekeeper (a dialog, or the command just waits), and files that were blocked once may stay blocked after the mark is removed: unpack the archive again in that case. Programs built by oxl build are signed on your machine (ad hoc) and are not quarantined. If you skipped xattr, you can allow the run in "System Settings → Privacy & Security", but every file (oxl, libLLVM.dylib, …) has to be confirmed separately, so removing the mark once is simpler.

Check and first program#

oxl --version                                      # oxl 1.0.0-beta (edition 2027, …)
mkdir -p ~/oxl-smoke && cd ~/oxl-smoke
oxl doctor                                         # checks the whole environment, see below
oxl new hello && cd hello && oxl run               # Hello, world!
oxl build -o hello-bin && ls -d hello-bin hello-bin.dSYM

oxl build puts <name>.dSYM with the debug info (for lldb) beside the program; more checks: checking the installation. The first start of a freshly built program may take a few seconds (the system scans a new ad hoc signed file), later starts take milliseconds (D-8688). If something does not work, run oxl doctor. On macOS it checks the Command Line Tools (xcode-select -p), dsymutil, the com.apple.quarantine mark on the installed files (a fail line with the xattr -dr com.apple.quarantine <directory> command; a copy that macOS already blocked once must be extracted again, see above), the signature of oxl (codesign --verify), the Developer Tools permission and the limits (ulimit -n, the length of TMPDIR), and builds and runs a hello world (checking the installation). If oxl build prints linking failed or xcrun: error, the Command Line Tools are missing. What differs on this platform (kqueue, durability OXL_FULLFSYNC, --static, --image): platforms.

Durability of writes (for nodes with data)#

fsync on macOS does not flush the drive's cache, so by default (as with SQLite and PostgreSQL on macOS) an acknowledged write of the storage and the Raft log survives a crash of the program and a reboot of macOS but can be lost on a sudden power loss. If the data must survive it, start the program with OXL_FULLFSYNC=1 (export OXL_FULLFSYNC=1): writes then go through F_FULLFSYNC, about 4 ms per flush on the internal SSD (parallel writes are grouped). For development and tests keep the default. More: platforms, appendix D of the Standard (impl-fsync).

Debugging#

oxl dap, oxl debug and oxl test --debug work through lldb-dap. It comes with the Xcode Command Line Tools or with Homebrew llvm (brew install llvm; the version need not be 18). oxl looks for the adapter in PATH, then in the Command Line Tools, Xcode and Homebrew locations; an explicit path is OXL_LLDB_DAP=/opt/homebrew/opt/llvm/bin/lldb-dap or oxl dap --lldb-dap <path>. Keep the program and its .dSYM together (lldb finds the debug info by UUID). All-stop and remote debugging of a node (oxl debug attach, --all-stop) attach lldb-dap to the node's process through Apple's debugserver.

No administrator rights are needed for processes of the same user (what oxl build produces). On the first attach macOS may ask for permission ("Developer Tools Access needs to take control of another process"): confirm it with your password; sudo DevToolsSecurity -enable does the same once. You also have to be in the _developer group (administrators are). If the debugger says it cannot attach to the process, check this and that the program was built by oxl build (ad hoc, no hardened runtime). Editor setup: debugging from the editor.

Updating and uninstalling#

Every version lives in its own oxl-<version> directory: unpack the new one beside it and switch PATH. To uninstall:

rm -rf ~/opt/oxl-1.0.0-beta                        # the installation itself
# remove the export PATH=... line from ~/.zprofile
code --uninstall-extension oxwaldlink.oxl-lang     # if you installed the VS Code extension
rm -rf ~/.cache/oxl                                # optional: the build and package cache ($OXL_HOME if set)