Add comments

.cargo/config.toml

@@ -18,6 +18,8 @@ rustflags = [
 ]
 
 [target.aarch64-apple-darwin]
+# The purpose of lzld is to reduce startup time on Mac
+# by lazy loading frameworks. See tools/lzld/README.md
 linker = "tools/lzld/lzld"
 rustflags = [
   "-C",

tools/lzld/README.md

@@ -1,4 +1,40 @@
-A `ld -lazy_framework` for macOS. Designed to build Deno.
+# `lzld`
+
+This tools implements an alternative of the (deprecated) `ld -lazy_framework` to lazy load frameworks as needed. Symbols used are manually
+added to `lzld.m`.
+
+The purpose of this ld wrapper is to improve startup time on Mac. Because Deno includes WebGPU, it needs to link to Metal and QuartzCore.
+We've observed that loading frameworks during startup can cost as much as 8ms of startup time.
+
+## Adding a new symbol binding
+
+Add a binding for the used symbol in `lzld.m`, eg:
+
+```diff
+void *(*MTLCopyAllDevices_)(void) = 0;
++void *(*MTLSomethingSomething_)(void) = 0;
+
+void loadMetalFramework() {
+    void *handle = dlopen("/System/Library/Frameworks/Metal.framework/Metal", RTLD_LAZY);
+    if (handle) {
+        MTLCopyAllDevices_ = dlsym(handle, "MTLCopyAllDevices");
++       MTLSomethingSomething_ = dlsym(handle, "MTLSomethingSomething");
+    }
+}
+
+
++extern void *MTLSomethingSomething(void) {
++   if (MTLSomethingSomething_ == 0) {
++       loadMetalFramework();
++   }
++
++   return MTLSomethingSomething_();
++}
+
+extern void *MTLCopyAllDevices(void) {
+```
+
+then build the static library with `make liblzld_arm64.a`.
 
 ## Usage
 
@@ -28,9 +64,3 @@ framework via `dlopen` when needed.
 
 Rest of the arguments are passed as-is to `lld`.
 
-<!--
-Supported frameworks:
-- QuartzCore
-- CoreFoundation
-- TODO
--->

tools/lzld/lzld

@@ -1,4 +1,10 @@
 #!/bin/bash
+#
+# This script is a wrapper around the `lld` linker that adds the path to the
+# `liblzld` static library to the linker search path and links against it.
+#
+# Additionally, this script strips out `-framework` arguments
+
 arch=$(uname -m)
 
 # Find the path to the `lld` binary.

tools/lzld/lzld.m

@@ -1,3 +1,15 @@
+/*
+    lzld - lazy loading of OSX frmeworks
+
+    This is compiled as a static library and linked against the binary via `lzld` script.
+    This code dynamically load frameworks when symbol is called using dlopen and dlsym.
+
+    Dependencies:
+    - dlfcn.h: Header file providing functions for dynamic linking.
+    - QuartzCore.framework: Provides graphics rendering support. (WebGPU)
+    - Metal.framework: Framework for high-performance GPU-accelerated graphics and computing. (WebGPU)
+*/
+
 #import <dlfcn.h>
 
 // -- QuartzCore.framework