I have developed an app that I had been testing on the hardware device with the developer profile signed builds, I had setup a CloudKit container in development mode and also had tested with Production mode and they are working as expected. I have also tested storekit auto renewal subscriptions using Storekit Config file and all of that is working on the hardware device with the developer profile signed builds. Now comes the Fun Part, I want to use the Distribution profile to test the app for production readiness, I had created a distribution profile and had set that up in the Release under target of the app in Xcode, I have also created sandbox tester account (which is showing inactive even after 7 days - though I am also logged in with this sandbox tester account on a hardware device and under developer setting it shows as a sandbox tester account) All the subscriptions are showing Ready to Submit in the App Store Connect. I need help understand this whole flow, how to ensure I can test CloudKit and storekit for production readiness and then publish my app for the review. Thank you.

Dear Apple Community, I am facing quite a hard issue in my React Native app that I do not know how to overcome. I have an app, that connects to "ANY" Mautic.org instance - You can think of it as Wordpress for marketing automation. And as each WordPress instance has it's own URL, the same goes for the Mautic. So at the beginning I am asking user for a URL that my app si supposed to be connected: //previous code <TextInput value={instanceLink} onChangeText={(text) => setInstanceLink(text.trim().toLowerCase())} placeholder="Please insert instance link" style={styles.input} /> //Code continues The instance link value is stored in Expo Secure Store and used through the whole app. This works perfectly fine during development. The app saves this instance link and calls API without any issues: //previous code export const testConnection = async ( url: string ): Promise<{ status: boolean; message: string; fullResponseLog: Response | undefined; }> => { try { const response: Response = await fetch(url); // Code Continues However, when build for production and used in TestFlight or Google Play - I am getting "network request failed" (for Fetch) or "Network Error" (for Axios). It seems this "dynamic url" is blocked somehow by App Stores policy and I could not find a solution for this problem. Any ideas? Are such dynamic links actually blocked by some policy?

Hi, I really appreciate the C++ binding provided. I got the metal-cpp source code from the website at Getting Started. However, I could not find the same for metal-cpp-extensions. Is it not available or do we have to always extract it from the sample code? Thanks.

Hi, We have few MacStudio servers that when we ssh as users to it and trying to run some commands fro /usr/bin, they staying in hang state for infinite. When root user do the same commands are working properly Example for hanging commands : clang, gcc, make, ld etc Add as attachment the dtruss out for ld -v command to help debug it Thanks, Amir dtruss out from ld -v command

I am trying to integrate Apple Music API using MusicKit and need to generate a Developer Token. However, when I try to create a new key from the Certificates, Identifiers &amp; Profiles section, the “Media Services (MusicKit, ShazamKit, Apple Music Feed)” option is grayed out. We are getting the error 'there are no identifiers available that can be associated with the key.' Although we did checkmark 'musickit' in app services. I have already: Enrolled in the paid Apple Developer Program Created a valid App ID under Identifiers Logged in as the Account Holder Tried multiple browsers and devices Despite this, the option remains disabled. Could you please enable this or let me know what further steps I need to take? Thank you!

