Improve onboarding

[alicerunsonfedora]

The current build process and README documentation leaves a lot to be desired in terms of flow. In my testing as a first time user, I encountered some friction that could be helped with either an explanation in the README or some changes in the library:

• First, I ran into an issue when pulling the latest tagged release (v0.3, at time of writing) into my Swift package because SwiftGodot uses unsafe build flags. I was able to get around this by targeting a branch and/or specific revision instead, but I think this can/should be improved in some way.
• I didn't realize that, if I were using SwiftGodot to just provide scripts to a Godot project, I needed to use the CLI to build the resulting dylib files needed to create the gdextension. Granted, I had assumed this would be the case, and it didn't really bother me; however, I think this could cause some confusion to those not really familiar with the process.
• When editing scripts in Xcode, I often needed to rebuild the entire project by cleaning the build folder and then building the project. I am unsure if this is a Xcode quirk caused by incremental builds, but it did leave to some weird quirks.
• Finally, as I mentioned in Support for utility functions #50, some of the common utility methods such as print weren't available to me, which made it trickier to determine if my scripts were being loaded correctly.

I think improving the onboarding process can make working with the library a little easier and less of a developer headache.

[JustinSharkey]

I've run into #3 as well... At least twice I've had issues where my command line script says successful build but the binary it copies over does not have my changes. I assumed it to be an Xcode issue as well (and I live in Xcode during the week so maybe I'm predisposed to blame Xcode). But since someone else has the same issue maybe it's worth investigating/noting.

[migueldeicaza]

Xcode seems to be way too happy to rebuild everything even when not needed, but I would not put the blame just yet on it, or on SwiftPM, I might have gotten a dependency wrong or I might be accidentally causing something to trip the dependency checker in the wrong way.

I will try to investigate because it is tedious.

In the meantime, I did a new 0.4 release with the xcframework which should be slightly less painful, but makes it harder to make changes live to the binding.

[nvanfleet]

First, I ran into an issue when pulling the latest tagged release (v0.3, at time of writing) into my Swift package because SwiftGodot uses unsafe build flags. I was able to get around this by targeting a branch and/or specific revision instead, but I think this can/should be improved in some way.

@alicerunsonfedora can you tell me how to get around that?

[alicerunsonfedora]

First, I ran into an issue when pulling the latest tagged release (v0.3, at time of writing) into my Swift package because SwiftGodot uses unsafe build flags. I was able to get around this by targeting a branch and/or specific revision instead, but I think this can/should be improved in some way.

@alicerunsonfedora can you tell me how to get around that?

Pull the dependency with a specified revision or branch instead:

// swift-tools-version: 5.8

import PackageDescription

let package = Package(
    name: "Protractor",
    platforms: [ ... ],
    products: [
        .library(
            name: "Protractor",
            type: .dynamic,
            targets: ["Protractor"]),
    ],
    dependencies: [
        .package(url: "https://github.com/migueldeicaza/SwiftGodot", branch: "main")
    ],
    targets: [ ... ]
)

Alternatively, you can use the prebuilt xcframework with a binary target.

[Stiivi]

Another small detail: the swift build process will create libMyGame.dylib which needs to be renamed to plain MyGame (no prefix, no extension). The libSwiftGodot.dylib should remain with the name as created (with the prefix and extension).

[alicerunsonfedora]

Another small detail: the swift build process will create libMyGame.dylib which needs to be renamed to plain MyGame (no prefix, no extension).

I don’t think this is the case, as Godot doesn’t seem to care as long as you point to the correct file ame/path when creating the GDExtension file. I use the libXXX.dylib naming in my own projects and they work just fine.

[nvanfleet]

Another small detail: the swift build process will create libMyGame.dylib which needs to be renamed to plain MyGame (no prefix, no extension).

I don’t think this is the case, as Godot doesn’t seem to care as long as you point to the correct file ame/path when creating the GDExtension file. I use the libXXX.dylib naming in my own projects and they work just fine.

I can echo this, I have my own name for my dylib file and it works fine. My gdextension file has something like

macos.debug = "res://bin/lib<name>.dylib"
macos.release = "res://bin/lib<name>.dylib"
macos.debug.arm64 = "res://bin/lib<name>.dylib"
macos.release.arm64 = "res://bin/lib<name>.dylib"

If I ever get to the point where I am building for more than just my own machine the names might end up more complicated of course.

[alicerunsonfedora]

Just a quick update regarding these points:

• First, I ran into an issue when pulling the latest tagged release (v0.3, at time of writing) into my Swift package because SwiftGodot uses unsafe build flags. I was able to get around this by targeting a branch and/or specific revision instead, but I think this can/should be improved in some way.
• I didn't realize that, if I were using SwiftGodot to just provide scripts to a Godot project, I needed to use the CLI to build the resulting dylib files needed to create the gdextension. Granted, I had assumed this would be the case, and it didn't really bother me; however, I think this could cause some confusion to those not really familiar with the process.

I've just created some tutorials that were merged (see #98) that better explains this process, which should greatly improve the onboarding. I'm not sure when the website version will get updated (or maybe it is already updated), but it should be there for the DocC bundle at the very least.

[migueldeicaza]

Back at my computer: documentation pushed.

I might look into automatically generating the docs on pull requests, so I don't need to run this manually, but it is an slow process, so might want to find a way of not doing this on every push.

[alicerunsonfedora]

Doing it automatically would be nice. I planned to make a PR for that as well, but the current CI runs are failing. Perhaps once we can get the CI checks to pass, this can be done?