Developer Documentation

[StarWitch]

Forked off from the mega-documentation branch.

[Akaricchi]

Something went wrong with the history here. Can you please rebase this onto new-docs and remove the extraneous commits?

[Akaricchi]

As for the actual contents, I think it'd be good to have a separate document for the build and packaging options. This information isn't only useful to developers, but to downstream distributors and advanced users as well. Once we've got the most useful build options covered, I think we can finally merge that and the new readme into master, before covering the development/contributing guidelines.

[StarWitch]

@Akaricchi What were you hoping you see in a "Building/Maintainer" documentation? What's currently up, minus the developer-specific stuff, plus some examples of how to generate packages?

[Akaricchi]

An overview of the most useful build configuration options, e.g. how to enable the GLES3 renderer with shader translation support, how to set the default renderer, how to integrate ANGLE, relationship between package_data and enable_zip, when to use install_relative… An overview of the dependency management conventions would be nice, i.e. submodules are for things that should be vendored with Taisei, while system libraries should usually be preferred over subprojects. Packaging commands can be documented as well, but probably after everything else, as they are of not much usefulness to both end users and distro package maintainers. Probably also worth noting that when building distro packages, it's best to set validate_glsl explicitly to either true (when a compatible glslc binary is present in the build environment) or false (when it isn't).

[Akaricchi]

It's also worth noting that prefix has a slightly different meaning depending on the type of target system and whether install_relative is enabled.

On a typical Linux system without install_relative, it should be set to something like /usr/local (which is actually the default value). That'll install Taisei system-wide (root required; meson will ask for privilege elevation automatically), correctly add it to the system menus, associate replay files, put taisei in PATH (/usr/local/bin should be in PATH on most distros by default), etc. /usr should not be used as the prefix, because that's typically controlled by the package manager. $HOME/.local could be used as a prefix for user-level installations (this also should add menu entries and replay file associations), though in that case, taisei's main resource directory ($PREFIX/share/taisei) will be the same as the default user storage directory (~/.local/share/taisei, where the config/replays/screenshots/etc. are). That's a bit of a problem with the XDG basedir spec. It is of course possible to specify a non-standard prefix, but then you don't get the menu entries and PATH presence handled for you. None of this is really unique to Taisei though; anyone who frequently builds software from source on *nix systems should be familiar with it.

In install_relative mode, the meaning is different: it should be some Taisei-specific directory, e.g. $HOME/games/taisei, as all of the game's files will be dumped directly into it. Freedesktop.org stuff like menu entries and replay associations aren't even installed in this case — again, you're on your own there. install_relative is also implied by default on some platforms (Windows, macOS when macos_bundle=true, emscripten, switch…)

[StarWitch]

For some reason, ninja ctags -C build/ wasn't working. Might have been that I didn't have the proper tool installed. Removed the custom build target in meson.build, and this should be good to go now.