ranger-compiler 3.2.0 → 3.4.0

package/dist/lib/apple/AppleAppSpec.rgr

@@ -0,0 +1,201 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; AppleAppSpec.rgr -- the app, as everything but the code.
+; =============================================================================
+;
+; An .app bundle is a directory with an executable in it and a property list
+; that explains the executable to the system. Xcode builds that plist from a
+; project file, a target, a scheme and a build settings sheet; a command line
+; build has to say it in one place, and this is that place.
+;
+; The plist writer is here too, because the keys are not free-form: an iOS app
+; that omits `CFBundleExecutable` does not launch, one that omits
+; `UIDeviceFamily` is an iPhone app on an iPad, and one that omits
+; `UILaunchScreen` is letterboxed into a phone-sized box on every iPad no
+; matter what its families say. Those three are the ones a hand-built bundle
+; gets wrong, so they are written from the spec rather than left to a caller.
+; =============================================================================
+
+class AppleAppSpec {
+
+    ; The bundle and executable name. No spaces -- this is a file name.
+    def name:string "RangerApp"
+    ; What the home screen shows under the icon.
+    def displayName:string "Ranger App"
+    ; Reverse DNS, and the identity the simulator installs and launches by.
+    def bundleId:string "fi.ranger.app"
+    def version:string "1.0"
+    def build:string "1"
+
+    ; Every Swift file that goes into the executable, in no particular order.
+    ; For a Ranger app this is the generated .swift plus the host sources.
+    def sources:[string]
+    ; Files and directories copied into the bundle as they are. A stylesheet, a
+    ; font, an icon.
+    def resources:[string]
+    ; Anything extra for swiftc: -O, -warnings-as-errors, a framework path.
+    def swiftFlags:[string]
+    ; Frameworks to link that swiftc does not pull in on its own.
+    def frameworks:[string]
+
+    ; Extra Info.plist entries, as already-formatted XML fragments. The escape
+    ; hatch for a key this class does not know about.
+    def extraPlist:[string]
+
+    ; The .mobileprovision for a DEVICE build. Ignored for the simulator, which
+    ; needs no profile at all. When set, it is copied into the bundle as
+    ; `embedded.mobileprovision` and the entitlements it grants are read out of
+    ; it and handed to codesign.
+    def provisioningProfile:string ""
+
+    ; Portrait plus both landscapes, which is what a page that reflows wants.
+    ; An empty list leaves the key out and lets the system decide.
+    def orientations:[string]
+
+    Constructor () {
+        orientations = ([] _:string ( "UIInterfaceOrientationPortrait" "UIInterfaceOrientationLandscapeLeft" "UIInterfaceOrientationLandscapeRight" ))
+    }
+
+    fn addSource:void (path:string) {
+        push sources path
+    }
+
+    fn addResource:void (path:string) {
+        push resources path
+    }
+
+    fn addFramework:void (name:string) {
+        push frameworks name
+    }
+
+    ; The bundle directory name. `.app` is not decoration -- the simulator
+    ; installs a directory by that extension and nothing else.
+    fn bundleName:string () {
+        return (name + ".app")
+    }
+}
+
+; The property list, written out. XML rather than JSON or binary because it is
+; the format every Apple tool reads without conversion, and because a build that
+; goes wrong is one a person has to be able to read.
+class AppleInfoPlist {
+
+    ; Escape the five characters an XML text node cannot hold. A display name
+    ; with an ampersand in it is not exotic, and an unescaped one makes the
+    ; plist unparseable rather than wrong -- the app simply will not install.
+    sfn escape:string (s:string) {
+        def out:string s
+        out = (join (strsplit out "&") "&")
+        out = (join (strsplit out "<") "&lt;")
+        out = (join (strsplit out ">") "&gt;")
+        out = (join (strsplit out "\"") "&quot;")
+        return out
+    }
+
+    sfn stringKey:string (key:string value:string) {
+        return ("\t<key>" + (AppleInfoPlist.escape(key)) + "</key>\n\t<string>" + (AppleInfoPlist.escape(value)) + "</string>")
+    }
+
+    sfn boolKey:string (key:string value:boolean) {
+        def word:string "<false/>"
+        if value {
+            word = "<true/>"
+        }
+        return ("\t<key>" + (AppleInfoPlist.escape(key)) + "</key>\n\t" + word)
+    }
+
+    sfn intArrayKey:string (key:string values:[int]) {
+        def rows:[string]
+        push rows ("\t<key>" + (AppleInfoPlist.escape(key)) + "</key>")
+        push rows "\t<array>"
+        for values v:int i {
+            push rows ("\t\t<integer>" + v + "</integer>")
+        }
+        push rows "\t</array>"
+        return (join rows "\n")
+    }
+
+    sfn stringArrayKey:string (key:string values:[string]) {
+        def rows:[string]
+        push rows ("\t<key>" + (AppleInfoPlist.escape(key)) + "</key>")
+        push rows "\t<array>"
+        for values v:string i {
+            push rows ("\t\t<string>" + (AppleInfoPlist.escape(v)) + "</string>")
+        }
+        push rows "\t</array>"
+        return (join rows "\n")
+    }
+
+    ; The whole plist for one app on one target.
+    sfn build:string (spec:AppleAppSpec target:AppleTarget) {
+        def rows:[string]
+        push rows "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
+        push rows "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">"
+        push rows "<plist version=\"1.0\">"
+        push rows "<dict>"
+        push rows (AppleInfoPlist.stringKey("CFBundleDevelopmentRegion" "en"))
+        ; The one key with no default worth guessing: without it the system has
+        ; a directory and no idea which file in it to run.
+        push rows (AppleInfoPlist.stringKey("CFBundleExecutable" spec.name))
+        push rows (AppleInfoPlist.stringKey("CFBundleIdentifier" spec.bundleId))
+        push rows (AppleInfoPlist.stringKey("CFBundleInfoDictionaryVersion" "6.0"))
+        push rows (AppleInfoPlist.stringKey("CFBundleName" spec.name))
+        push rows (AppleInfoPlist.stringKey("CFBundleDisplayName" spec.displayName))
+        push rows (AppleInfoPlist.stringKey("CFBundlePackageType" "APPL"))
+        push rows (AppleInfoPlist.stringKey("CFBundleShortVersionString" spec.version))
+        push rows (AppleInfoPlist.stringKey("CFBundleVersion" spec.build))
+
+        def platformName:string "iPhoneOS"
+        if (target.isWatch()) {
+            platformName = "WatchOS"
+            if target.isSimulator {
+                platformName = "WatchSimulator"
+            }
+        } {
+            if target.isSimulator {
+                platformName = "iPhoneSimulator"
+            }
+        }
+        def platforms:[string]
+        push platforms platformName
+        push rows (AppleInfoPlist.stringArrayKey("CFBundleSupportedPlatforms" platforms))
+
+        if (target.isWatch()) {
+            ; A standalone watch app -- no paired iPhone app to be an appendage
+            ; of, which is what watchOS 6 and later allow and what makes a watch
+            ; build from the command line reasonable at all. WKApplication is
+            ; what watchOS 7 and later read, WKWatchOnly says there is no
+            ; companion, and WKRunsIndependentlyOfCompanionApp is what the
+            ; watchOS 6 generation read for the same thing. All three, because
+            ; which one is consulted depends on the OS and none of them costs
+            ; anything.
+            push rows (AppleInfoPlist.boolKey("WKApplication" true))
+            push rows (AppleInfoPlist.boolKey("WKWatchOnly" true))
+            push rows (AppleInfoPlist.boolKey("WKRunsIndependentlyOfCompanionApp" true))
+            push rows (AppleInfoPlist.stringKey("MinimumOSVersion" target.minVersion))
+        } {
+            push rows (AppleInfoPlist.stringKey("MinimumOSVersion" target.minVersion))
+            push rows (AppleInfoPlist.intArrayKey("UIDeviceFamily" target.families))
+            if ((array_length spec.orientations) > 0) {
+                push rows (AppleInfoPlist.stringArrayKey("UISupportedInterfaceOrientations" spec.orientations))
+                push rows (AppleInfoPlist.stringArrayKey("UISupportedInterfaceOrientations~ipad" spec.orientations))
+            }
+            ; An empty UILaunchScreen dictionary is the modern way to say "this
+            ; app has no launch storyboard and is still full screen". Leave it
+            ; out and iOS runs the app letterboxed in a phone-sized window on
+            ; every iPad, which looks exactly like a layout bug.
+            push rows "\t<key>UILaunchScreen</key>"
+            push rows "\t<dict/>"
+            push rows (AppleInfoPlist.boolKey("UIRequiresFullScreen" false))
+        }
+
+        for spec.extraPlist row:string i {
+            push rows row
+        }
+        push rows "</dict>"
+        push rows "</plist>"
+        push rows ""
+        return (join rows "\n")
+    }
+}