Recently a bunch of folks have asked about why a specific symbol is being referenced by their app. This is my attempt to address that question. If you have questions or comments, please start a new thread. Tag it with Linker so that I see it. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Determining Why a Symbol is Referenced In some situations you might want to know why a symbol is referenced by your app. For example: You might be working with a security auditing tool that flags uses of malloc. You might be creating a privacy manifest and want to track down where your app is calling stat. This post is my attempt at explaining a general process for tracking down the origin of these symbol references. This process works from ‘below’. That is, it works ‘up’ from you app’s binary rather than ‘down’ from your app’s source code. That’s important because: It might be hard to track down all of your source code, especially if you’re using one or more package management systems. If your app has a binary dependency on a static library, dynamic library, or framework, you might not have access to that library’s source code. IMPORTANT This post assumes the terminology from An Apple Library Primer. Read that before continuing here. The general outline of this process is: Find all Mach-O images. Find the Mach-O image that references the symbol. Find the object files (.o) used to make that Mach-O. Find the object file that references the symbol. Find the code within that object file. Those last few steps require some gnarly low-level Mach-O knowledge. If you’re looking for an easier path, try using the approach described in the A higher-level alternative section as a replacement for steps 3 through 5. This post assumes that you’re using Xcode. If you’re using third-party tools that are based on Apple tools, and specifically Apple’s linker, you should be able to adapt this process to your tooling. If you’re using a third-party tool that has its own linker, you’ll need to ask for help via your tool’s support channel. Find all Mach-O images On Apple platforms an app consists of a number of Mach-O images. Every app has a main executable. The app may also embed dynamic libraries or frameworks. The app may also embed app extensions or system extensions, each of which have their own executable. And a Mac app might have embedded bundles, helper tools, XPC services, agents, daemons, and so on. To find all the Mach-O images in your app, combine the find and file tools. For example: % find "Apple Configurator.app" -print0 | xargs -0 file | grep Mach-O Apple Configurator.app/Contents/MacOS/Apple Configurator: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64] … Apple Configurator.app/Contents/MacOS/cfgutil: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64:Mach-O 64-bit executable arm64] … Apple Configurator.app/Contents/Extensions/ConfiguratorIntents.appex/Contents/MacOS/ConfiguratorIntents: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64:Mach-O 64-bit executable arm64] … Apple Configurator.app/Contents/Frameworks/ConfigurationUtilityKit.framework/Versions/A/ConfigurationUtilityKit: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit dynamically linked shared library x86_64] [arm64] … This shows that Apple Configurator has a main executable (Apple Configurator), a helper tool (cfgutil), an app extension (ConfiguratorIntents), a framework (ConfigurationUtilityKit), and many more. This output is quite unwieldy. For nicer output, create and use a shell script like this: % cat FindMachO.sh #! /bin/sh # Passing `-0` to `find` causes it to emit a NUL delimited after the # file name and the `:`. Sadly, macOS `cut` doesn’t support a nul # delimiter so we use `tr` to convert that to a DLE (0x01) and `cut` on # that. # # Weirdly, `find` only inserts the NUL on the primary line, not the # per-architecture Mach-O lines. We use that to our advantage, filtering # out the per-architecture noise by only passing through lines # containing a DLE. find "$@" -type f -print0 \ | xargs -0 file -0 \ | grep -a Mach-O \ | tr '\0' '\1' \ | grep -a $(printf '\1') \ | cut -d $(printf '\1') -f 1 Find the Mach-O image that references the symbol Once you have a list of Mach-O images, use nm to find the one that references the symbol. The rest of this post investigate a test app, WaffleVarnishORama, that’s written in Swift but uses waffle management functionality from the libWaffleCore.a static library. The goal is to find the code that calls calloc. This app has a single Mach-O image: % FindMachO.sh "WaffleVarnishORama.app" WaffleVarnishORama.app/WaffleVarnishORama Use nm to confirm that it references calloc: % nm "WaffleVarnishORama.app/WaffleVarnishORama" | grep "calloc" U _calloc The _calloc symbol has a leading underscore because it’s a C symbol. This convention dates from the dawn of Unix, where the underscore distinguish C symbols from assembly language symbols. The U prefix indicates that the symbol is undefined, that is, the Mach-O images is importing the symbol. If the symbol name is prefixed by a hex number and some other character, like T or t, that means that the library includes an implementation of calloc. That’s weird, but certainly possible. OTOH, if you see this then you know this Mach-O image isn’t importing calloc. IMPORTANT If this Mach-O isn’t something that you build — that is, you get this Mach-O image as a binary from another developer — you won’t be able to follow the rest of this process. Instead, ask for help via that library’s support channel. Find the object files used to make that Mach-O image The next step is to track down which .o file includes the reference to calloc. Do this by generating a link map. A link map is an old school linker feature that records the location, size, and origin of every symbol added to the linker’s output. To generate a link map, enable the Write Link Map File build setting. By default this puts the link map into a text (.txt) file within the derived data directory. To find the exact path, look at the Link step in the build log. If you want to customise this, use the Path to Link Map File build setting. A link map has three parts: A simple header A list of object files used to build the Mach-O image A list of sections and their symbols In our case the link map looks like this: # Path: …/WaffleVarnishORama.app/WaffleVarnishORama # Arch: arm64 # Object files: [ 0] linker synthesized [ 1] objc-file [ 2] …/AppDelegate.o [ 3] …/MainViewController.o [ 4] …/libWaffleCore.a[2](WaffleCore.o) [ 5] …/Foundation.framework/Foundation.tbd … # Sections: # Address Size Segment Section 0x100008000 0x00001AB8 __TEXT __text … The list of object files contains: An object file for each of our app’s source files — That’s AppDelegate.o and MainViewController.o in this example. A list of static libraries — Here that’s just libWaffleCore.a. A list of dynamic libraries — These might be stub libraries (.tbd), dynamic libraries (.dylib), or frameworks (.framework). Focus on the object files and static libraries. The list of dynamic libraries is irrelevant because each of those is its own Mach-O image. Find the object file that references the symbol Once you have list of object files and static libraries, use nm to each one for the calloc symbol: % nm "…/AppDelegate.o" | grep calloc % nm "…/MainViewController.o" | grep calloc % nm "…/libWaffleCore.a" | grep calloc U _calloc This indicates that only libWaffleCore.a references the calloc symbol, so let’s focus on that. Note As in the Mach-O case, the U prefix indicates that the symbol is undefined, that is, the object file is importing the symbol. Find the code within that object file To find the code within the object file that references the symbol, use the objdump tool. That tool takes an object file as input, but in this example we have a static library. That’s an archive containing one or more object files. So, the first step is to unpack that archive: % mkdir "libWaffleCore-objects" % cd "libWaffleCore-objects" % ar -x "…/libWaffleCore.a" % ls -lh total 24 -rw-r--r-- 1 quinn staff 4.1K 8 May 11:24 WaffleCore.o -rw-r--r-- 1 quinn staff 56B 8 May 11:24 __.SYMDEF SORTED There’s only a single object file in that library, which makes things easy. If there were a multiple, run the following process over each one independently. To find the code that references a symbol, run objdump with the -S and -r options: % xcrun objdump -S -r "WaffleCore.o" … ; extern WaffleRef newWaffle(void) { 0: d10083ff sub sp, sp, #32 4: a9017bfd stp x29, x30, [sp, #16] 8: 910043fd add x29, sp, #16 c: d2800020 mov x0, #1 10: d2800081 mov x1, #4 ; Waffle * result = calloc(1, sizeof(Waffle)); 14: 94000000 bl 0x14 <ltmp0+0x14> 0000000000000014: ARM64_RELOC_BRANCH26 _calloc … Note the ARM64_RELOC_BRANCH26 line. This tells you that the instruction before that — the bl at offset 0x14 — references the _calloc symbol. IMPORTANT The ARM64_RELOC_BRANCH26 relocation is specific to the bl instruction in 64-bit Arm code. You’ll see other relocations for other instructions. And the Intel architecture has a whole different set of relocations. So, when searching this output don’t look for ARM64_RELOC_BRANCH26 specifically, but rather any relocation that references _calloc. In this case we’ve built the object file from source code, so WaffleCore.o contains debug symbols. That allows objdump include information about the source code context. From that, we can easily see that calloc is referenced by our newWaffle function. To see what happens when you don’t have debug symbols, create an new object file with them stripped out: % cp "WaffleCore.o" "WaffleCore-stripped.o" % strip -x -S "WaffleCore-stripped.o" Then repeat the objdump command: % xcrun objdump -S -r "WaffleCore-stripped.o" … 0000000000000000 <_newWaffle>: 0: d10083ff sub sp, sp, #32 4: a9017bfd stp x29, x30, [sp, #16] 8: 910043fd add x29, sp, #16 c: d2800020 mov x0, #1 10: d2800081 mov x1, #4 14: 94000000 bl 0x14 <_newWaffle+0x14> 0000000000000014: ARM64_RELOC_BRANCH26 _calloc … While this isn’t as nice as the previous output, you can still see that newWaffle is calling calloc. A higher-level alternative Grovelling through Mach-O object files is quite tricky. Fortunately there’s an easier approach: Use the -why_live option to ask the linker why it included a reference to the symbol. To continue the above example, I set the Other Linker Flags build setting to -Xlinker / -why_live / -Xlinker / _calloc and this is what I saw in the build transcript: _calloc from /usr/lib/system/libsystem_malloc.dylib _newWaffle from …/libWaffleCore.a[2](WaffleCore.o) _$s18WaffleVarnishORama18MainViewControllerC05tableE0_14didSelectRowAtySo07UITableE0C_10Foundation9IndexPathVtFTf4dnn_n from …/MainViewController.o _$s18WaffleVarnishORama18MainViewControllerC05tableE0_14didSelectRowAtySo07UITableE0C_10Foundation9IndexPathVtF from …/MainViewController.o Demangling reveals a call chain like this: calloc newWaffle WaffleVarnishORama.MainViewController.tableView(_:didSelectRowAt:) WaffleVarnishORama.MainViewController.tableView(_:didSelectRowAt:) and that should be enough to kick start your investigation. IMPORTANT The -why_live option only works if you dead strip your Mach-O image. This is the default for the Release build configuration, so use that for this test. Revision History 2025-07-18 Added the A higher-level alternative section. 2024-05-08 First posted.

export VALIDATE_DEVELOPMENT_ASSET_PATHS=YES_ERROR export VALIDATE_PRODUCT=NO export VALID_ARCHS=arm64\ arm64e\ i386\ x86_64 export VERBOSE_PBXCP=NO export VERSION_INFO_BUILDER=always export VERSION_INFO_FILE=React-Codegen_vers.c export VERSION_INFO_STRING="@(#)PROGRAM:React-Codegen\ \ PROJECT:Pods-" export WORKSPACE_DIR=/Users/always/Downloads/Qacademy-Developing-UI-3\ 4/ios export WRAP_ASSET_PACKS_IN_SEPARATE_DIRECTORIES=NO export XCODE_APP_SUPPORT_DIR=/Applications/Xcode.app/Contents/Developer/Library/Xcode export XCODE_PRODUCT_BUILD_VERSION=16A242d export XCODE_VERSION_ACTUAL=1600 export XCODE_VERSION_MAJOR=1600 export XCODE_VERSION_MINOR=1600 export XPCSERVICES_FOLDER_PATH=/XPCServices export YACC=yacc export arch=undefined_arch export variant=normal /bin/sh -c /Users/always/Library/Developer/Xcode/DerivedData/Qacademy-ahrekaakdnrtqnfurmiuebfpbjdn/Build/Intermediates.noindex/Pods.build/Debug-iphonesimulator/React-Codegen.build/Script-46EB2E00016FC0.sh /bin/sh: /Users/always/Downloads/Qacademy-Developing-UI-3: is a directory Command PhaseScriptExecution failed with a nonzero exit code warning: Run script build phase 'Bundle React Native code and images' will be run during every build because it does not specify any outputs. To address this issue, either add output dependencies to the script phase, or configure it to run in every build by unchecking "Based on dependency analysis" in the script phase. (in target 'Qacademy' from project 'Qacademy') warning: Run script build phase '[CP-User] [Hermes] Replace Hermes for the right configuration, if needed' will be run during every build because it does not specify any outputs. To address this issue, either add output dependencies to the script phase, or configure it to run in every build by unchecking "Based on dependency analysis" in the script phase. (in target 'hermes-engine' from project 'Pods') --- xcodebuild: WARNING: Using the first of multiple matching destinations: { platform:iOS Simulator, id:F3B25D76-2816-4DA9-B63D-DAA28C7C48A0, OS:18.0, name:iPhone 16 Pro Max } { platform:iOS Simulator, id:F3B25D76-2816-4DA9-B63D-DAA28C7C48A0, OS:18.0, name:iPhone 16 Pro Max } ** BUILD FAILED ** The following build commands failed: PhaseScriptExecution [CP-User]\ Generate\ Specs /Users/always/Library/Developer/Xcode/DerivedData/Qacademy-ahrekaakdnrtqnfurmiuebfpbjdn/Build/Intermediates.noindex/Pods.build/Debug-iphonesimulator/React-Codegen.build/Script-46EB2E00016FC0.sh (in target 'React-Codegen' from project 'Pods') Building workspace Qacademy with scheme Qacademy and configuration Debug (2 failures)

