Local development NuGet package not updating - probable documentation issue surrounding GodotNuGetFallbackFolder and GODOT_VERSION_STATUS

[Avantir-Chaosfire]

Godot version

4.0.3

System information

macOS 13.3.1

Issue description

I'm trying to convert my Godot 3 project to Godot 4. I use a custom build of Godot with GodotSteam, mono/.NET enabled and a few other tweaks. The only tweak I've made at the present is an extra argument to the MoveAndSlide method. The project itself is in C#.

I've been following the Compiling with .NET documentation page, and it went perfectly the first time. Built the editor, opened the project, no problems. Then I went to make a change to the editor (added the extra argument to the MoveAndSlide method). Built again, no problem. But now when I build the project, I get an error indicating my change to the editor wasn't applied (the build error indicates that there are no arguments to MoveAndSlide - as if my change wasn't applied).

I am sure I built correctly. I commented out some code and used reflection to investigate the GodotSharp assembly my project links to at run time, and it links to the correct version of GodotSharp with the argument I added to MoveAndSlide. This is a compile time problem, not a link time problem.

I saw the documentation had some information about how GodotSharp is distributed through a NuGet package, and how it uses a local NuGet package for local development, including this note:

By default, all development builds share a version number, which can cause some issues with caching of the NuGet packages. To solve this issue either use GODOT_VERSION_STATUS to give every build a unique version or delete GodotNuGetFallbackFolder after every build to clear the package cache.

This is almost certainly my problem, but the note isn't helpful enough to fix it. What is GODOT_VERSION_STATUS? Where is the GodotNuGetFallbackFolder (I searched my computer and couldn't find it)?

I tried setting GODOT_VERSION_STATUS as an environment variable to "abcde1" and built again, but that didn't appear to do anything. It did update the NuGet packages in my local NuGet package source, but they still show as 4.0.3-rc, not 4.0.3-abcde1 (is that what's supposed to change? I think it is).

My local NuGet cache has no Godot 4 assemblies, since I have been using the --push-nupkgs-local flag on the build_assemblies.py script.

Part of the problem is that I can't figure out where the GodotSharp assemblies it's using at compile time even are, since they don't show up as references in Visual Studio. On which note, if I use GODOT_VERSION_STATUS to adjust the version number, do I need to update anything in the project file? I see this reference at the top, which looks weird to me:

<Project Sdk="Godot.NET.Sdk/4.0.3-rc">

Does anyone know how to fix this? Is this a bug with local development on a mac? I think either way it's a documentation issue. The GodotNuGetFallbackFolder and GODOT_VERSION_STATUS need to be explained.

Steps to reproduce

Listed above.

Minimal reproduction project

This is an issue with local development of the editor, not with the behaviour of the editor itself.

[raulsntos]

What is GODOT_VERSION_STATUS?

GODOT_VERSION_STATUS is an environment variable. This is how we read it:

godot/methods.py

Lines 96 to 97 in 809a982

	if os.getenv("GODOT_VERSION_STATUS") != None:
	version_info["status"] = str(os.getenv("GODOT_VERSION_STATUS"))

In version 4.0.3-rc the status is the rc part.

If the GODOT_VERSION_STATUS environment variable is not defined, it uses the status from version.py which is usually dev in our development branch (master).

Where is the GodotNuGetFallbackFolder?

According to the file paths documentation, the path for editor data in macOS is ~/Library/Application Support/Godot, so the GodotNuGetFallbackFolder should be in ~/Library/Application Support/Godot/mono/GodotNuGetFallbackFolder.

Users that build the engine from source should keep in mind that the NuGet packages are only copied to this folder when a package with the same version doesn't already exist. Since building from source usually means building the same version multiple times, this means that the package will only be copied the first time so make sure to clear this folder.

This folder has been deprecated in 4.1 (see #73984) but your NuGet configuration may still use it as an additional source so make sure to clear it anyway.

Part of the problem is that I can't figure out where the GodotSharp assemblies it's using at compile time even are

This depends on your NuGet configuration. If you have a NuGet.Config file in your project or a parent directory, that configuration will be used. Otherwise, it will use the user configuration in ~/.nuget/NuGet/NuGet.Config (or other configuration files in the ~/.nuget/NuGet/config directory).

The NuGet configuration specifies which sources to use to retrieve packages, you probably have this configured to use nuget.org and your custom local source where you are pushing the Godot packages after building them with --push-nupkgs-local.

Since in 4.0 we were using the GodotNuGetFallbackFolder, we also add a configuration file in ~/.nuget/NuGet/config/Godot.Offline.Config that uses GodotNuGetFallbackFolder as an additional source (so make sure to clear this folder).

I tried setting GODOT_VERSION_STATUS as an environment variable to "abcde1" and built again, but that didn't appear to do anything.

I'm not a macOS user, but I think I've heard that macOS may not allow reading from the user's environment variables under certain circumstances so maybe that's what's happening here. If you need to change the status try modifying the version.py file instead.

[Avantir-Chaosfire]

Thank you, changing the GODOT_VERSION_STATUS in the version.py file and in my csproj file fixed it.

I do have the GodotNuGetFallbackFolder at the location you mentioned. Not sure why my search didn't find it, must have not been searching hidden folders.

I think this part needs to be added to the official documentation:

I'm not a macOS user, but I think I've heard that macOS may not allow reading from the user's environment variables under certain circumstances so maybe that's what's happening here. If you need to change the status try modifying the version.py file instead.

As well as a section describing how to change the GodotSharp version referenced by the csproj file (it's obvious if you open up the csproj, but if you don't, you wouldn't know).

Another thing that almost tripped me up on the csproj reference - I think the GodotSharp version has to match what appears in the local NuGet package source, but that's not necessarily the same as what you set in the version.py file. I set GODOT_VERSION_STATUS to abcde1, but in my csproj I had to reference 4.0.3-abcde.1. Note the extra dot.

[raulsntos]

As well as a section describing how to change the GodotSharp version referenced by the csproj file

I think opening the project in Godot updates the csproj automatically. But yes, it's probably good to mention it.

I set GODOT_VERSION_STATUS to abcde1, but in my csproj I had to reference 4.0.3-abcde.1. Note the extra dot.

Oh yeah, sorry I forgot to mention. When Godot releases Beta 1, Beta 2, RC 5, the version doesn't separate the number from the status name (beta1, beta2, rc5) but in C# we try to separate it to comply with SemVer 2.0 (see https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions). This allows NuGet to sort the packages correctly.