package/dist/lib/apple/AppleDevice.rgr

@@ -0,0 +1,295 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; AppleDevice.rgr -- the iPhones and iPads that are plugged in.
+; =============================================================================
+;
+; `xcrun devicectl list devices` prints a table. This reads it, and like the
+; simulator parser it is a PURE FUNCTION over the text: the one part of the
+; device story that has edge cases is therefore the one part that can be tested
+; on a machine with nothing plugged into it.
+;
+;     Devices:
+;     Name           Hostname              Identifier                             State       Model
+;     ─────────────  ────────────────────  ─────────────────────────────────────  ──────────  ─────
+;     Tero iPhone    00008101-...local     1A2B3C4D-5E6F-7890-ABCD-EF1234567890   connected   iPhone 14 Pro (iPhone15,2)
+;
+; The fields are found by splitting on runs of TWO OR MORE spaces rather than by
+; slicing at the separator line's column offsets. Column offsets look tidier and
+; are wrong: `strlen` counts UTF-16 units on some targets, runes on others and
+; BYTES on C++, so a device named "Terön iPhone" would slice at three different
+; places in three languages. Two spaces is two spaces everywhere.
+;
+; The IDENTIFIER is what `devicectl --device` wants, and it is not the 40-hex
+; UDID that older tools used -- it is a UUID that devicectl assigns. Finding it
+; by shape rather than by column position is also what makes this survive a
+; column being added, which Xcode has done before.
+; =============================================================================
+
+Import "AppleSimulator.rgr"
+
+class AppleDeviceInfo {
+
+    def name:string ""
+    ; What `devicectl --device` takes.
+    def identifier:string ""
+    ; "connected", "available (paired)", "unavailable"...
+    def state:string ""
+    def model:string ""
+
+    Constructor () {
+    }
+
+    ; "connected" means devicectl has a tunnel to the device AT THIS MOMENT.
+    fn isConnected:boolean () {
+        return ((indexOf state "connected") >= 0)
+    }
+
+    ; "available (paired)" is a device devicectl knows and has no tunnel to
+    ; right now. It is NOT an absent device: the tunnel is raised on demand by
+    ; the first real operation -- `devicectl device info apps` on a phone in
+    ; this state prints "Acquired tunnel connection to device" and then answers
+    ; -- so an install onto it works. Refusing it here is the difference
+    ; between a build that runs and one that stops on a cable that is plugged
+    ; in.
+    ;
+    ; "unavailable" CONTAINS "available", so the negative is tested first; the
+    ; substring test that reads right is the one that is wrong.
+    fn isPaired:boolean () {
+        if ((indexOf state "unavailable") >= 0) {
+            return false
+        }
+        return ((indexOf state "available") >= 0)
+    }
+
+    ; A device worth handing to devicectl: one with a tunnel, or one that can
+    ; raise one.
+    fn isUsable:boolean () {
+        if (this.isConnected()) {
+            return true
+        }
+        return (this.isPaired())
+    }
+
+    fn describe:string () {
+        return (name + " (" + model + ") " + identifier + " -- " + state)
+    }
+}
+
+class AppleDeviceList {
+
+    ; Split a table row on runs of two or more spaces, dropping empty pieces.
+    sfn columns:[string] (line:string) {
+        def out:[string]
+        def n:int (strlen line)
+        def cur:string ""
+        def spaces:int 0
+        def i:int 0
+        while (i < n) {
+            def ch:string (substring line i (i + 1))
+            if (ch == " ") {
+                spaces = spaces + 1
+            } {
+                ; One space is inside a field; two ends it.
+                if (spaces >= 2) {
+                    if ((strlen (trim cur)) > 0) {
+                        push out (trim cur)
+                    }
+                    cur = ""
+                } {
+                    if (spaces == 1) {
+                        cur = (cur + " ")
+                    }
+                }
+                spaces = 0
+                cur = (cur + ch)
+            }
+            i = i + 1
+        }
+        if ((strlen (trim cur)) > 0) {
+            push out (trim cur)
+        }
+        return out
+    }
+
+    sfn parse:[AppleDeviceInfo] (text:string) {
+        def found:[AppleDeviceInfo]
+        def lines:[string] (strsplit text "\n")
+        for lines rawLine:string li {
+            def cols:[string] (AppleDeviceList.columns(rawLine))
+            def cnt:int (array_length cols)
+            if (cnt >= 3) {
+                ; The identifier is found by SHAPE, so a new column before or
+                ; after it changes nothing. The header row and the separator
+                ; row hold no UUID and fall out here.
+                def at:int (0 - 1)
+                def ci:int 0
+                while (ci < cnt) {
+                    if (at < 0) {
+                        if (AppleSimulatorList.looksLikeUdid((itemAt cols ci))) {
+                            at = ci
+                        }
+                    }
+                    ci = ci + 1
+                }
+                if (at > 0) {
+                    def dev:AppleDeviceInfo (new AppleDeviceInfo)
+                    dev.name = (itemAt cols 0)
+                    dev.identifier = (itemAt cols at)
+                    if ((at + 1) < cnt) {
+                        dev.state = (itemAt cols (at + 1))
+                    }
+                    def rest:[string]
+                    def mi:int (at + 2)
+                    while (mi < cnt) {
+                        push rest (itemAt cols mi)
+                        mi = mi + 1
+                    }
+                    dev.model = (join rest " ")
+                    push found dev
+                }
+            }
+        }
+        return found
+    }
+
+    ; The device to install onto. `nameWanted` is a substring of the name, or
+    ; the identifier itself; "" takes the first usable one, which is the whole
+    ; point of a one-command device build.
+    ;
+    ; A CONNECTED device wins over a merely paired one when both match, because
+    ; the connected one needs no tunnel raised and is therefore faster and
+    ; surer. A paired one is still returned when it is all there is.
+    sfn pick@(optional):AppleDeviceInfo (devices:[AppleDeviceInfo] nameWanted:string) {
+        def wanted:string (trim nameWanted)
+        def best@(optional):AppleDeviceInfo
+        def fallback@(optional):AppleDeviceInfo
+        for devices d:AppleDeviceInfo i {
+            if (d.isUsable()) {
+                def matches:boolean false
+                if ((strlen wanted) == 0) {
+                    matches = true
+                } {
+                    if ((indexOf d.name wanted) >= 0) {
+                        matches = true
+                    }
+                    if (d.identifier == wanted) {
+                        matches = true
+                    }
+                }
+                if matches {
+                    if (d.isConnected()) {
+                        if (null? best) {
+                            best = d
+                        }
+                    } {
+                        if (null? fallback) {
+                            fallback = d
+                        }
+                    }
+                }
+            }
+        }
+        if (!null? best) {
+            return best
+        }
+        return fallback
+    }
+}
+
+; =============================================================================
+; What `xcrun devicectl device info details --device ID` says about one device.
+; =============================================================================
+;
+; The listing that `list devices` prints has one word for the whole story --
+; "connected", "available (paired)" -- and that word is not enough to tell a
+; device that cannot be used from one that merely has no tunnel open. `info
+; details` has the fields that actually decide it:
+;
+;     ▿ deviceProperties:
+;         • ddiServicesAvailable: false
+;         • developerModeStatus: enabled
+;         • osVersionNumber: 26.3
+;     ▿ connectionProperties:
+;         • pairingState: paired
+;         • tunnelState: unavailable
+;
+; `developerModeStatus` is the one a person has to fix on the phone itself, and
+; `ddiServicesAvailable` is the one that fixes itself the moment anything asks
+; for a developer service. Telling them apart is the difference between "go
+; enable a setting" and "wait four seconds".
+;
+; Parsed as a PURE FUNCTION over the text, like the listing above it: the
+; bullets are decoration, so a value is read as whatever follows "key:" on the
+; line that has it. A field Apple adds, moves or re-indents changes nothing.
+; =============================================================================
+
+class AppleDeviceDetails {
+
+    ; "enabled", "disabled", ""
+    def developerMode:string ""
+    ; The developer disk image is mounted and its services can be called.
+    def ddiAvailable:boolean false
+    ; "connected", "disconnected", "unavailable"
+    def tunnelState:string ""
+    def pairingState:string ""
+    def osVersion:string ""
+    def marketingName:string ""
+    def udid:string ""
+
+    Constructor () {
+    }
+
+    fn developerModeEnabled:boolean () {
+        return (developerMode == "enabled")
+    }
+
+    ; The text after "key:" on the first line that mentions it, trimmed. "" when
+    ; no line does -- which is also the answer for a device that reported the
+    ; field empty, and both mean the same thing to every caller here.
+    ;
+    ; The line is SPLIT on ":" rather than sliced at the offset `indexOf` gives
+    ; for the key. The lines have "•" and "▿" in them, and an offset into a
+    ; string with multi-byte characters before it is counted in runes on some
+    ; targets and in BYTES on others -- so the slice that is right on Node is
+    ; off by two per bullet on Go. Splitting asks no arithmetic and is the same
+    ; answer everywhere. `AppleDeviceList.columns` avoids the same trap for the
+    ; same reason.
+    sfn valueFor:string (text:string key:string) {
+        def lines:[string] (strsplit text "\n")
+        def found:string ""
+        def seen:boolean false
+        for lines raw:string i {
+            if (seen == false) {
+                def parts:[string] (strsplit raw ":")
+                def cnt:int (array_length parts)
+                if (cnt >= 2) {
+                    if ((indexOf (itemAt parts 0) key) >= 0) {
+                        seen = true
+                        ; A value with a ":" in it -- a time, a URL -- keeps it.
+                        def rest:[string]
+                        def pi:int 1
+                        while (pi < cnt) {
+                            push rest (itemAt parts pi)
+                            pi = pi + 1
+                        }
+                        found = (trim (join rest ":"))
+                    }
+                }
+            }
+        }
+        return found
+    }
+
+    sfn parse:AppleDeviceDetails (text:string) {
+        def d:AppleDeviceDetails (new AppleDeviceDetails)
+        d.developerMode = (AppleDeviceDetails.valueFor(text "developerModeStatus"))
+        d.tunnelState = (AppleDeviceDetails.valueFor(text "tunnelState"))
+        d.pairingState = (AppleDeviceDetails.valueFor(text "pairingState"))
+        d.osVersion = (AppleDeviceDetails.valueFor(text "osVersionNumber"))
+        d.marketingName = (AppleDeviceDetails.valueFor(text "marketingName"))
+        d.udid = (AppleDeviceDetails.valueFor(text "udid"))
+        d.ddiAvailable = ((AppleDeviceDetails.valueFor(text "ddiServicesAvailable")) == "true")
+        return d
+    }
+}