Apple’s library technology has a long and glorious history, dating all the way back to the origins of Unix. This does, however, mean that it can be a bit confusing to newcomers. This is my attempt to clarify some terminology. If you have any questions or comments about this, start a new thread and tag it with Linker so that I see it. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" An Apple Library Primer Apple’s tools support two related concepts: Platform — This is the platform itself; macOS, iOS, iOS Simulator, and Mac Catalyst are all platforms. Architecture — This is a specific CPU architecture used by a platform. arm64 and x86_64 are both architectures. A given architecture might be used by multiple platforms. The most obvious example of this arm64, which is used by all of the platforms listed above. Code built for one platform will not work on another platform, even if both platforms use the same architecture. Code is usually packaged in either a Mach-O file or a static library. Mach-O is used for executables (MH_EXECUTE), dynamic libraries (MH_DYLIB), bundles (MH_BUNDLE), and object files (MH_OBJECT). These can have a variety of different extensions; the only constant is that .o is always used for a Mach-O containing an object file. Use otool and nm to examine a Mach-O file. Use vtool to quickly determine the platform for which it was built. Use size to get a summary of its size. Use dyld_info to get more details about a dynamic library. IMPORTANT All the tools mentioned here are documented in man pages. For information on how to access that documentation, see Reading UNIX Manual Pages. There’s also a Mach-O man page, with basic information about the file format. Many of these tools have old and new variants, using the -classic suffix or llvm- prefix, respectively. For example, there’s nm-classic and llvm-nm. If you run the original name for the tool, you’ll get either the old or new variant depending on the version of the currently selected tools. To explicitly request the old or new variants, use xcrun. The term Mach-O image refers to a Mach-O that can be loaded and executed without further processing. That includes executables, dynamic libraries, and bundles, but not object files. A dynamic library has the extension .dylib. You may also see this called a shared library. A framework is a bundle structure with the .framework extension that has both compile-time and run-time roles: At compile time, the framework combines the library’s headers and its stub library (stub libraries are explained below). At run time, the framework combines the library’s code, as a Mach-O dynamic library, and its associated resources. The exact structure of a framework varies by platform. For the details, see Placing Content in a Bundle. macOS supports both frameworks and standalone dynamic libraries. Other Apple platforms support frameworks but not standalone dynamic libraries. Historically these two roles were combined, that is, the framework included the headers, the dynamic library, and its resources. These days Apple ships different frameworks for each role. That is, the macOS SDK includes the compile-time framework and macOS itself includes the run-time one. Most third-party frameworks continue to combine these roles. A static library is an archive of one or more object files. It has the extension .a. Use ar, libtool, and ranlib to inspect and manipulate these archives. The static linker, or just the linker, runs at build time. It combines various inputs into a single output. Typically these inputs are object files, static libraries, dynamic libraries, and various configuration items. The output is most commonly a Mach-O image, although it’s also possible to output an object file. The linker may also output metadata, such as a link map (see Using a Link Map to Track Down a Symbol’s Origin). The linker has seen three major implementations: ld — This dates from the dawn of Mac OS X. ld64 — This was a rewrite started in the 2005 timeframe. Eventually it replaced ld completely. If you type ld, you get ld64. ld_prime — This was introduced with Xcode 15. This isn’t a separate tool. Rather, ld now supports the -ld_classic and -ld_new options to select a specific implementation. Note During the Xcode 15 beta cycle these options were -ld64 and -ld_prime. I continue to use those names because the definition of new changes over time (some of us still think of ld64 as the new linker ;–). The dynamic linker loads Mach-O images at runtime. Its path is /usr/lib/dyld, so it’s often referred to as dyld, dyld, or DYLD. Personally I pronounced that dee-lid, but some folks say di-lid and others say dee-why-el-dee. IMPORTANT Third-party executables must use the standard dynamic linker. Other Unix-y platforms support the notion of a statically linked executable, one that makes system calls directly. This is not supported on Apple platforms. Apple platforms provide binary compatibility via system dynamic libraries and frameworks, not at the system call level. Note Apple platforms have vestigial support for custom dynamic linkers (your executable tells the system which dynamic linker to use via the LC_LOAD_DYLINKER load command). This facility originated on macOS’s ancestor platform and has never been a supported option on any Apple platform. The dynamic linker has seen 4 major revisions. See WWDC 2017 Session 413 (referenced below) for a discussion of versions 1 through 3. Version 4 is basically a merging of versions 2 and 3. The dyld man page is chock-full of useful info, including a discussion of how it finds images at runtime. Every dynamic library has an install name, which is how the dynamic linker identifies the library. Historically that was the path where you installed the library. That’s still true for most system libraries, but nowadays a third-party library should use an rpath-relative install name. For more about this, see Dynamic Library Identification. Mach-O images are position independent, that is, they can be loaded at any location within the process’s address space. Historically, Mach-O supported the concept of position-dependent images, ones that could only be loaded at a specific address. While it may still be possible to create such an image, it’s no longer a good life choice. Mach-O images have a default load address, also known as the base address. For modern position-independent images this is 0 for library images and 4 GiB for executables (leaving the bottom 32 bits of the process’s address space unmapped). When the dynamic linker loads an image, it chooses an address for the image and then rebases the image to that address. If you take that address and subtract the image’s load address, you get a value known as the slide. Xcode 15 introduced the concept of a mergeable library. This a dynamic library with extra metadata that allows the linker to embed it into the output Mach-O image, much like a static library. Mergeable libraries have many benefits. For all the backstory, see WWDC 2023 Session 10268 Meet mergeable libraries. For instructions on how to set this up, see Configuring your project to use mergeable libraries. If you put a mergeable library into a framework structure you get a mergeable framework. Xcode 15 also introduced the concept of a static framework. This is a framework structure where the framework’s dynamic library is replaced by a static library. Note It’s not clear to me whether this offers any benefit over creating a mergeable framework. Earlier versions of Xcode did not have proper static framework support. That didn’t stop folks trying to use them, which caused all sorts of weird build problems. A universal binary is a file that contains multiple architectures for the same platform. Universal binaries always use the universal binary format. Use the file command to learn what architectures are within a universal binary. Use the lipo command to manipulate universal binaries. A universal binary’s architectures are either all in Mach-O format or all in the static library archive format. The latter is called a universal static library. A universal binary has the same extension as its non-universal equivalent. That means a .a file might be a static library or a universal static library. Most tools work on a single architecture within a universal binary. They default to the architecture of the current machine. To override this, pass the architecture in using a command-line option, typically -arch or --arch. An XCFramework is a single document package that includes libraries for any combination of platforms and architectures. It has the extension .xcframework. An XCFramework holds either a framework, a dynamic library, or a static library. All the elements must be the same type. Use xcodebuild to create an XCFramework. For specific instructions, see Xcode Help > Distribute binary frameworks > Create an XCFramework. Historically there was no need to code sign libraries in SDKs. If you shipped an SDK to another developer, they were responsible for re-signing all the code as part of their distribution process. Xcode 15 changes this. You should sign your SDK so that a developer using it can verify this dependency. For more details, see WWDC 2023 Session 10061 Verify app dependencies with digital signatures and Verifying the origin of your XCFrameworks. A stub library is a compact description of the contents of a dynamic library. It has the extension .tbd, which stands for text-based description (TBD). Apple’s SDKs include stub libraries to minimise their size; for the backstory, read this post. Use the tapi tool to create and manipulate stub libraries. In this context TAPI stands for a text-based API, an alternative name for TBD. Oh, and on the subject of tapi, I’d be remiss if I didn’t mention tapi-analyze! Stub libraries currently use YAML format, a fact that’s relevant when you try to interpret linker errors. If you’re curious about the format, read the tapi-tbdv4 man page. There’s also a JSON variant documented in the tapi-tbdv5 man page. Note Back in the day stub libraries used to be Mach-O files with all the code removed (MH_DYLIB_STUB). This format has long been deprecated in favour of TBD. Historically, the system maintained a dynamic linker shared cache, built at runtime from its working set of dynamic libraries. In macOS 11 and later this cache is included in the OS itself. Libraries in the cache are no longer present in their original locations on disk: % ls -lh /usr/lib/libSystem.B.dylib ls: /usr/lib/libSystem.B.dylib: No such file or directory Apple APIs, most notably dlopen, understand this and do the right thing if you supply the path of a library that moved into the cache. That’s true for some, but not all, command-line tools, for example: % dyld_info -exports /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B.dylib [arm64e]: -exports: offset symbol … 0x5B827FE8 _mach_init_routine % nm /usr/lib/libSystem.B.dylib …/nm: error: /usr/lib/libSystem.B.dylib: No such file or directory When the linker creates a Mach-O image, it adds a bunch of helpful information to that image, including: The target platform The deployment target, that is, the minimum supported version of that platform Information about the tools used to build the image, most notably, the SDK version A build UUID For more information about the build UUID, see TN3178 Checking for and resolving build UUID problems. To dump the other information, run vtool. In some cases the OS uses the SDK version of the main executable to determine whether to enable new behaviour or retain old behaviour for compatibility purposes. You might see this referred to as compiled against SDK X. I typically refer to this as a linked-on-or-later check. Apple tools support the concept of autolinking. When your code uses a symbol from a module, the compiler inserts a reference (using the LC_LINKER_OPTION load command) to that module into the resulting object file (.o). When you link with that object file, the linker adds the referenced module to the list of modules that it searches when resolving symbols. Autolinking is obviously helpful but it can also cause problems, especially with cross-platform code. For information on how to enable and disable it, see the Build settings reference. Mach-O uses a two-level namespace. When a Mach-O image imports a symbol, it references the symbol name and the library where it expects to find that symbol. This improves both performance and reliability but it precludes certain techniques that might work on other platforms. For example, you can’t define a function called printf and expect it to ‘see’ calls from other dynamic libraries because those libraries import the version of printf from libSystem. To help folks who rely on techniques like this, macOS supports a flat namespace compatibility mode. This has numerous sharp edges — for an example, see the posts on this thread — and it’s best to avoid it where you can. If you’re enabling the flat namespace as part of a developer tool, search the ’net for dyld interpose to learn about an alternative technique. WARNING Dynamic linker interposing is not documented as API. While it’s a useful technique for developer tools, do not use it in products you ship to end users. Apple platforms use DWARF. When you compile a file, the compiler puts the debug info into the resulting object file. When you link a set of object files into a executable, dynamic library, or bundle for distribution, the linker does not include this debug info. Rather, debug info is stored in a separate debug symbols document package. This has the extension .dSYM and is created using dsymutil. Use symbols to learn about the symbols in a file. Use dwarfdump to get detailed information about DWARF debug info. Use atos to map an address to its corresponding symbol name. Different languages use different name mangling schemes: C, and all later languages, add a leading underscore (_) to distinguish their symbols from assembly language symbols. C++ uses a complex name mangling scheme. Use the c++filt tool to undo this mangling. Likewise, for Swift. Use swift demangle to undo this mangling. For a bunch more info about symbols in Mach-O, see Understanding Mach-O Symbols. This includes a discussion of weak references and weak definition. If your code is referencing a symbol unexpectedly, see Determining Why a Symbol is Referenced. To remove symbols from a Mach-O file, run strip. To hide symbols, run nmedit. It’s common for linkers to divide an object file into sections. You might find data in the data section and code in the text section (text is an old Unix term for code). Mach-O uses segments and sections. For example, there is a text segment (__TEXT) and within that various sections for code (__TEXT > __text), constant C strings (__TEXT > __cstring), and so on. Over the years there have been some really good talks about linking and libraries at WWDC, including: WWDC 2023 Session 10268 Meet mergeable libraries WWDC 2022 Session 110362 Link fast: Improve build and launch times WWDC 2022 Session 110370 Debug Swift debugging with LLDB WWDC 2021 Session 10211 Symbolication: Beyond the basics WWDC 2019 Session 416 Binary Frameworks in Swift — Despite the name, this covers XCFrameworks in depth. WWDC 2018 Session 415 Behind the Scenes of the Xcode Build Process WWDC 2017 Session 413 App Startup Time: Past, Present, and Future WWDC 2016 Session 406 Optimizing App Startup Time Note The older talks are no longer available from Apple, but you may be able to find transcripts out there on the ’net. Historically Apple published a document, Mac OS X ABI Mach-O File Format Reference, or some variant thereof, that acted as the definitive reference to the Mach-O file format. This document is no longer available from Apple. If you’re doing serious work with Mach-O, I recommend that you find an old copy. It’s definitely out of date, but there’s no better place to get a high-level introduction to the concepts. The Mach-O Wikipedia page has a link to an archived version of the document. For the most up-to-date information about Mach-O, see the declarations and doc comments in <mach-o/loader.h>. Revision History 2025-08-04 Added a link to Determining Why a Symbol is Referenced. 2025-06-29 Added information about autolinking. 2025-05-21 Added a note about the legacy Mach-O stub library format (MH_DYLIB_STUB). 2025-04-30 Added a specific reference to the man pages for the TBD format. 2025-03-01 Added a link to Understanding Mach-O Symbols. Added a link to TN3178 Checking for and resolving build UUID problems. Added a summary of the information available via vtool. Discussed linked-on-or-later checks. Explained how Mach-O uses segments and sections. Explained the old (-classic) and new (llvm-) tool variants. Referenced the Mach-O man page. Added basic info about the strip and nmedit tools. 2025-02-17 Expanded the discussion of dynamic library identification. 2024-10-07 Added some basic information about the dynamic linker shared cache. 2024-07-26 Clarified the description of the expected load address for Mach-O images. 2024-07-23 Added a discussion of position-independent images and the image slide. 2024-05-08 Added links to the demangling tools. 2024-04-30 Clarified the requirement to use the standard dynamic linker. 2024-03-02 Updated the discussion of static frameworks to account for Xcode 15 changes. Removed the link to WWDC 2018 Session 415 because it no longer works )-: 2024-03-01 Added the WWDC 2023 session to the list of sessions to make it easier to find. Added a reference to Using a Link Map to Track Down a Symbol’s Origin. Made other minor editorial changes. 2023-09-20 Added a link to Dynamic Library Identification. Updated the names for the static linker implementations (-ld_prime is no more!). Removed the beta epithet from Xcode 15. 2023-06-13 Defined the term Mach-O image. Added sections for both the static and dynamic linkers. Described the two big new features in Xcode 15: mergeable libraries and dependency verification. 2023-06-01 Add a reference to tapi-analyze. 2023-05-29 Added a discussion of the two-level namespace. 2023-04-27 Added a mention of the size tool. 2023-01-23 Explained the compile-time and run-time roles of a framework. Made other minor editorial changes. 2022-11-17 Added an explanation of TAPI. 2022-10-12 Added links to Mach-O documentation. 2022-09-29 Added info about .dSYM files. Added a few more links to WWDC sessions. 2022-09-21 First posted.

