From ccc4ecba2912257a6757d32d13c43221a2d48023 Mon Sep 17 00:00:00 2001 From: Dragos Daian Date: Fri, 17 May 2024 13:08:55 +0200 Subject: [PATCH] Update README.md by removing typo Remove uneeded message Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md update readme and also ios build to be with .framework as well Co-Authored-By: Patrick Exner (FlameLizard) --- README.md | 109 ++++++++++++++++++++----- SConstruct | 2 +- bin/ios/{ => ios.framework}/Info.plist | 0 demo/bin/example.gdextension | 2 + 4 files changed, 93 insertions(+), 20 deletions(-) rename bin/ios/{ => ios.framework}/Info.plist (100%) diff --git a/README.md b/README.md index c484ce0..8cd795e 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,24 @@ This repository serves as a quickstart template for GDExtension development with * An empty Godot project (`demo/`) * godot-cpp as a submodule (`godot-cpp/`) * GitHub Issues template (`.github/ISSUE_TEMPLATE.yml`) -* GitHub CI/CD to publish your library packages when creating a release (`.github/workflows/builds.yml`) +* GitHub CI/CD workflows to publish your library packages when creating a release (`.github/workflows/builds.yml`) +* GitHub CI/CD actions to build (`.github/actions/build/action.yml`) and to sign Mac frameworks (`.github/actions/build/sign.yml`). * preconfigured source files for C++ development of the GDExtension (`src/`) +## Usage - Template + +To use this template, log in to GitHub and click the green "Use this template" button at the top of the repository page. +This will let you create a copy of this repository with a clean git history. Make sure you clone the correct branch as these are configured for development of their respective Godot development branches and differ from each other. Refer to the docs to see what changed between the versions. + +For getting started after cloning your own copy to your local machine, you should: +* initialize the godot-cpp git submodule via `git submodule update --init` +* change the name of your library + * change the name of the compiled library file inside the `SConstruct` file by modifying the `libname` string. + * change the pathnames of the to be loaded library name inside the `demo/bin/example.gdextension` file. By replacing `libgdexample` to the name specified in your `SConstruct` file. + * change the name of the `demo/bin/example.gdextension` file +* change the `entry_symbol` string inside your `demo/bin/your-extension.gdextension` file to be configured for your GDExtension name. This should be the same as the `GDExtensionBool GDE_EXPORT` external C function. As the name suggests, this sets the entry function for your GDExtension to be loaded by the Godot editors C API. +* register the classes you want Godot to interact with inside the `register_types.cpp` file in the initialization method (here `initialize_gdextension_types`) in the syntax `ClassDB::register_class();`. + ## Usage - Actions The actions builds `godot-cpp` at a specified location, and then builds the `gdextension` at a configurable location. It builds for desktop, mobile and web and allows for configuration on what platforms you need. It also supports configuration for debug and release builds, and for double builds. @@ -16,7 +31,8 @@ The action uses SConstruct for both godot-cpp and the GDExtension that is built. To reuse the build actions, in a github actions yml file, do the following: -```name: Build GDExtension +```yml +name: Build GDExtension on: workflow_call: push: @@ -72,6 +88,13 @@ jobs: arch: ${{ matrix.arch }} float-precision: single build-target-type: template_release + - name: 🔗 GDExtension Build + uses: ./.github/actions/build + with: + platform: ${{ matrix.platform }} + arch: ${{ matrix.arch }} + float-precision: ${{ matrix.float-precision }} + build-target-type: template_debug - name: Mac Sign if: ${{ matrix.platform == 'macos' && env.APPLE_CERT_BASE64 }} env: @@ -91,12 +114,59 @@ jobs: name: GDExtension path: | ${{ github.workspace }}/bin/** +``` +The above example is a lengthy one, so we will go through it action by action to see what is going on. + +In the `Checkout` step, we checkout the code. +In the `🔗 GDExtension Build` step, we are using the reusable action: +```yml +uses: godotengine/godot-cpp-template/.github/actions/build@main +with: + platform: ${{ matrix.platform }} + arch: ${{ matrix.arch }} + float-precision: single + build-target-type: template_release ``` +with the parameters from the matrix. + +As a result of this step, the binaries will be built in the `bin` folder (as specified in the SConstruct file). + +Note: for macos, you will have to build the binary as a `.dylib` in a `EXTENSION-NAME.framework` folder. The framework folder should also have a `Resources` folder with a file called `Info.plist`. Without this file, signing will fail. + +Note: for iOS, the same should be as for MacOS, however the `Info.plist` file needs to be close to the `.dylib`, instead of in a `Resources` folder (If this is not done, the build will fail to upload to the App Store). -## Usage - Signing +So, in our case, the builds should be: -You will need: +```sh +bin/EXTENSION-NAME.macos.template_debug.framework/EXTENSION-NAME.macos.template_release +bin/EXTENSION-NAME.ios.template_debug.framework/EXTENSION-NAME.ios.template_release.arm64.dylib + +Afterwards, you want to set in the `.gdextension` file the paths to the `.framework` folder, instead of the `.dylib` file (Note that for the `.dylib` binary, the extension is not needed, you could have a file without any extension and it would still work). + +In the `name: Mac Sign` step, we are signing the generated mac binaries. +We are reusing the following action: +```yml +uses: godotengine/godot-cpp-template/.github/actions/sign@main +with: + FRAMEWORK_PATH: bin/macos/macos.framework + APPLE_CERT_BASE64: ${{ secrets.APPLE_CERT_BASE64 }} + APPLE_CERT_PASSWORD: ${{ secrets.APPLE_CERT_PASSWORD }} + APPLE_DEV_PASSWORD: ${{ secrets.APPLE_DEV_PASSWORD }} + APPLE_DEV_ID: ${{ secrets.APPLE_DEV_ID }} + APPLE_DEV_TEAM_ID: ${{ secrets.APPLE_DEV_TEAM_ID }} + APPLE_DEV_APP_ID: ${{ secrets.APPLE_DEV_APP_ID }} +``` +As you can see, this action requires some secrets to be configured in order to run. Also, you need to tell it the path to the `.framework` folder, where you have both the binary (`.dylib` file) and the `Resources` folder with the `Info.plist` file. + +## Configuration - Mac Signing Secrets + +In order to sign the Mac binary, you need to configure the following secrets: +`APPLE_CERT_BASE64`, `APPLE_CERT_PASSWORD`, `APPLE_DEV_PASSWORD`, `APPLE_DEV_ID`, `APPLE_DEV_TEAM_ID`, `APPLE_DEV_APP_ID`. These secrets are stored in the example above in the Github secrets for repositories. The names of the secrets have to match the names of the secrets you use for your action. For more on this, read the [Creating secrets for a repository](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) article from Github. + +These secrets are then passed down to the `godotengine/godot-cpp-template/.github/actions/sign@main` action that signs the binary. + +In order to configure these secrets, you will need: - A Mac - An Apple ID enrolled in Apple Developer Program (99 USD per year) @@ -159,20 +229,21 @@ base64 -i Certificates.p12 -o Certificates.base64 - Copy the contents of the generated file: Eg. -- APPLE_CERT_BASE64 = `...`(A long text file) - -- While still +- `APPLE_CERT_BASE64` = `...`(A long text file) -## Usage - Template +After these secrets are obtained, all that remains is to set them in Github secrets and then use them in the Github action, eg. in the above Github action usage example, this part: -To use this template, log in to GitHub and click the green "Use this template" button at the top of the repository page. -This will let you create a copy of this repository with a clean git history. Make sure you clone the correct branch as these are configured for development of their respective Godot development branches and differ from each other. Refer to the docs to see what changed between the versions. - -For getting started after cloning your own copy to your local machine, you should: -* initialize the godot-cpp git submodule via `git submodule update --init` -* change the name of your library - * change the name of the compiled library file inside the `SConstruct` file by modifying the `libname` string. - * change the pathnames of the to be loaded library name inside the `demo/bin/example.gdextension` file. By replacing `libgdexample` to the name specified in your `SConstruct` file. - * change the name of the `demo/bin/example.gdextension` file -* change the `entry_symbol` string inside your `demo/bin/your-extension.gdextension` file to be configured for your GDExtension name. This should be the same as the `GDExtensionBool GDE_EXPORT` external C function. As the name suggests, this sets the entry function for your GDExtension to be loaded by the Godot editors C API. -* register the classes you want Godot to interact with inside the `register_types.cpp` file in the initialization method (here `initialize_gdextension_types`) in the syntax `ClassDB::register_class();`. +``` +- name: Mac Sign + if: ${{ matrix.platform == 'macos' && env.APPLE_CERT_BASE64 }} + env: + APPLE_CERT_BASE64: ${{ secrets.APPLE_CERT_BASE64 }} + uses: godotengine/godot-cpp-template/.github/actions/sign@main + with: + FRAMEWORK_PATH: bin/macos/macos.framework + APPLE_CERT_BASE64: ${{ secrets.APPLE_CERT_BASE64 }} + APPLE_CERT_PASSWORD: ${{ secrets.APPLE_CERT_PASSWORD }} + APPLE_DEV_PASSWORD: ${{ secrets.APPLE_DEV_PASSWORD }} + APPLE_DEV_ID: ${{ secrets.APPLE_DEV_ID }} + APPLE_DEV_TEAM_ID: ${{ secrets.APPLE_DEV_TEAM_ID }} +``` \ No newline at end of file diff --git a/SConstruct b/SConstruct index 75c2372..5fb32d2 100644 --- a/SConstruct +++ b/SConstruct @@ -55,7 +55,7 @@ sources = Glob("src/*.cpp") file = "{}{}{}".format(libname, env["suffix"], env["SHLIBSUFFIX"]) -if env["platform"] == "macos": +if env["platform"] == "macos" or env["platform"] == "ios": platlibname = "{}.{}.{}".format(libname, env["platform"], env["target"]) file = "{}.framework/{}".format(env["platform"], platlibname, platlibname) diff --git a/bin/ios/Info.plist b/bin/ios/ios.framework/Info.plist similarity index 100% rename from bin/ios/Info.plist rename to bin/ios/ios.framework/Info.plist diff --git a/demo/bin/example.gdextension b/demo/bin/example.gdextension index 99c1746..679baf6 100644 --- a/demo/bin/example.gdextension +++ b/demo/bin/example.gdextension @@ -7,6 +7,8 @@ compatibility_minimum = "4.1" macos.debug = "res://bin/libgdexample.macos.template_debug.framework" macos.release = "res://bin/libgdexample.macos.template_release.framework" +ios.debug = "res://bin/libgdexample.ios.template_debug.framework" +ios.release = "res://bin/libgdexample.ios.template_release.framework" windows.debug.x86_32 = "res://bin/libgdexample.windows.template_debug.x86_32.dll" windows.release.x86_32 = "res://bin/libgdexample.windows.template_release.x86_32.dll" windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.x86_64.dll"