Document creating iOS export template ZIP

[MartinMajewski]

Godot version

4.1 and master branch

System information

MacOS 14.1 on MacBook Pro M1 Max

Issue description

I followed the "Compiling for iOS" documentation here and compiling on MacOS Sonoma 14.1 went smoothly. However, the iOS Xcode template cannot be opened with Xcode 15.0.1 (the most current stable version). Xcode refuses to open it with the bland message:

I couldn't find any obvious issue with the syntax of the inner "pbxproj" file, so something else is broken.

I tried the 4.1 tagged source code, and the most recent master branch commit.

Any suggestions?

Cheers,
Martin

Steps to reproduce

Clone the Godot source code (4.1 or main), navigate to "misc/dist/ios_xcode" and try opening the godot_ios.xcodeproj file with Xcode 15.0.1

Minimal reproduction project

There is nothing to provide, as it is all in the official repo.

[bruvzg]

The project template should be zipped along with compiled libraries to make a export template which can be used during export (from the Godot editor). The project is not intended to be opened directly (it's incomplete, a bunch of stuff is filled up by the exporter).

[MartinMajewski]

Edit: I think I got your point by looking into the documentation for exporting for iOS! Please ignore my original post for now, and let me try to get the information on both documentations together. If I succeed, I will try to fill in the information gaps in the documentation that lead me on the wrong path, and I will create a pull request for it.

Maybe we misunderstood each other, or I got a wrong impression of the purpose of the entire process.

I'm not talking about exporting a Godot project (a game, e.g.) onto iOS but the Godot Editor as an application onto an iOS device (like on the iPad). Even for a project export (like documented here, you need a working Xcode project, eventually, or you cannot build and deploy an iOS application.

So, either the documentation is incomplete, missing important information, or that xcproject file is broken, indeed.

Would you mind explaining the process of packaging the Godot editor as an iOS app in a bit more depth? Thanks.

[bruvzg]

I'm not talking about exporting a Godot project (a game, e.g.) onto iOS but the Godot Editor as an application onto an iOS device (like on the iPad).

There's no Godot Editor support for iOS, project in the misc is for export template only.

Godot Editor is designed to run in multiple processes, and that's impossible on iOS (so we need godotengine/godot-proposals#8151 to be implemented to add support for iOS). You can hack it to run editor part (editor will partially work, but you won't be able to run projects for it), see bruvzg/godot@a8de536 for example, but there's no Xcode project (you can export empty project from the editor, remove PCK file and replace libraries if you want to try).

Even for a project export (like documented here, you need a working Xcode project, eventually, or you cannot build and deploy an iOS application.

The working project is created by the Godot Editor during export (from the template project you are trying to open).

So, either the documentation is incomplete, missing important information, or that xcproject file is broken, indeed.

It is incomplete, steps for packing template are clearly missing.

Would you mind explaining the process of packaging the Godot editor as an iOS app in a bit more depth?

1. Do everything in https://docs.godotengine.org/en/stable/contributing/development/compiling/compiling_for_ios.html
2. Archive content of the ios_xcode folder into ZIP file.

File tree in the ZIP should look like this

.
├── MoltenVK.xcframework
│   ├── Info.plist
│   ├── ios-arm64
│   │   └── libMoltenVK.a
│   ├── ios-arm64_x86_64-maccatalyst
│   │   └── libMoltenVK.a
│   └── ios-arm64_x86_64-simulator
│       └── libMoltenVK.a
├── data.pck
├── godot_ios
│   ├── Images.xcassets
│   │   ├── LaunchImage.launchimage
│   │   │   ├── Contents.json
│   │   │   ├── Default-480h@2x.png
│   │   │   ├── Default-568h@2x.png
│   │   │   ├── Default-667h@2x.png
│   │   │   ├── Default-Landscape-736h@3x.png
│   │   │   ├── Default-Landscape-X.png
│   │   │   ├── Default-Landscape.png
│   │   │   ├── Default-Landscape@2x.png
│   │   │   ├── Default-Portrait-736h@3x.png
│   │   │   ├── Default-Portrait-X.png
│   │   │   ├── Default-Portrait.png
│   │   │   └── Default-Portrait@2x.png
│   │   └── SplashImage.imageset
│   │       ├── Contents.json
│   │       ├── splash@2x.png
│   │       └── splash@3x.png
│   ├── Launch Screen.storyboard
│   ├── dummy.cpp
│   ├── dummy.h
│   ├── dummy.swift
│   ├── dylibs
│   │   └── empty
│   ├── en.lproj
│   │   └── InfoPlist.strings
│   ├── export_options.plist
│   ├── godot_ios-Info.plist
│   └── godot_ios.entitlements
├── godot_ios.xcodeproj
│   ├── project.pbxproj
│   ├── project.xcworkspace
│   │   └── contents.xcworkspacedata
│   └── xcshareddata
│       └── xcschemes
│           └── godot_ios.xcscheme
├── libgodot.ios.debug.xcframework
│   ├── Info.plist
│   ├── ios-arm64
│   │   ├── empty
│   │   └── libgodot.a
│   └── ios-arm64_x86_64-simulator
│       ├── empty
│       └── libgodot.a
└── libgodot.ios.release.xcframework
    ├── Info.plist
    ├── ios-arm64
    │   ├── empty
    │   └── libgodot.a
    └── ios-arm64_x86_64-simulator
        ├── empty
        └── libgodot.a

3. Select this ZIP file in the export dialog in the editor on macOS:

4. After exporting, you can open the project in Xcode.

[Calinou]

It is incomplete, steps for packing template are clearly missing.

In general, I find manual template packing steps a bit fragile (not just for iOS). I wonder if we should move this to a SCons option that you pass after building the last export template you're interested in (since ios.zip includes fat binaries, and both debug + release). There isn't much reason to do it manually when the process can be automated – we then only have to mention the SCons option in the documentation.

See https://github.com/Calinou/godot/tree/scons-android-add-generate-apk-option where I attempted to add generate_apk=yes for Android builds, so that you don't have to call Gradle manually to do that.
Edit: Done in godotengine/godot#84440.

We can still write documentation for 4.2, but this is something we should look into after 4.2 is released.

[MartinMajewski]

Ah, I get you. Yes, manual packaging is not only fragile but tedious af! :-)