Hello! We would like to know the steps required to build an application and submit it to the Apple Store using an automated process on a server. Here are our conditions: We have a server running macOS Sonoma 14.6.1 on Amazon EC2. Xcode 16.1 (Build version 16B40) is installed. We use only console commands, as the GUI is not available. We use Cordova to add the iOS platform to the application. A private key, certificate, and provisioning profile have already been created and are located on the server. Could you please clarify: What commands are needed to configure the Keychain to use the certificate and provisioning profile? How can we build the application using xcodebuild? What are the steps to sign and submit the application to the App Store with minimal human interaction? Thank you in advance for your assistance!

I regularly bump into folks confused by this issue, so I thought I’d collect my thoughts on the topic into a single (hopefully) coherent post. If you have questions or comments, put them in a new thread here on the forums. Feel free to use whatever subtopic and tags that apply to your situation, but make sure to add the Debugging tag so that I see your thread go by. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Testing and Debugging Code Running in the Background I regularly see questions like this: My background code works just fine in Xcode but fails when I download the app from the App Store. or this: … or fails when I run my app from the Home screen. or this: How do I step through my background code? These suggest a fundamental misunderstanding of how the debugger interacts with iOS’s background execution model. The goal of this post is to explain that misunderstanding so that you can effectively test and debug background code. Note The focus of this post is iOS. The advice here generally applies to any of iOS’s ‘child’ platforms, so iPadOS, tvOS, and so on. However, there will be some platform specific differences, especially on watchOS. This advice here doesn’t apply to macOS. It’s background execution model is completely different than the one used by iOS. Understand the Fundamentals The key point to note here is that the debugger prevents your app from suspending. This has important consequences for iOS’s background execution model. Normally: iOS suspends your app when it’s in the background. Once your app is suspended, it becomes eligible for termination. The most common reason for this is that the system wants to recover memory, but it can happen for various other reasons. For example, the system might terminate a suspended app in order to update it. Under various circumstances your app can continue running after moving to the background. A great example of this is the continued processed task feature, introduced in iOS 26 beta. Alternatively, your app can be resumed or relaunched in the background to perform some task. For example, the region monitor feature of Core Location can resume or relaunch your app in the background when the user enters or leaves a region. If no app needs to be executing, the system can sleep the CPU. None of this happens in the normal way if the debugger is attached to your app, and it’s vital that you take that into account when debugging code that runs in the background. An Example of the Problem For an example of how this can cause problems, imagine an app that uses an URLSession background session. A background session will resume or relaunch your app in the background when specific events happen. This involves two separate code paths: If your app is suspended, the session resumes it in the background. If your app is terminated, it relaunches it in the background. Neither code path behaves normally if the debugger is attached. In the first case, the app never suspends, so the resume case isn’t properly exercised. Rather, your background session acts like it would if your app were in the foreground. Normally this doesn’t cause too many problems, so this isn’t a huge concern. On the other hand, the second case is much more problematic. The debugger prevents your app from suspending, and hence from terminating, and thus you can’t exercise this code path at all. Seek Framework-Specific Advice The above is just an example, and there are likely other things to keep in mind when debugging background code for a specific framework. Consult the documentation for the framework you’re working with to see if it has specific advice. Note For URLSession background sessions, check out Testing Background Session Code. The rest of this post focuses on the general case, offering advice that applies to all frameworks that support background execution. Run Your App Outside of Xcode When debugging background execution, launch your app from the Home screen. For day-to-day development: Run the app from Xcode in the normal way (Product > Run). Stop it. Run it again from the Home screen. Alternatively, install a build from TestFlight. This accurately replicates the App Store install experience. Write Code with Debugging in Mind It’s obvious that, if you run the app without attaching the debugger, you won’t be able to use the debugger to debug it. Rather: Extract the core logic of your code into libraries, and then write extensive unit tests for those libraries. You’ll be able to debug these unit tests with the debugger. Add log points to help debug your integration with the system. Treat your logging as a feature of your product. Carefully consider where to add log points and at what level to log. Check this logging code into your source code repository and ship it — or at least the bulk of it — as part of your final product. This logging will be super helpful when it comes to debugging problems that only show up in the field. My general advice is that you use the system log for these log points. See Your Friend the System Log for lots of advice on that front. One of the great features of the system log is that disabled log points are very cheap. In most cases it’s fine to leave these in your final product. Attach and Detach In some cases it really is helpful to debug with the debugger. One option here is to attach to your running app, debug a specific thing, and then detach from it. Specifically: To attach to a running app, choose Debug > Attach to Process > YourAppName in Xcode. To detach, choose Debug > Detach. Understand Force Quit iOS allows users to remove an app from the multitasking UI. This is commonly known as force quit, but that’s not a particularly accurate term: The multitasking UI doesn’t show apps that are running, it shows apps that have been run by the user. The UI shows recently run apps regardless of whether they’re in the foreground, running in the background, suspended, or terminated. So, removing an app from the UI may not actually quit anything. Removing an app sets a flag that prevents the app from being launched in the background. That flag gets cleared when the user next launches the app manually. Note In some circumstances iOS will not honour this flag. The exact cases where this happens are not documented and have changed over time. Keep these behaviours in mind as you debug your background execution code. For example, imagine you’re trying to test the URLSession background relaunch code path discussed above. If you force quit your app, you’ll never hit this code path because iOS won’t relaunch your app in the background. Rather, add a debug-only button that causes your app to call exit. IMPORTANT This suggestion is for debugging only. Don’t include a Quit button in your final app! This is specifically proscribed by QA1561. Alternatively, if you’re attached to your app with Xcode, simply choose Product > Stop. This is like calling exit; it has no impact on your app’s ability to run in the background. Test With Various Background App Refresh Settings iOS puts users in control of background execution via the options in Settings > General > Background App Refresh. Test how your app performs with the following settings: Background app refresh turned off overall Background app refresh turned on in general but turned off for your app Background app refresh turned on in general and turned on for your app IMPORTANT While these settings are labelled Background App Refresh, they affect subsystems other than background app refresh. Test all of these cases regardless of what specific background execution feature you’re using. Test Realistic User Scenarios In many cases you won’t be able to fully test background execution code at your desk. Rather, install a TestFlight build of your app and then use the device as a normal user would. For example: To test Core Location background execution properly, actual leave your office and move around as a user might. To test background app refresh, use your app regularly during the day and then put your device on charge at night. Testing like this requires two things: Patience Good logging The system log may be sufficient here, but you might need to investigate other logging solutions that are more appropriate for your product. These testing challenges are why it’s critical that you have unit tests to exercise your core logic. It takes a lot of time to run integration tests like this, so you want to focus on integration issues. Before starting your integration tests, make sure that your unit tests have flushed out any bugs in your core logic. Revision History 2025-08-12 Made various editorial changes. 2025-08-11 First posted.

