Add temp utilities (alias OS::get_temp_dir(), FileAccess::create_temp(), and DirAccess::create_temp())

[adamscott]

This PR adds OS::get_temp_dir(), FileAccess::create_temp(), and DirAccess::create_temp() functions (the PR originally spelled tmp instead of temp), for all the supported platforms.

The concept of temporary files and directories

 There's already OS.get_cache_dir(), why do we need temporary files?

Temporary files and cache files are really similar, but they are distinct.

	Cache files	Temporary files
Can be deleted at any time by the user	✅	✅
Can be deleted at any time by the OS	❌	✅
Purpose	Persistent temporary files, usually can be expected to be there the next time, useful after creation.	Volatile temporary files, usually not needed after use.
Example	Generated thumbnail icons.	One-time write to a file to get the binary data of it.

So this is why Godot should support and provide an API for this special kind of files.

Methods

OS.get_temp_dir()

This function returns the global OS temporary dir for the application. It may be the root /tmp directory for most of the Unix/Linux systems, but for other platforms, it is the temporary dir given by the OS.

If no such thing as a temporary directory exist for the OS (ie. the Android platform), a directory inside the cache directory is chosen.

FileAccess.create_temp(int mode_flags, String prefix = "", String extension = "", bool keep = false)

This static function returns a FileAccess object with a temporary file open.

For sorting purposes, you can set prefix to the name of your project, just to be able to quickly debug temporary files if needed.

As ResourceLoaders usually detect the type of the file with the extension, you can pass a custom extension to add to the file name.

And if you set keep to true, the file will not get cleaned up when the FileAccess instance will be freed.

DirAccess.create_temp(String prefix = "", bool keep = false)

This static function returns a DirAccess object with a temporary directory open. Useful if you need temporary named files and directories.

prefix and keep exist such as in FileAccess.create_temp().

If keep is false, it will recursively delete the contents of the temporary directory when the DirAccess instance will be freed.

[Calinou]

I've tried to use the following code, but despite create_tmp() being static, I get an error:

func _ready() -> void:
	var tmp_file := FileAccess.create_tmp(FileAccess.WRITE_READ, ".txt")
	tmp_file.store_string("I am *not* persisted after the file is closed.")
	tmp_file.close()
	OS.shell_open(tmp_file.get_path_absolute())  # Should fail because the file has been removed at this point.

	var tmp_file_keep := FileAccess.create_tmp(FileAccess.WRITE_READ, ".txt", true)
	tmp_file_keep.store_string("I am persisted after the file is closed.")
	tmp_file.close()
	OS.shell_open(tmp_file_keep.get_path_absolute())  # Should work because `keep` is `true`.

Cannot call method 'store_string' on a null value.

PS: Do modes other than FileAccess.WRITE make sense here? The file path is guaranteed to not exist before creation, so I don't think other FileAccess modes make sense to use here.

[adamscott]

@Calinou The cleanup is done on the FileAccess destructor. So, .close() doesn't clean-up the file per se.

I did this because FileAccess::reopen() exists, but I just saw that it is not exposed to the public API (_bind_methods()).

[adamscott]

PS: Do modes other than FileAccess.WRITE make sense here? The file path is guaranteed to not exist before creation, so I don't think other FileAccess modes make sense to use here.

What I did is that I create the file first with WRITE, then close, then open it again with the mode wished.

[Alex2782]

https://chat.godotengine.org/channel/android?msg=3peujMoKbDJCQ0eul

Todo: Android bindings for OS::get_tmp_dir()

https://github.com/Alex2782/godot/tree/get_tmp_dir_for_android

5 files changed, +41 lines: Alex2782@9dd4af4

func _ready() -> void:
	print("get_cache_dir(): ", OS.get_cache_dir())
	print("get_tmp_dir(): ", OS.get_tmp_dir())

Tested on Android 13, Samsung Tab S7. I'm still not sure if I've taken everything into account correctly.

[Calinou]

Tested locally on Linux, it works as expected.

const ITERATIONS = 1_000

func _ready() -> void:
	for __ in ITERATIONS:
		FileAccess.create_tmp(FileAccess.WRITE_READ, "hello", "txt", true)
		DirAccess.create_tmp("world", true)

After checking the contents of /tmp, there are 1,000 files and folders created respectively.

[akien-mga]

We try to avoid abbreviations in the API, so we should probably avoid tmp throughout, even if that's the canonical Unix name. On Windows it would be temp which is at least bit better to the uninitiated.

We could go all the way with temporary, but since we do use dir already as an abbreviation in some of these APIs, I think something like OS::get_temp_dir / DirAccess::create_temp_dir / FileAccess::create_temp_file (note I'm adding _dir and _file for the DA/FA APIs, which I think are clearer than just create_tmp).

Thoughts?

[Mickeon]

temp is a common shorthand in programming to name anything temporary. Namely variables, but also game assets, in a similar vein to dummy.
So I think it's reasonably appropriate, but it's also worth noting there's no existing method in the API with "temp" or "temporary" in their name. The closest thing is the {temp_dir} placeholder for SSH Remote Deploy scripts.

[Repiteo]

temp is only slightly more verbose than tmp, and conveys the exact same information that temporary would. And while temp isn't used by any of our API, it IS used by the Python standard library tempfile which we import in some of our buildscripts (and all of its functions/variables). My vote is for temp.

[adamscott]

I added a commit that renames tmp to temp! Thanks for the input everyone.

[akien-mga]

I would still suggest create_temp_file and create_temp_dir for the respective FileAccess and DirAccess APIs. But it's not a big blocker if others prefer just create_temp for both.

[Mickeon]

mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm

[Repiteo]

I prefer the plain create_temp for both, as it's more in-line with their existing api create and create_for_path.

[bruvzg]

Tested on macOS, iOS and Windows, works as expected.

[Repiteo]

Thanks!