Fixing iOS Simulator Errors (Xcode 12.4 and Cocos2d-x 3.17.2)

Hi everyone.

After upgrading to Xcode 12 (12.4) our Cocos2d-x 3.17.2 games would no longer compile for iOS Simulators.
It may also be useful to note I’m doing this on macOS Catalina 10.15.7.

We’ve since fixed the issues and have iOS Simulators working again.
I wanted to share the errors we encountered and how we fixed them in case anyone needs them as some of them I couldn’t find anywhere online.

… not found / built for arm64

warning: framework not found

ld: warning: directory not found for option '-F/Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/XCFrameworkIntermediates/AAA'
ld: framework not found AAA

error: module map file not found

<unknown>:0: error: module map file '/Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/AAA/AAA.modulemap' not found

warning: ignoring file - link with incompatible architecture

ld: warning: ignoring file /Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libAAA iOS.a, building for iOS Simulator-x86_64 but attempting to link with file built for iOS Simulator-arm64

The fix

All of the above errors/warnings were fixed by updating the build settings of every project in the workspace to build iOS Simulators for the x86_64 architecture exclusively.
More detail on applying this fix to Xcode/CMakeList.txt in this thread.

Projects that come from Pods need have their build settings updated via the Podfile's post_install instead.
This applies the fix after running pod install:

post_install do |installer|
    installer.pods_project.build_configurations.each do |config|
        config.build_settings["ARCHS[sdk=iphonesimulator*]"] = "x86_64"

:warning: This will only update the Pods project itself. If any target/sub-project overrides architectures you may need to use installer.generated_pod_targets or installer.pod_target_subprojects to update those too. Check the Pod post_install docs for a list of variables.

No symbols/file

Missing required architecture x86_64

ld: warning: ignoring file /Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libAAA.a, missing required architecture x86_64 in file /Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libAAA.a (2 slices)

May also appear as

ld: symbol(s) not found for architecture x86_64

No such file or directory

clang: error: no such file or directory: '/Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libAAA iOS.a'

The fix

Both of the above issues were fixed by removing VALID_ARCHS from the .xcconfig/.pbxproj file of the project(s) in question.

:information_source: VALID_ARCHS seem to take priority over ARCHS.
:warning: Our VALID_ARCHS did not include x86_64 so adding it may also be a valid fix. Since VALID_ARCHS is deprecated in Xcode 12 I’d recommend replacing them with ARCHS/EXCLUDED_ARCHS.

If the project in question comes from Pods we need to remove VALID_ARCHS via the Podfile's post_install instead.
This applies the fix after running pod install:

post_install do |installer|
    installer.aggregate_targets.each do |target|
        target.xcconfigs.each do |config_name, config_file|

:warning: This will only remove VALID_ARCHS from .xcconfig files.

Linking in incompatible platform

ld: in /Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libluacocos2d iOS.a(lj_vm.o), building for iOS Simulator, but linking in object file built for macOS, file '/Users/.../Library/Developer/Xcode/DerivedData/.../Build/Products/Debug-iphonesimulator/libluacocos2d iOS.a' for architecture x86_64

The fix

It took me a while to figure this one out.
The solution was to update libluajit.a that comes from the Cocos2d-x dependencies.
I’d recommend to simply try updating your dependencies to the latest verison as that may solve the problem. We did this which allowed us to compile, however launching the game on simulators crashed when trying to init lua:

Thread 1: EXC_BAD_ACCESS (code=1, address=0x10759)

Coming from

_state = lua_open();



This same crash has appeared in the past and required rebuilding LuaJit.

I checked the pre-built dependencies and libluajit.a for iOS hasn’t been updated since Nov 2019.
The fix was to rebuild it for simulators.

Building libluajit.a for iOS Simulators

  1. Clone the LuaJit repo

    git clone -b v2.1

    :information_source: More info here

  2. Navigate to LUAJIT_PROJECT_FOLDER/src and make the library
    :warning: LUAJIT_PROJECT_FOLDER is the root folder of cloned luajit source

    make CROSS=/usr/bin/ TARGET_FLAGS="-mios-simulator-version-min=9.0 -isysroot `xcode-select -p`/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk" TARGET_SYS=iOS

    :information_source: More info here. Example here
    :warning: Your iOS simulator minimum version may differ from mine

  3. Navigate to LUAJIT_PROJECT_FOLDER and install the library

    sudo make install TARGET_SYS=iOS
  4. Navigate to /usr/local/lib/ to find libluajit-5.1.a
    :warning: This library is for iOS Simulators only

  5. Copy libluajit-5.1.a somewhere under your cocos2d-x project
    I went with cocos2d-x/extra-libs/iPhoneSimulator/

  6. Rename libluajit-5.1.a to libluajit.a so it matches the existing ones

  7. Update LIBRARY_SEARCH_PATHS for the lua bindings project

    • Via Xcode:
      1. Open cocos2d_lua_binding.xcodeproj
      2. Select the libluacocos2d iOS target
      3. Switch to the Build Settings tab
      4. Search for “library search”
      5. Add the relative path for the iOS Simulator libluajit.a we just built
        :warning: Make sure this is only used when building for iOS Simulators
    • Via Text:
      1. Open the cocos2d_lua_binding’s project.pbxproj in text editor
      2. Add the following to all buildSettings
        "LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*]" = "$(SRCROOT)/../../../../extra-libs/iphonesimulator";
        :warning: Your relative path may differ from mine

If anyone knows of a simpler way to do any of this, or there’s any issues with my instructions, please let me know.

It’d be great to see the pre-built dependencies updated with a newer version of libluajit.a.

I hope this is helpful.