I would like to know if macOS DEXT supports the following networking features: Tx/Rx Multiqueue, RSS, RSC, NS/ARP offload, PTP or packet timestamping and TSN. I couldn't find relevant documentation for these features in the Apple Developer Documentation. If they are supported, could you let me know which features are supported and how to find the corresponding official Apple documentation? Thanks

The app I'm working on has iOS 16.0 as target. Recently Live Activities support was added, but then it started crashing when running on iOS 16.0 devices. After some investigation, I've found that the culprit was the presence of NSUserActivityTypeLiveActivity and WidgetCenter.UserInfoKey.activityID, even though they were inside an @available(iOS 17.2, *) block. If I comment these two variables, the app work as expected. I've also tried adding #if canImport(ActivityKit) around the code, but without success. But if the @available isn't working, how can I prevent this? It looks like a bug, since the documentation says that NSUserActivityTypeLiveActivity is supported but iOS 14.0+, but I'm pretty sure it was introduced on 16.1. This is the only output I get with the crash: dyld[66888]: Symbol not found: _$s9WidgetKit0A6CenterC11UserInfoKeyV10activityIDSSvgZ Referenced from: <D6EFF120-2681-34C1-B261-8F3F7B388238> /Users/<redacted>/Library/Developer/CoreSimulator/Devices/8B5B4DC9-3D54-4C91-8C88-E705E851CA0F/data/Containers/Bundle/Application/DB6671FF-CB07-4570-BD63-C851D94FAF29/<redacted>.app/<redacted>.debug.dylib Expected in: <C5E72BB5-533F-3658-A987-E849888F4DFC> /Library/Developer/CoreSimulator/Volumes/iOS_20A360/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 16.0.simruntime/Contents/Resources/RuntimeRoot/System/Library/Frameworks/WidgetKit.framework/WidgetKit

