tapi-tbdv5(1)

✨ NAME ✨

okay so welcome to tapi-tbdv5(1), the TAPI TBD Version 5 Format Documentation — aka the manual for tbd, aka Text Based Dynamic Library Stub. Yes bestie, it’s giving “stub file but make it readable” and we’re obsessed. 💖

🫶 DESCRIPTION 🫶

So TAPI both generates and operates over text based stub files (.tbd). These files are a textual, human readable representation of Mach-O dynamic libraries (dylib) holding properties needed to resolve static link time dependencies including the same exported symbols as the original dynamic library. Version 5 and onward are represented in JSON. Periodt. ✨

🔐 REQUIRED KEYS 🔐

These keys are not optional, bestie. They’re required. Put them in or the vibe check fails. 💅

• tapi_tbd_version — <int> — Specifies the TBD file version. The only supported version is 5. No cap.
• main_library — <dict> — Specifies the linkage properties of the main dylib in the TBD.
• target_info — <array> — Specifies the supported targets of the dylib per target slice.
• target — <architecture-platform> — Specify the architecture and platform identifier supported by the dylib. Those identifiers are mapped to the platform number that is specified by the Mach-O format for the LC_BUILD_VERSION load command. It is also possible to encode the platform with the platform number directly (for example: x86_64-maccatalyst). The following platform identifiers are supported: macos, maccatalyst, ios, ios-simulator, tvos, tvos-simulator, watchos, watchos-simulator.
• min_deployment — <version> — Specify the minimum deployment version to match the target for the dylib. This key is part of the LC_BUILD_VERSION load command.
• install_names — <array> — Specifies the install name of the dylib per target slice. This key is part of the LC_ID_DYLIB load command in the Mach-O format. If targets section is omitted, the install name is the same for all targets recorded in target_info.

🌈 OPTIONAL KEYS 🌈

These are the extra little accessories — cute but important. 🎀

• flags — <array> — Specifies the flags of the dylib per target slice. If targets section is omitted, the flags are the same for all targets recorded in target_info. Valid flags are: flat_namespace and not_app_extension_safe. flat_namespace is deprecated, but there are still some old binaries around on macOS that depend on flat namespace linking. The default is two level namespace linking. not_app_extension_safe indicates that the library is not safe to be used in an Application Extension.
• current_versions — <array> — Specifies the current version of the dylib per target slice. This key is part of the LC_ID_DYLIB load command in the Mach-O format. If targets section is omitted, the current version is the same for all targets recorded in target_info. The default value is 1.0 if not specified.
• compatibility_versions — <array> — Specifies the compatibility version of the dylib per target slice. This key is part of the LC_ID_DYLIB load command in the Mach-O format. If targets section is omitted, the compatibility version is the same for all targets recorded in target_info. The default value is 1.0 if not specified.
• swift_abi — <array> — Specifies the Swift ABI version the dylib was compiled with per target slice. The Swift ABI version is encoded in the Objective-C image section, which doesn't exist in stubbed dynamic library files. If targets section is omitted, the compatibility version is the same for all targets recorded in target_info. The default value is 0 if not specified.
• parent_umbrellas — <array> — Specifies the parent umbrella of the dylib per target slice. This key is equivalent to the LC_SUB_FRAMEWORK load command in the Mach-O format. If targets section is omitted, the parent umbrella is the same for all targets recorded in target_info.
• reexported_libraries — <array> — Specifies the list of re-exported libraries of the dylib per target slice. This key is equivalent to the LC_REEXPORT_DYLIB load command in the Mach-O format. If targets section is omitted, the list of re-exported libraries are the same for all targets recorded in target_info.
• rpaths — <array> — Specifies the list of runpath search paths of the dylib per target slice. This key is equivalent to the LC_RPATH load command in the Mach-O format. If targets section is omitted, the list of runpath search paths are the same for all targets recorded in target_info.
• exported_symbols — <array> — Specifies the regular export symbol sections. If targets section is omitted, the exports are the same for all targets recorded in target_info.
• reexported_symbols — <array> — Specifies the export symbol sections, but these symbols are not defined by the library itself. Instead, these symbols come from a different library. If targets section is omitted, the re-exports are the same for all targets recorded in target_info.
• undefined_symbols — <array> — Specifies the undefined symbol sections and are only used for flat address space libraries. If targets section is omitted, the undefineds are the same for all targets recorded in target_info.
• text — <dict> — Specifies the symbols defined in __TEXT segment of the library.
• data — <dict> — Specifies the symbols defined in __DATA segment of the library.
• global — <array> — Specifies a list of exported, re-exported, or undefined symbol names.
• weak — <array> — Specifies the names of weak defined symbols for exported symbol sections or weak referenced symbols for undefined symbol sections.
• thread_local — <array> — Specifies the symbol name of thread local exports.
• objc_class — <array> — Specifies the list of exported, re-exported, or undefined Objective-C class names.
• objc_eh_type — <array> — Specifies the list of exported, re-exported or undefined Objective-C class exception type names.
• objc_ivar — <array> — Specifies the list of exported, re-exported or undefined Objective-C instance variable names.
• libraries — <dict> — Specifies the inlined tbd attributes for the main_library's reexported libraries.