Okay, my experiment will end here. Thank you both for taking your time and explaining to a Godot noob. 😅

Anyhow, I would love to see the Godot editor for iPad Pro devices. However, with the limited Xcode pipeline on iOS, building out a game would still not be possible. The entire app packaging and signing needs to be done on a Mac in any case. I have yet to hear of an end-to-end app development solution on an iOS device for an iOS device.

This ticket can be closed if no further discussion is necessary from your side.

Cheers,
Martin

[MartinMajewski]

Just found this: https://www.youtube.com/watch?v=n6Igyjj3QYQ

[jbromberg]

There's also this recent post by the creator of the SwiftGodot and SwiftGodotKit libraries.

https://x.com/migueldeicaza/status/1717591286927012279?s=20

[bruvzg]

Just found this: https://www.youtube.com/watch?v=n6Igyjj3QYQ

It seems to be based on the same bruvzg/godot@a8de536 which I have already mentioned earlier.

What's the patch is doing:

• When you open a project from Project Manager, instead of running a new Godot instance (or restarting itself, which is also unsupported by iOS), it's saving the command line argument for the editor to the file and crashes.
• On restart (you have to manually dismiss the crash message and start it again), it's reading command line args from this file, starts the editor, and deletes the command line file.

Consequently, there's no way to run the project from the editor (or run any of the external tools used during the export). This approach is obviously not suitable for any practical use. But the editor can work (with some small issues, but most of them should be fixable by reusing code paths and config from Android editor).

I think there were attempts (when the first patch was discussed in the Godot Rocket Chat) to use multiple apps (one for PM, one for Editor, and one for running project) and custom URL handlers as well. This might be a bit better, but also not something that can be published (or even sideloaded w/o paid account, due to app ID number limitation). But I'm not sure if it was actually done in any form.

There's also this recent post by the creator of the SwiftGodot and SwiftGodotKit libraries.
https://x.com/migueldeicaza/status/1717591286927012279?s=20

[comment from the thread] yeah, I had to disable the project manager. Godot has certainly a peculiar design (unreal also makes these odd choices).

I guess it might be similar limited POC as well, the main instancing issue is likely still there.

[skrillfalconblast]

@bruvzg I'm trying to export a custom build to IOS, thus I've followed you're instructions above and have created an identical ios_xcode.zip. Sadly, the export fails throwing an error, saying:

"Requested template library 'libgodot.ios.debug.xcframework' not found. It might be missing from your template archive."

And I have definitely included it. How could I ameliorate this?

[skrillfalconblast]

I've found the fix! You have to select all the files in xcode_ios and zip them creating "Archive.zip", then rename that to xcode_ios.zip.

"The reason it keeps failing the first way is because in export_plugin.cpp, it looks for library files that begin with "libgodot.ios". However if you compress the folder, all of the files will begin with "ios_xcode/" instead, and the begins_with check fails, therefore not detecting any libraries."

• Courtesy of a Godot reddit comment on this post: https://www.reddit.com/r/godot/comments/191sfjh/problem_using_my_own_compiled_ios_export_templates/

The docs on compiling a custom Xcode iOS build and exporting it to iOS are horrendous.