In System Settings -> General -> Date & Time, there is an option called "Set time and date automatically". Is there a way to check whether it is enabled programmatically?

So I'm testing a microapp that is contained in an IPFS folder. I use a web3 website that is used to view NFTs and their IPFS files. The app has gyro controls, which are enabled through a confirmation gesture. In iOS 18.5, when I press "Request Permission" button I get the popup to allow the app to acess movement and orientation. In iOS26, pressing the button does nothing. Keep in mind that this only happens through the website, that uses iframes. When I load the IPFS file from a direct link, the popup appears with no issue. I think this might be because iOS26 uses WebGPU or it might be a bug since iOS26 is still in beta.

We recently upgrade our OS from Sonoma to Sequoia and have been using Fastlane to generate our ipa(s) However since the upgrade we are facing the following error: 00:26:30 + xcodebuild -exportArchive -exportOptionsPlist /var/folders/sk/_k2v73dd5hscn2mcvcqc43gs69_8bc/T/gym_config20240930-10121-gjvg0h.plist -archivePath /Users/ejeniossvc/jenkins/workers/workspace/local-jenkins-build32/-1449677665/452/build-dir/rqa-EnterpriseDistribution/dist/MY.xcarchive -exportPath /var/folders/sk/_k2v73dd5hscn2mcvcqc43gs69_8bc/T/gym_output20240930-10121-27pj6 -allowProvisioningUpdates -skipPackagePluginValidation -skipMacroValidation CODE_SIGN_STYLE=Manual DEVELOPMENT_TEAM=xxxxxxxxxxxx 00:26:30 error: Couldn't load -exportOptionsPlist: The data couldn’t be read because it isn’t in the correct format. 00:26:30 00:26:30 Swift.DecodingError.dataCorrupted(Swift.DecodingError.Context(codingPath: [], debugDescription: "The given data was not a valid property list.", underlyingError: Optional(Error Domain=NSCocoaErrorDomain Code=3840 "Encountered unexpected character s on line 1 while looking for close tag for key" UserInfo={NSDebugDescription=Encountered unexpected character s on line 1 while looking for close tag for key})))

Hi! My simulator will not build because there is essentially a package conflict. I am adding Firebase to a Flutter application. Simulator built before trying to add firebase but now I'm getting errors telling me a package can't be found even though it's installed Output Package Loading (Xcode): Missing package product 'FirebaseCore' .../ios/Runner.xcodeproj I added target 'Runner' do use_frameworks! use_modular_headers! pod 'FirebaseDatabase' pod 'FirebaseAnalytics' pod 'FirebaseMessaging' pod 'FirebaseCore' pod 'FirebaseFunctions' pod 'FirebaseAppCheck' pod 'FirebaseFirestore' pod 'FirebaseStorage' pod 'FirebaseDynamicLinks' pod 'FirebaseAuth' flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__)) target 'RunnerTests' do inherit! :search_paths end end and ran pod install with no errors. Opening the runnner.xcworkspace shows all of the named packages under "Frameworks, Libraries, and Embedded Content' I've tried manually adding through Xcode those packages but then get a conflict error, so I am out of ideas as to how to fix this. It appears to be something new with the latest MacOS update as I've seen another person with the same problem that started after he updated... I've also cleaned, re-installed, re-booted a few times because My Android emulator builds fine Any help would be appreciated! Thanks!

Hi everyone, I'm working on an NFC-related app using CoreNFC with APDU commands to read and write tags. I’ve encountered an issue when trying to handle the scenario where the user cancels the NFC session. Here’s what’s happening: When a user cancels the NFC session manually (e.g., by tapping "Cancel"), I see an error log indicating tagReaderSession|userCancelled. However, when I explicitly call session.invalidate(errorMessage: "No NFC tag found") in my code to handle a scenario where no tag is detected, the session still shows the error as userCancelled instead of my custom error message. This behavior is confusing both in terms of debugging and for providing feedback to users, as I expect my custom message to appear instead of the generic "user cancelled" message. func tagReaderSessionDidBecomeActive(_ session: NFCTagReaderSession) { // Session becomes active } func tagReaderSession(_ session: NFCTagReaderSession, didDetect tags: [NFCTag]) { // Handle tag detection logic } func tagReaderSession(_ session: NFCTagReaderSession, didInvalidateWithError error: Error) { print("Session invalidated with error: \(error.localizedDescription)") } func handleNoTagDetected(session: NFCTagReaderSession) { session.invalidate(errorMessage: "No NFC tag found") } I call handleNoTagDetected(session:) explicitly when no tag is detected, expecting the custom error message to show. However, the system still shows the cancellation error. Has anyone else experienced this behavior? Is this the intended behavior for CoreNFC, or am I missing something in my implementation? Any guidance would be appreciated. Thanks in advance!

Hi All, I have an App on AppStore, recently the minimum supported version of the app was changed from iOS 12 to iOS 14. Post that the TestFlight builds are crashing on launch. If we revert the minimum supported iOS version to 12, the crash no longer happens. This project is using cocoapods, and from the crash logs it seems the issue with with PLCrashReporter framework. "EXC_CRASH" Termination reason: DYLD 9 weak-def symbol not found '__ZN7plcrash3PL_5async15dwarf_cfa_stateljiE10push_stateEv'. This issue is happening only on TestFlight builds where the minimum supported version is 14.0 Any pointer to a solution is welcome.

Hi, I am encountering a linking issue with a project for an iOS .NET MAUI application that I am developing using Visual Studio 17.11.4. This project includes a custom static library (.a). The custom static library (.a) depends on the libxml2 library. However, it appears that libxml2 is not included in Xcode 15.4 (Sonoma OS), resulting in the following error: error : Undefined symbols for architecture arm64: error : "_xmlBufferCreate", referenced from: .... I have set the following additional arguments for compilation: -cxx -gcc_flags "-lz -lxml2". Despite my efforts to install libxml2 using Homebrew, I have not been successful. Could you please advise on how I can resolve this issue? Specifically, what is the path that Xcode uses to include libxml2?