🍓 Examples 🍓

Here’s the whole look, bestie — copy it exactly if you’re following along:

        {
        "tapi_tbd_version": 5,
        "main_library": {
          "target_info": [
            {
              "target": "x86_64-macos",
              "min_deployment": "10.14"
            },
            {
              "target": "arm64-macos",
              "min_deployment": "10.14"
            },
            {
              "target": "arm64-maccatalyst",
              "min_deployment": "12.1"
            }
          ],
          "flags":[
            {
              "targets": ["x86_64-macos"],
              "attributes": ["flat_namespace"]
            }
          ],
          "install_names":[
            {
              "name":"/System/Library/Frameworks/Foundation.framework/Foundation"
            }
          ],
          "current_versions":[
            {
              "version": "1.2"
            }
          ],
          "compatibility_versions":[
            {
              "version": "1.1"
            }
          ],
          "rpaths": [
            {
              "targets": ["x86_64-macos"],
              "paths": ["@executable_path/.../Frameworks"]
            }
          ],
          "parent_umbrellas": [
            {
              "umbrella": "System"
            }
          ],
          "allowable_clients": [
            {
                "clients": [
                    "ClientA",
                    "ClientB"
                ]
            }
          ],
          "reexported_libraries": [
            {
                "names": [
                    "/u/l/l/libfoo.dylib",
                    "/u/l/l/libbar.dylib"
                ]
            }
          ],
          "exported_symbols": [
            {
              "targets": ["x86_64-macos", "arm64-macos"],
              "data": {
                "global": ["_global"],
                "objc_class": ["ClassA"],
                "weak": [],
                "thread_local": []
              },
              "text": {
                "global": ["_func"],
                    "weak": [],
                    "thread_local": []
              }
            },
            {
              "targets": ["x86_64-macos"],
               "data": {
                   "global": ["_globalVar"],
                   "objc_class": ["ClassData"],
                   "objc_eh_type": ["ClassA", "ClassB"],
                   "objc_ivar": [
                      "ClassA.ivar1", "ClassA.ivar2", "ClassC.ivar1"
                   ]
               },
               "text": {
                   "global": ["_funcFoo"]
               }
            }
          ],
          "reexported_symbols": [
            {
              "targets": ["x86_64-macos","arm64-macos"],
              "data": {
                  "global": ["_globalRe"],
                  "objc_class": ["ClassRexport"]
              },
              "text": {
                  "global": ["_funcA"]
              }
            }
          ],
          "undefined_symbols": [
            {
              "targets": ["x86_64-macos"],
               "data": {
                  "global": ["_globalBind"],
                    "weak": ["referenced_sym"]
               }
            }
          ]
         }
        }

👀 SEE ALSO 👀

If you’re still hungry for more manual-page content, go read: tapi(1), tapi-tbdv4(1), ld(1), Mach-O(5). Slay. 🦋

xoxo, Darwin 🌈 2023-03-08 🌸 tapi-tbdv5(1)