[single branch] Introduce preview.h and Makefile option LIBDRAGON_PREVIEW

[Dragorn421]

Goal

Not have to maintain two different branches: trunk and preview

To that end, the idea is to drop the trunk branch and keep only the preview branch.
However to keep the ability of experimenting with new APIs that are not yet stable, there still needs to be a clear distinction between stable APIs and preview APIs

A choice has also been made to make the preview opt-in switch a n64.mk option, that is, NOT a libdragon build time option. So an installed libdragon toolchain will be able to be used for compiling both stable-using and preview-using projects.

The changes

n64.mk now has LIBDRAGON_PREVIEW ?= 0. Setting to 1 enables usage of preview APIs.

This variable controls appending -DLIBDRAGON_PREVIEW or not to the compiler/assembler flags, which controls the definitions of macros in new file include/preview.h. These are the macros under stable (i.e. the default LIBDRAGON_PREVIEW=0):

/// 0 or 1 depending on whether preview APIs are enabled
#define HAVE_PREVIEW 0
/// Error if preview APIs are disabled
#define ASSERT_PREVIEW _Pragma("GCC error \"This API is part of preview\"")
/// Error if preview APIs are disabled and a function with this attribute is used
#define PREVIEW_API __attribute__((error("This API is part of preview")))

• headers can behave differently depending on HAVE_PREVIEW
• whole files can use ASSERT_PREVIEW to make compilation error on including them
• preview-only functions can be tagged with PREVIEW_API, making compilation error on calling them

Building libdragon

Building libdragon, in particular building the preview APIs parts, requires preview APIs to be usable. To that effect, the Makefile and tools/Makefile makefiles unconditionally define the LIBDRAGON_BUILD_TIME macro (i.e. pass -DLIBDRAGON_BUILD_TIME to the compiler) which makes preview.h (see above) behave as if LIBDRAGON_PREVIEW was defined, allowing usage and compilation of preview APIs.

CI

CI (github actions) has been amended to build examples and test roms for both stable and preview.

The system in action

The rest of the changes are about tagging the OpenGL implementation and APIs/tools building upon it as preview, for demonstration purposes. For example:

• e.g. GL/gl.h uses ASSERT_PREVIEW to make compilation error unless preview
• HAVE_PREVIEW is used to conditionally include model64.h from libdragon.h only if preview APIs are available
• HAVE_PREVIEW is also used in the test rom source to only include opengl tests under preview (otherwise the build would error)