This posts collects together a bunch of information about the symbols found in a Mach-O file. It assumes the terminology defined in An Apple Library Primer. If you’re unfamiliar with a term used here, look there for the definition. If you have any questions or comments about this, start a new thread in the Developer Tools & Services > General topic area and tag it with Linker. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Understanding Mach-O Symbols Every Mach-O file has a symbol table. This symbol table has many different uses: During development, it’s written by the compiler. And both read and written by the linker. And various other tools. During execution, it’s read by the dynamic linker. And also by various APIs, most notably dlsym. The symbol table is an array of entries. The format of each entry is very simple, but they have been used and combined in various creative ways to achieve a wide range of goals. For example: In a Mach-O object file, there’s an entry for each symbol exported to the linker. In a Mach-O image, there’s an entry for each symbol exported to the dynamic linker. And an entry for each symbol imported from dynamic libraries. Some entries hold information used by the debugger. See Debug Symbols, below. Examining the Symbol Table There are numerous tools to view and manipulate the symbol table, including nm, dyld_info, symbols, strip, and nmedit. Each of these has its own man page. A good place to start is nm: % nm Products/Debug/TestSymTab U ___stdoutp 0000000100000000 T __mh_execute_header U _fprintf U _getpid 0000000100003f44 T _main 0000000100008000 d _tDefault 0000000100003ecc T _test 0000000100003f04 t _testHelper Note In the examples in this post, TestSymTab is a Mach-O executable that’s formed by linking two Mach-O object files, main.o and TestCore.o. There are three columns here, and the second is the most important. It’s a single letter indicating the type of the entry. For example, T is a code symbol (in Unix parlance, code is in the text segment), D is a data symbol, and so on. An uppercase letter indicates that the symbol is visible to the linker; a lowercase letter indicates that it’s internal. An undefined (U) symbol has two potential meanings: In a Mach-O image, the symbol is typically imported from a specific dynamic library. The dynamic linker connects this import to the corresponding exported symbol of the dynamic library at load time. In a Mach-O object file, the symbol is undefined. In most cases the linker will try to resolve this symbol at link time. Note The above is a bit vague because there are numerous edge cases in how the system handles undefined symbols. For more on this, see Undefined Symbols, below. The first column in the nm output is the address associated with the entry, or blank if an address is not relevant for this type of entry. For a Mach-O image, this address is based on the load address, so the actual address at runtime is offset by the slide. See An Apple Library Primer for more about those concepts. The third column is the name for this entry. These names have a leading underscore because that’s the standard name mangling for C. See An Apple Library Primer for more about name mangling. The nm tool has a lot of formatting options. The ones I use the most are: -m — This prints more information about each symbol table entry. For example, if a symbol is imported from a dynamic library, this prints the library name. For a concrete example, see A Deeper Examination below. -a — This prints all the entries, including debug symbols. We’ll come back to that in the Debug Symbols section, below. -p — By default nm sorts entries by their address. This disables that sort, causing nm to print the entries in the order in which they occur in the symbol table. -x — This outputs entries in a raw format, which is great when you’re trying to understand what’s really going on. See Raw Symbol Information, below, for an example of this. A Deeper Examination To get more information about each symbol table, run nm with the -m option: % nm -m Products/Debug/TestSymTab (undefined) external ___stdoutp (from libSystem) 0000000100000000 (__TEXT,__text) [referenced dynamically] external __mh_execute_header (undefined) external _fprintf (from libSystem) (undefined) external _getpid (from libSystem) 0000000100003f44 (__TEXT,__text) external _main 0000000100008000 (__DATA,__data) non-external _tDefault 0000000100003ecc (__TEXT,__text) external _test 0000000100003f04 (__TEXT,__text) non-external _testHelper This contains a world of extra information about each entry. For example: You no longer have to remember cryptic single letter codes. Instead of U, you get undefined. If the symbol is imported from a dynamic library, it gives the name of that dynamic library. Here we see that _fprintf is imported from the libSystem library. It surfaces additional, more obscure information. For example, the referenced dynamically flag is a flag used by the linker to indicate that a symbol is… well… referenced dynamically, and thus shouldn’t be dead stripped. Undefined Symbols Mach-O’s handling of undefined symbols is quite complex. To start, you need to draw a distinction between the linker (aka the static linker) and the dynamic linker. Undefined Symbols at Link Time The linker takes a set of files as its input and produces a single file as its output. The input files can be Mach-O images or dynamic libraries [1]. The output file is typically a Mach-O image [2]. The goal of the linker is to merge the object files, resolving any undefined symbols used by those object files, and create the Mach-O image. There are two standard ways to resolve an undefined symbol: To a symbol exported by another Mach-O object file To a symbol exported by a dynamic library In the first case, the undefined symbol disappears in a puff of linker magic. In the second case, it records that the generated Mach-O image depends on that dynamic library [3] and adds a symbol table entry for that specific symbol. That entry is also shown as undefined, but it now indicates the library that the symbol is being imported from. This is the core of the two-level namespace. A Mach-O image that imports a symbol records both the symbol name and the library that exports the symbol. The above describes the standard ways used by the linker to resolve symbols. However, there are many subtleties here. The most radical is the flat namespace. That’s out of scope for this post, because it’s a really bad option for the vast majority of products. However, if you’re curious, the ld man page has some info about how symbol resolution works in that case. A more interesting case is the -undefined dynamic_lookup option. This represents a halfway house between the two-level namespace and the flat namespace. When you link a Mach-O image with this option, the linker resolves any undefined symbols by adding a dynamic lookup undefined entry to the symbol table. At load time, the dynamic linker attempts to resolve that symbol by searching all loaded images. This is useful if your software works on other Unix-y platforms, where a flat namespace is the norm. It can simplify your build system without going all the way to the flat namespace. Of course, if you use this facility and there are multiple libraries that export that symbol, you might be in for a surprise! [1] These days it’s more common for the build system to pass a stub library (.tbd) to the linker. The effect is much the same as passing in a dynamic library. In this discussion I’m sticking with the old mechanism, so just assume that I mean dynamic library or stub library. If you’re unfamiliar with the concept of a stub library, see An Apple Library Primer. [2] The linker can also merge the object files together into a single object file, but that’s relatively uncommon operation. For more on that, see the discussion of the -r option in the ld man page. [3] It adds an LC_LOAD_DYLIB load command with the install name from the dynamic library. See Dynamic Library Identification for more on that. Undefined Symbols at Load Time When you load a Mach-O image the dynamic linker is responsible for finding all the libraries it depends on, loading them, and connecting your imports to their exports. In the typical case the undefined entry in your symbol table records the symbol name and the library that exports the symbol. This allows the dynamic linker to quickly and unambiguously find the correct symbol. However, if the entry is marked as dynamic lookup [1], the dynamic linker will search all loaded images for the symbol and connect your library to the first one it finds. If the dynamic linker is unable to find a symbol, its default behaviour is to fail the load of the Mach-O image. This changes if the symbol is a weak reference. In that case, the dynamic linking continues to load the image but sets the address of the symbol to NULL. See Weak vs Weak vs Weak, below, for more about this. [1] In this case nm shows the library name as dynamically looked up. Weak vs Weak vs Weak Mach-O supports two different types of weak symbols: Weak references (aka weak imports) Weak definitions IMPORTANT If you use the term weak without qualification, the meaning depends on your audience. App developers tend to assume that you mean a weak reference whereas folks with a C++ background tend to assume that you mean a weak definition. It’s best to be specific. Weak References Weak references support the availability mechanism on Apple platforms. Most developers build their apps with the latest SDK and specify a deployment target, that is, the oldest OS version on which their app runs. Within the SDK, each declaration is annotated with the OS version that introduced that symbol [1]. If the app uses a symbol introduced later than its deployment target, the compiler flags that import as a weak reference. The app is then responsible for not using the symbol if it’s run on an OS release where it’s not available. For example, consider this snippet: #include <xpc/xpc.h> void testWeakReference(void) { printf("%p\n", xpc_listener_set_peer_code_signing_requirement); } The xpc_listener_set_peer_code_signing_requirement function is declared like so: API_AVAILABLE(macos(14.4)) … int xpc_listener_set_peer_code_signing_requirement(…); The API_AVAILABLE macro indicates that the symbol was introduced in macOS 14.4. If you build this code with the deployment target set to macOS 13, the symbol is marked as a weak reference: % nm -m Products/Debug/TestWeakRefC … (undefined) weak external _xpc_listener_set_peer_code_signing_requirement (from libSystem) If you run the above program on macOS 13, it’ll print NULL (actually 0x0). Without support for weak references, the dynamic linker on macOS 13 would fail to load the program because the _xpc_listener_set_peer_code_signing_requirement symbol is unavailable. [1] In practice most of the SDK’s declarations don’t have availability annotations because they were introduced before the minimum deployment target supported by that SDK. Weak definitions Weak references are about imports. Weak definitions are about exports. A weak definition allows you to export a symbol from multiple images. The dynamic linker coalesces these symbol definitions. Specifically: The first time it loads a library with a given weak definition, the dynamic linker makes it the primary. It registers that definition such that all references to the symbol resolve to it. This registration occurs in a namespace dedicated to weak definitions. That namespace is flat. Any subsequent definitions of that symbol are ignored. Weak definitions are weird, but they’re necessary to support C++’s One Definition Rule in a dynamically linked environment. IMPORTANT Weak definitions are not just weird, but also inefficient. Avoid them where you can. To flush out any unexpected weak definitions, pass the -warn_weak_exports option to the static linker. The easiest way to create a weak definition is with the weak attribute: __attribute__((weak)) void testWeakDefinition(void) { } IMPORTANT The C++ compiler can generate weak definitions without weak ever appearing in your code. This shows up in nm like so: % nm -m Products/Debug/TestWeakDefC … 0000000100003f40 (__TEXT,__text) weak external _testWeakDefinition … The output is quite subtle. A symbol flagged as weak external is either a weak reference or a weak definition depending on whether it’s undefined or not. For clarity, use dyld_info instead: % dyld_info -imports -exports Products/Debug/TestWeakRefC Products/Debug/TestWeakDefC [arm64]: … -imports: … 0x0001 _xpc_listener_set_peer_code_signing_requirement [weak-import] (from libSystem) % dyld_info -imports -exports Products/Debug/TestWeakDefC Products/Debug/TestWeakDefC [arm64]: -exports: offset symbol … 0x00003F40 _testWeakDefinition [weak-def] … … Here, weak-import indicates a weak reference and weak-def a weak definition. Weak Library There’s one final confusing use of the term weak, that is, weak libraries. A Mach-O image includes a list of imported libraries and a list of symbols along with the libraries they’re imported from. If an image references a library that’s not present, the dynamic linker will fail to load the library even if all the symbols it references in that library are weak references. To get around this you need to mark the library itself as weak. If you’re using Xcode it will often do this for your automatically. If it doesn’t, mark the library as optional in the Link Binary with Libraries build phase. Use otool to see whether a library is required or optional. For example, this shows an optional library: % otool -L Products/Debug/TestWeakRefC Products/Debug/TestWeakRefC: /usr/lib/libEndpointSecurity.dylib (… 511.60.5, weak) … In the non-optional case, there’s no weak indicator: % otool -L Products/Debug/TestWeakRefC Products/Debug/TestWeakRefC: /usr/lib/libEndpointSecurity.dylib (… 511.60.5) … Debug Symbols or Why the DWARF still stabs. (-: Historically, all debug information was stored in symbol table entries, using a format knows as stabs. This format is now obsolete, having been largely replaced by DWARF. However, stabs symbols are still used for some specific roles. Note See <mach-o/stab.h> and the stab man page for more about stabs on Apple platforms. See stabs and DWARF for general information about these formats. In DWARF, debug symbols aren’t stored in the symbol table. Rather, debug information is stored in various __DWARF sections. For example: % otool -l Intermediates.noindex/TestSymTab.build/Debug/TestSymTab.build/Objects-normal/arm64/TestCore.o | grep __DWARF -B 1 sectname __debug_abbrev segname __DWARF … The compiler inserts this debug information into the Mach-O object file that it creates. Eventually this Mach-O object file is linked into a Mach-O image. At that point one of two things happens, depending on the Debug Information Format build setting. During day-to-day development, set Debug Information Format to DWARF. When the linker creates a Mach-O image from a bunch of Mach-O object files, it doesn’t do anything with the DWARF information in those objects. Rather, it records references to the source objects files into the final image. This is super quick. When you debug that Mach-O image, the debugger finds those references and uses them to locate the DWARF information in the original Mach-O object files. Each reference is stored in a stabs OSO symbol table entry. To see them, run nm with the -a option: % nm -a Products/Debug/TestSymTab … 0000000000000000 - 00 0001 OSO …/Intermediates.noindex/TestSymTab.build/Debug/TestSymTab.build/Objects-normal/arm64/TestCore.o 0000000000000000 - 00 0001 OSO …/Intermediates.noindex/TestSymTab.build/Debug/TestSymTab.build/Objects-normal/arm64/main.o … Given the above, the debugger knows to look for DWARF information in TestCore.o and main.o. And notably, the executable does not contain any DWARF sections: % otool -l Products/Debug/TestSymTab | grep __DWARF -B 1 % When you build your app for distribution, set Debug Information Format to DWARF with dSYM File. The executable now contains no DWARF information: % otool -l Products/Release/TestSymTab | grep __DWARF -B 1 % Xcode runs dsymutil tool to collect the DWARF information, organise it, and export a .dSYM file. This is actually a document package, within which is a Mach-O dSYM companion file: % find Products/Release/TestSymTab.dSYM Products/Release/TestSymTab.dSYM Products/Release/TestSymTab.dSYM/Contents … Products/Release/TestSymTab.dSYM/Contents/Resources/DWARF Products/Release/TestSymTab.dSYM/Contents/Resources/DWARF/TestSymTab … % file Products/Release/TestSymTab.dSYM/Contents/Resources/DWARF/TestSymTab Products/Release/TestSymTab.dSYM/Contents/Resources/DWARF/TestSymTab: Mach-O 64-bit dSYM companion file arm64 That file contains a copy of the the DWARF information from all the original Mach-O object files, optimised for use by the debugger: % otool -l Products/Release/TestSymTab.dSYM/Contents/Resources/DWARF/TestSymTab | grep __DWARF -B 1 … sectname __debug_line segname __DWARF … Raw Symbol Information As described above, each Mach-O file has a symbol table that’s an array of symbol table entries. The structure of each entry is defined by the declarations in <mach-o/nlist.h> [1]. While there is an nlist man page, the best documentation for this format is the the comments in the header itself. Note The terms nlist stands for name list and dates back to truly ancient versions of Unix. Each entry is represented by an nlist_64 structure (nlist for 32-bit Mach-O files) with five fields: n_strx ‘points’ to the string for this entry. n_type encodes the entry type. This is actually split up into four subfields, as discussed below. n_sect is the section number for this entry. n_desc is additional information. n_value is the address of the symbol. The four fields within n_type are N_STAB (3 bits), N_PEXT (1 bit), N_TYPE (3 bits), and N_EXT (1 bit). To see these raw values, run nm with the -x option: % nm -a -x Products/Debug/TestSymTab … 0000000000000000 01 00 0300 00000036 _getpid 0000000100003f44 24 01 0000 00000016 _main 0000000100003f44 0f 01 0000 00000016 _main … This prints a column for n_value, n_type, n_sect, n_desc, and n_strx. The last column is the string you get when you follow the ‘pointer’ in n_strx. The mechanism used to encode all the necessary info into these fields is both complex and arcane. For the details, see the comments in <mach-o/nlist.h> and <mach-o/stab.h>. However, just to give you a taste: The entry for getpid has an n_type field with just the N_EXT flag set, indicating that this is an external symbol. The n_sect field is 0, indicating a text symbol. And n_desc is 0x0300, with the top byte indicating that the symbol is imported from the third dynamic library. The first entry for _main has an n_type field set to N_FUN, indicating a stabs function symbol. The n_desc field is the line number, that is, line 22. The second entry for _main has an n_type field with N_TYPE set to N_SECT and the N_EXT flag set, indicating a symbol exported from a section. In this case the section number is 1, that is, the text section. [1] There is also an <nlist.h> header that defines an API that returns the symbol table. The difference between <nlist.h> and <mach-o/nlist.h> is that the former defines an API whereas the latter defines the Mach-O on-disk format. Don’t include both; that won’t end well!