From 9a8aeac501d777dadffd07443daef6736677a5f2 Mon Sep 17 00:00:00 2001 From: Alice D Date: Sat, 10 Jul 2021 00:33:15 -0400 Subject: [PATCH 01/10] developer docs --- doc/DEVELOPMENT.rst | 471 ++++++++++++++++++++++++++++++++++++++++++++ doc/README.rst | 10 +- 2 files changed, 477 insertions(+), 4 deletions(-) create mode 100644 doc/DEVELOPMENT.rst diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst new file mode 100644 index 0000000000..1f74b689f7 --- /dev/null +++ b/doc/DEVELOPMENT.rst @@ -0,0 +1,471 @@ +Taisei Project - Compiling FAQ +============================== + +.. contents:: + +Introduction +------------ + +This document contains some important tips on compiling and developing for +specific platforms. + +Basic Build Instructions +------------------------ + +Taisei's general dependencies are as follows: + +- C (C11) compiler (``gcc``, ``clang``, etc) +- Python >= 3.5 +- meson >= 0.53.0 +- ninja >= 1.10.0 +- docutils +- make (optional) + +You can optionally install `other dependencies <../README.rst#dependencies>`__, +but the build system will pull in everything else you might need otherwise. + +First, you'll need to checkout the repository. You can do that with the +following: + +.. code:: sh + + git clone https://github.com/taisei-project/taisei.git + cd taisei/ + git submodule update --init --recursive + +Ensure that the ``git submodule`` or Taisei will not build, as it will be +missing many of the dependencies its needs to compile. + +Next, you'll want to set up a prefix for where the game's binaries will be +installed. For starting out development, you're better off installing it to +your HOME directory. + +.. code:: sh + + export TAISEI_PREFIX=/home/{your_username}/bin + +To build and install Taisei on \*nix, there are two options: you can use the +``Makefile`` or you can run the commands directly, depending on your +preferences. + +To use the ``Makefile``: + +.. code:: sh + + cd taisei/ + make all # sets up, compiles, and installs Taisei + +This is equivalent to: + +.. code:: sh + + meson setup build/ --prefix=$TAISEI_PREFIX -Dwerror=true -Ddeprecation_warnings=no-error + meson compile -C build/ + meson install -C build/ + +There are a bunch of different arguments attached to the ``setup`` command. +Here's an explanation of what they do: + +- ``--prefix=$TAISEI_PREFIX`` installs Taisei to the prefix you specified in + the previous step. +- ``-Dwerror=true`` makes compilation **hard fail** on ``Warnings`` put out by + the compiler. This can be a bit of a pain, but a lot of the time the warnings + are there for a good reason, so we treat them as errors. As an example, it + can detect potential null-pointer errors under certain conditions. +- ``-Ddeprecation_warnings=no-error`` turns off those warnings-as-errors for + deprecation warnings specifically, as some system libraries (such as OpenGL + on macOS) may have deprecation warnings for things not related to Taisei's + code. + + +These commands will set up your build environment, compile the game, and +install it to the ``/home/{your_username}/bin`` directory you specified +earlier. You can then run the game by executing the ``taisei`` binary in that +directory (or running the ``Taisei.app`` for macOS). + +Development +----------- + +Build Options +""""""""""""" + +Game Data Path +'''''''''''''' + +When compiling with ``TAISEI_PREFIX`` set, game file data will be +installed to ``$TAISEI_PREFIX/share/taisei/``, and this path will be built +*statically* into the executable. You can decide whether or not you want this +based on your own preferences. Alternatively, you can install game data +relatively as well: + +.. code:: sh + + make setup/install-relative + +Or: + +.. code:: sh + + meson configure build/ -Dinstall_relative=true + +Which will cause save game data to be installed to: + +.. code:: sh + + $TAISEI_PREFIX/taisei/ + $TAISEI_PREFIX/data/ + +Note that ``install relative`` is always set when building for Windows. + +Debugging +''''''''' + +You can enable debugging options/output for development purposes: + +.. code:: sh + + make setup/debug + +Or: + +.. code:: sh + + meson configure build/ -Dbuildtype=debug -Db_ndebug=false + +Faster Builds +''''''''''''' + +This option also helps for speeding up build times, although there is a +theoretical reduction in performance with these options: + +.. code:: sh + + make setup/fastbuild + +Or: + +.. code:: sh + + meson configure build/ -Db_lto=false -Dstrip=false + +Developer Mode +'''''''''''''' + +For debugging actual gameplay, you can set this option and it will enable cheats +and other 'fast-forward' options by the pressing keys defined in +``src/config.h``. + +.. code:: sh + + make setup/developer + +Or: + +.. code:: sh + + meson config build/ -Ddeveloper=true + +Stack Trace Debugging +''''''''''''''''''''' + +This is useful for debugging crashes in the game. It uses +`AddressSanitizer `__: + +.. code:: sh + + make setup/debug-asan + +Or: + +.. code:: sh + + meson configure build/ -Db_sanitize=address,undefined + +Depending on your platform, you may need to specify the specific library binary +to use to launch ASan appropriately. Using macOS as an example: + +.. code:: sh + + export DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib + +The ``../12.0.0/..`` in the path of ``DYLD_INSERT_LIBRARIES`` changes with each +version of XCode. If it fails to launch for you, ensure that the version number +is correct by browsing to the parent directory of ``../clang``. + +Then, you can launch Taisei's binary from the command line (using macOS as an +example): + +.. code:: sh + + /path/to/Taisei.app/Contents/MacOS/Taisei + + +OpenGL ES Support (Optional) +"""""""""""""""""""""""""""" + +3.0 +''' + +The OpenGL ES 3.0 backend is not built by default. To enable it, do: + +.. code:: sh + + make setup/gles/30 + +Or: + +.. code:: sh + + meson configure build/ -Dr_gles30=true -Dshader_transpiler=true -Dr_default=gles30 + +2.0 +''' + +An experimental OpenGL ES 2.0 backend can be enabled similarly, using: + +.. code:: sh + + make setup/gles/20 + +Or: + +.. code:: sh + + meson configure build/ -Dr_gles20=true -Dshader_transpiler=true -Dr_default=gles20 + +However, GLES 2.0 requires a few extensions to be present on your system +to function correctly, most notably: + +- ``OES_depth_texture`` or ``GL_ANGLE_depth_texture`` +- ``OES_standard_derivatives`` +- ``OES_vertex_array_object`` +- ``EXT_frag_depth`` +- ``EXT_instanced_arrays`` or ``ANGLE_instanced_arrays`` or + ``NV_instanced_arrays`` + +ANGLE (Windows/macOS) +''''''''''''''''''''' + +ANGLE support is semi-optional for macOS, and *mandatory* for Windows. Due to +long-standing OpenGL bugs on Windows, it's required so that Taisei runs +correctly on as many GPU configurations as possible. macOS runs fine with the +standard OpenGL 3.3 backend, but requires ANGLE for GL ES 3.0 support. + +For Windows and macOS, you will need Google's ANGLE library for both ES 3.0 and +2.0. You'll need to check out +`ANGLE `__ and build it first. Refer to their +documentation on how to do that. + +Once you've compiled ANGLE, enable it with: + +.. code:: sh + + export LIBGLES=/path/to/libGLESv2.{dll,dylib} + export LIBEGL=/path/to/libEGL.{dll,dylib} + make setup/gles/angle + +Or: + +.. code:: sh + + export LIBGLES=/path/to/libGLESv2.{dll,dylib} + export LIBEGL=/path/to/libEGL.{dll,dylib} + meson configure build/ -Dinstall_angle=true -Dangle_libgles=$LIBGLES -Dangle_libegl=$LIBEGL + +Ensure you use the correct file extension for your platform. (``.dll`` for +Windows, ``.dylib`` for macOS.) + +``meson`` will copy those files over into the package itself when packaging with +``ninja zip`` or ``ninja dmg``. + +Coding Style +------------ + +Tabs/Spaces +""""""""""" + +In the ``*.c`` files, tabs are used. In the ``meson.build`` and ``*.py`` files, +spaces are used. It's a bit inconsistent, but it's the style that was chosen at +the beginning, and one we're probably going to stick with. + +To help you abide by this standard, you should install +`EditorConfig `__ for your preferred editor of +choice, and load in the file found at ``.editorconfig`` in the root of the +project. + +For Loops +""""""""" + +In general, things like ``for`` loops should have no spaces between the ``for`` and opening brace (``(``). For example: + +.. code:: c + + # incorrect + for (int i = 0; i < 10; i++) { log_debug(i); } + + # correct + for(int i = 0; i < 10; i++) { log_debug(i); } + + +Platform-Specific Tips +---------------------- + +Linux (Debian/Ubuntu) +""""""""""""""""""""" + +On an apt-based system (Debian/Ubuntu), ensure you have build dependencies +installed: + +.. code:: sh + + apt-get install meson cmake build-essential + apt-get install libsdl2-dev libsdl2-mixer-dev libogg-dev libopusfile-dev libpng-dev libzip-dev libx11-dev + +If your distribution of Linux uses Wayland as its default window server, ensure +that Wayland deps are installed: + +.. code:: sh + + apt-get install libwayland-dev + +For packaging, your best bet is ``.zip``. Invoke ``ninja`` to package a +``.zip``: + +.. code:: sh + + ninja zip -C build/ + +macOS +""""" + +On macOS, you need to begin with installing the Xcode Command Line Tools: + +.. code:: sh + + xcode-select --install + +There are additional command line tools that you'll need. You can acquire those +by using `Homebrew `__. + +Follow the instructions for installing Homebrew, and then install the following +tools: + +.. code:: sh + + brew install meson cmake pkg-config docutils imagemagick pygments + +The following dependencies are technically optional, and can be pulled in at +build-time, but you're better off installing them yourself to reduce compile +times: + +.. code:: sh + + brew install freetype2 libzip opusfile libvorbis webp sdl2 + +As of 2020-02-18, you should **not** install the following packages via +Homebrew, as the versions available do not compile against Taisei correctly. +If you're having mysterious errors, ensure that they're not installed. + +* ``spirv-tools`` +* ``spirv-cross`` +* ``sdl2_mixer`` + +Remove them with: + +.. code:: sh + + brew remove spirv-tools spirv-cross sdl2_mixer + +Taisei-compatible versions are bundled and will be pulled in at compile time. + +In addition, if you're trying to compile on an older version of macOS +(i.e: <10.12), SDL2 may not compile correctly on Homebrew (as of 2019-02-19). +Let ``meson`` pull in the corrected version for you via subprojects. + +**NOTE:** While Homebrew's optional dependencies greatly improve compile times, +if you can't remove packages that give you errors from your system for whatever +reason, you can force ``meson`` to use its built-in subprojects by using the +following option: + +.. code:: sh + + make setup/fallback + +Or: + +.. code:: sh + + meson configure build/ --wrap-mode=forcefallback + +Optionally, if you're on macOS and compiling for macOS, you can to install +`create-dmg `__, which will allow +you to have nicer-looking macOS ``.dmg`` files for distribution: + +.. code:: sh + + brew install create-dmg + +You can create a ``.dmg`` on either Linux or macOS (although with ``create-dmg`` +on macOS, the macOS-produced ``.dmg`` will look nicer): + +.. code:: sh + + ninja dmg -C build/ + +Windows +""""""" + +While the game itself officially supports Windows, building the project +directly on Windows is a bit difficult to set up due to the radically different +tooling required for a native Windows build environment. + +However, you can still compile on a Windows-based computer by leveraging Windows +10's +`Windows For Linux (WSL) Subsystem `__ +to cross-compile to Windows. Ironically enough, compiling for Windows on Linux +ends up being easier and more consistent than trying to compile with Windows's +native toolset. + +Taisei uses `mstorsjo/llvm-mingw `__ to +achieve cross-compiling on Windows. We also have a ``meson`` machine file +located at ``misc/ci/windows-llvm_mingw-x86_64-build-test-ci.ini`` to go with +that toolchain. In general, you'll need the following tools for compiling Taisei +for Windows on Linux: + +- ``llvm-mingw`` +- `nsis `__ >= 3.0 + +On macOS, you're probably better off using Docker and the +`Docker container `__ that +``llvm-mingw`` provides, and installing ``nsis`` on top of it. Refer to +``misc/ci/Dockerfile.windows`` for more insight. + +Additionally, on Windows, you'll need to make sure you have *ANGLE support* +enabled, as previously mentioned. + +Compiling Issues +---------------- + +-Wunused-variable +""""""""""""""""" + +If you get an error compiling your code, but you're 100% sure that you've +actually used the variable, chances are you're using that variable in an +``assert()`` and are compiling with ``clang``. + +``clang`` won't recognize that the variable is actually being used in an +``assert()``. + +You can use the macro ``attr_unused`` to bypass that warning. This: + +.. code:: c + + int x = 0; + assert(x == 0); + +Becomes this: + +.. code:: c + + attr_unused int x = 0; + assert(x == 0); diff --git a/doc/README.rst b/doc/README.rst index 4b7b2d411e..b380d2c270 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -13,10 +13,12 @@ Gameplay & Troubleshooting Development ----------- -* `BUILD.rst <./BUILD.rst>`__ - how to set up your build environment, - and compile Taisei -* `ENVIRON.rst <./ENVIRON.rst>`__ - various environment variables built - into Taisei to modify its core settings, when run from the command line +* `BUILD.rst <./BUILD.rst>`__ - how to set up your build environment, and + compile Taisei +* `DEVELOPMENT.rst <./DEVELOPMENT.rst>`__ - how to develop with Taisei, + including code style and various other platform-specific tips +* `ENVIRON.rst <./ENVIRON.rst>`__ - various environment variables built into + Taisei to modify its core settings, when run from the command line * `MATH.rst <./MATH.rst>`__ - introduction to complex numbers, used in the coordinate system of Taisei From dc4dc77c5bc39726db2bd689f35436fccf78052b Mon Sep 17 00:00:00 2001 From: Alice D Date: Sat, 10 Jul 2021 00:37:20 -0400 Subject: [PATCH 02/10] get rid of makefile commands (for now) --- doc/DEVELOPMENT.rst | 71 +-------------------------------------------- 1 file changed, 1 insertion(+), 70 deletions(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 1f74b689f7..283b13f08a 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -19,7 +19,6 @@ Taisei's general dependencies are as follows: - meson >= 0.53.0 - ninja >= 1.10.0 - docutils -- make (optional) You can optionally install `other dependencies <../README.rst#dependencies>`__, but the build system will pull in everything else you might need otherwise. @@ -44,18 +43,7 @@ your HOME directory. export TAISEI_PREFIX=/home/{your_username}/bin -To build and install Taisei on \*nix, there are two options: you can use the -``Makefile`` or you can run the commands directly, depending on your -preferences. - -To use the ``Makefile``: - -.. code:: sh - - cd taisei/ - make all # sets up, compiles, and installs Taisei - -This is equivalent to: +To build and install Taisei on \*nix: .. code:: sh @@ -77,7 +65,6 @@ Here's an explanation of what they do: on macOS) may have deprecation warnings for things not related to Taisei's code. - These commands will set up your build environment, compile the game, and install it to the ``/home/{your_username}/bin`` directory you specified earlier. You can then run the game by executing the ``taisei`` binary in that @@ -98,12 +85,6 @@ installed to ``$TAISEI_PREFIX/share/taisei/``, and this path will be built based on your own preferences. Alternatively, you can install game data relatively as well: -.. code:: sh - - make setup/install-relative - -Or: - .. code:: sh meson configure build/ -Dinstall_relative=true @@ -122,12 +103,6 @@ Debugging You can enable debugging options/output for development purposes: -.. code:: sh - - make setup/debug - -Or: - .. code:: sh meson configure build/ -Dbuildtype=debug -Db_ndebug=false @@ -138,12 +113,6 @@ Faster Builds This option also helps for speeding up build times, although there is a theoretical reduction in performance with these options: -.. code:: sh - - make setup/fastbuild - -Or: - .. code:: sh meson configure build/ -Db_lto=false -Dstrip=false @@ -155,12 +124,6 @@ For debugging actual gameplay, you can set this option and it will enable cheats and other 'fast-forward' options by the pressing keys defined in ``src/config.h``. -.. code:: sh - - make setup/developer - -Or: - .. code:: sh meson config build/ -Ddeveloper=true @@ -171,12 +134,6 @@ Stack Trace Debugging This is useful for debugging crashes in the game. It uses `AddressSanitizer `__: -.. code:: sh - - make setup/debug-asan - -Or: - .. code:: sh meson configure build/ -Db_sanitize=address,undefined @@ -208,12 +165,6 @@ OpenGL ES Support (Optional) The OpenGL ES 3.0 backend is not built by default. To enable it, do: -.. code:: sh - - make setup/gles/30 - -Or: - .. code:: sh meson configure build/ -Dr_gles30=true -Dshader_transpiler=true -Dr_default=gles30 @@ -223,12 +174,6 @@ Or: An experimental OpenGL ES 2.0 backend can be enabled similarly, using: -.. code:: sh - - make setup/gles/20 - -Or: - .. code:: sh meson configure build/ -Dr_gles20=true -Dshader_transpiler=true -Dr_default=gles20 @@ -258,14 +203,6 @@ documentation on how to do that. Once you've compiled ANGLE, enable it with: -.. code:: sh - - export LIBGLES=/path/to/libGLESv2.{dll,dylib} - export LIBEGL=/path/to/libEGL.{dll,dylib} - make setup/gles/angle - -Or: - .. code:: sh export LIBGLES=/path/to/libGLESv2.{dll,dylib} @@ -387,12 +324,6 @@ if you can't remove packages that give you errors from your system for whatever reason, you can force ``meson`` to use its built-in subprojects by using the following option: -.. code:: sh - - make setup/fallback - -Or: - .. code:: sh meson configure build/ --wrap-mode=forcefallback From efd96f33b562fe932bbf69bb9f11aaabf1b9b723 Mon Sep 17 00:00:00 2001 From: Alice D Date: Sat, 10 Jul 2021 13:46:25 -0400 Subject: [PATCH 03/10] add link to docs in main readme --- README.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 9e57d20991..bddc61144c 100644 --- a/README.rst +++ b/README.rst @@ -124,8 +124,10 @@ Taisei stores all data in a platform-specific directory: This is referred to as the **Storage Directory**. You can set the environment variable ``TAISEI_STORAGE_PATH`` to override this behaviour. -Troubleshooting ---------------- +Development & Troubleshooting +----------------------------- + +We have extended developer documentation available `here <./doc/README.rst>`__. Documentation for many topics, including development and game controller support, can be found in our `docs section <./doc/README.rst>`__. From dcfa81b0152252cb3195bb39027e667c2a6c1fc8 Mon Sep 17 00:00:00 2001 From: Alice D Date: Thu, 5 Aug 2021 14:31:57 -0400 Subject: [PATCH 04/10] fix indentation, fix links, add missing words --- doc/DEVELOPMENT.rst | 77 ++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 36 deletions(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 283b13f08a..5031c2cd83 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -1,5 +1,5 @@ -Taisei Project - Compiling FAQ -============================== +Taisei Project - Development FAQ +================================ .. contents:: @@ -16,11 +16,11 @@ Taisei's general dependencies are as follows: - C (C11) compiler (``gcc``, ``clang``, etc) - Python >= 3.5 -- meson >= 0.53.0 +- meson >= 0.53.0 (0.56.2 recommended) - ninja >= 1.10.0 - docutils -You can optionally install `other dependencies <../README.rst#dependencies>`__, +You can optionally install `other dependencies <#Platform-Specific_Tips>`__, but the build system will pull in everything else you might need otherwise. First, you'll need to checkout the repository. You can do that with the @@ -32,8 +32,9 @@ following: cd taisei/ git submodule update --init --recursive -Ensure that the ``git submodule`` or Taisei will not build, as it will be -missing many of the dependencies its needs to compile. +The ``git submodule update --init --recursive`` line is absolutely necessary, +or Taisei will not build, as it will be missing many of the dependencies its +needs to compile. Next, you'll want to set up a prefix for where the game's binaries will be installed. For starting out development, you're better off installing it to @@ -41,7 +42,12 @@ your HOME directory. .. code:: sh - export TAISEI_PREFIX=/home/{your_username}/bin + # on Linux + export TAISEI_PREFIX=/home/{your_username}/bin + + # or macOS + export TAISEI_PREFIX=/Users/{your_username}/bin + To build and install Taisei on \*nix: @@ -66,9 +72,9 @@ Here's an explanation of what they do: code. These commands will set up your build environment, compile the game, and -install it to the ``/home/{your_username}/bin`` directory you specified -earlier. You can then run the game by executing the ``taisei`` binary in that -directory (or running the ``Taisei.app`` for macOS). +install it to the ``*/bin`` directory you specified earlier. You can then run +the game by executing the ``taisei`` binary in that directory (or running the +``Taisei.app`` for macOS). Development ----------- @@ -93,10 +99,10 @@ Which will cause save game data to be installed to: .. code:: sh - $TAISEI_PREFIX/taisei/ - $TAISEI_PREFIX/data/ + $TAISEI_PREFIX/taisei/ + $TAISEI_PREFIX/data/ -Note that ``install relative`` is always set when building for Windows. +Note that ``install_relative`` is always set when building for Windows. Debugging ''''''''' @@ -115,7 +121,7 @@ theoretical reduction in performance with these options: .. code:: sh - meson configure build/ -Db_lto=false -Dstrip=false + meson configure build/ -Db_lto=false -Dstrip=false Developer Mode '''''''''''''' @@ -143,7 +149,7 @@ to use to launch ASan appropriately. Using macOS as an example: .. code:: sh - export DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib + export DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib The ``../12.0.0/..`` in the path of ``DYLD_INSERT_LIBRARIES`` changes with each version of XCode. If it fails to launch for you, ensure that the version number @@ -154,7 +160,7 @@ example): .. code:: sh - /path/to/Taisei.app/Contents/MacOS/Taisei + /path/to/Taisei.app/Contents/MacOS/Taisei OpenGL ES Support (Optional) @@ -167,7 +173,7 @@ The OpenGL ES 3.0 backend is not built by default. To enable it, do: .. code:: sh - meson configure build/ -Dr_gles30=true -Dshader_transpiler=true -Dr_default=gles30 + meson configure build/ -Dr_gles30=true -Dshader_transpiler=true -Dr_default=gles30 2.0 ''' @@ -205,9 +211,9 @@ Once you've compiled ANGLE, enable it with: .. code:: sh - export LIBGLES=/path/to/libGLESv2.{dll,dylib} - export LIBEGL=/path/to/libEGL.{dll,dylib} - meson configure build/ -Dinstall_angle=true -Dangle_libgles=$LIBGLES -Dangle_libegl=$LIBEGL + export LIBGLES=/path/to/libGLESv2.{dll,dylib} + export LIBEGL=/path/to/libEGL.{dll,dylib} + meson configure build/ -Dinstall_angle=true -Dangle_libgles=$LIBGLES -Dangle_libegl=$LIBEGL Ensure you use the correct file extension for your platform. (``.dll`` for Windows, ``.dylib`` for macOS.) @@ -243,7 +249,6 @@ In general, things like ``for`` loops should have no spaces between the ``for`` # correct for(int i = 0; i < 10; i++) { log_debug(i); } - Platform-Specific Tips ---------------------- @@ -255,15 +260,15 @@ installed: .. code:: sh - apt-get install meson cmake build-essential - apt-get install libsdl2-dev libsdl2-mixer-dev libogg-dev libopusfile-dev libpng-dev libzip-dev libx11-dev + apt-get install meson cmake build-essential + apt-get install libsdl2-dev libsdl2-mixer-dev libogg-dev libopusfile-dev libpng-dev libzip-dev libx11-dev If your distribution of Linux uses Wayland as its default window server, ensure that Wayland deps are installed: .. code:: sh - apt-get install libwayland-dev + apt-get install libwayland-dev For packaging, your best bet is ``.zip``. Invoke ``ninja`` to package a ``.zip``: @@ -279,7 +284,7 @@ On macOS, you need to begin with installing the Xcode Command Line Tools: .. code:: sh - xcode-select --install + xcode-select --install There are additional command line tools that you'll need. You can acquire those by using `Homebrew `__. @@ -289,7 +294,7 @@ tools: .. code:: sh - brew install meson cmake pkg-config docutils imagemagick pygments + brew install meson cmake pkg-config docutils imagemagick pygments The following dependencies are technically optional, and can be pulled in at build-time, but you're better off installing them yourself to reduce compile @@ -297,9 +302,9 @@ times: .. code:: sh - brew install freetype2 libzip opusfile libvorbis webp sdl2 + brew install freetype2 libzip opusfile libvorbis webp sdl2 -As of 2020-02-18, you should **not** install the following packages via +As of 2021-08-05, you should **not** install the following packages via Homebrew, as the versions available do not compile against Taisei correctly. If you're having mysterious errors, ensure that they're not installed. @@ -311,7 +316,7 @@ Remove them with: .. code:: sh - brew remove spirv-tools spirv-cross sdl2_mixer + brew remove spirv-tools spirv-cross sdl2_mixer Taisei-compatible versions are bundled and will be pulled in at compile time. @@ -334,7 +339,7 @@ you to have nicer-looking macOS ``.dmg`` files for distribution: .. code:: sh - brew install create-dmg + brew install create-dmg You can create a ``.dmg`` on either Linux or macOS (although with ``create-dmg`` on macOS, the macOS-produced ``.dmg`` will look nicer): @@ -363,8 +368,8 @@ located at ``misc/ci/windows-llvm_mingw-x86_64-build-test-ci.ini`` to go with that toolchain. In general, you'll need the following tools for compiling Taisei for Windows on Linux: -- ``llvm-mingw`` -- `nsis `__ >= 3.0 +- ``llvm-mingw`` +- `nsis `__ >= 3.0 On macOS, you're probably better off using Docker and the `Docker container `__ that @@ -391,12 +396,12 @@ You can use the macro ``attr_unused`` to bypass that warning. This: .. code:: c - int x = 0; - assert(x == 0); + int x = 0; + assert(x == 0); Becomes this: .. code:: c - attr_unused int x = 0; - assert(x == 0); + attr_unused int x = 0; + assert(x == 0); From bc3c354cda66a159846f348b30efebd963d51d42 Mon Sep 17 00:00:00 2001 From: Alice D Date: Thu, 5 Aug 2021 14:33:25 -0400 Subject: [PATCH 05/10] fix link --- doc/DEVELOPMENT.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 5031c2cd83..249bfbb3cd 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -20,7 +20,7 @@ Taisei's general dependencies are as follows: - ninja >= 1.10.0 - docutils -You can optionally install `other dependencies <#Platform-Specific_Tips>`__, +You can optionally install `other dependencies <#platform-specific-tips>`__, but the build system will pull in everything else you might need otherwise. First, you'll need to checkout the repository. You can do that with the From 42664e0a4dc307711086cfa44915c26c300aaee2 Mon Sep 17 00:00:00 2001 From: Alice D Date: Sun, 29 Aug 2021 11:44:00 -0400 Subject: [PATCH 06/10] remove duplicate sections from other PR --- doc/DEVELOPMENT.rst | 298 -------------------------------------------- 1 file changed, 298 deletions(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 249bfbb3cd..14e70af05d 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -9,218 +9,6 @@ Introduction This document contains some important tips on compiling and developing for specific platforms. -Basic Build Instructions ------------------------- - -Taisei's general dependencies are as follows: - -- C (C11) compiler (``gcc``, ``clang``, etc) -- Python >= 3.5 -- meson >= 0.53.0 (0.56.2 recommended) -- ninja >= 1.10.0 -- docutils - -You can optionally install `other dependencies <#platform-specific-tips>`__, -but the build system will pull in everything else you might need otherwise. - -First, you'll need to checkout the repository. You can do that with the -following: - -.. code:: sh - - git clone https://github.com/taisei-project/taisei.git - cd taisei/ - git submodule update --init --recursive - -The ``git submodule update --init --recursive`` line is absolutely necessary, -or Taisei will not build, as it will be missing many of the dependencies its -needs to compile. - -Next, you'll want to set up a prefix for where the game's binaries will be -installed. For starting out development, you're better off installing it to -your HOME directory. - -.. code:: sh - - # on Linux - export TAISEI_PREFIX=/home/{your_username}/bin - - # or macOS - export TAISEI_PREFIX=/Users/{your_username}/bin - - -To build and install Taisei on \*nix: - -.. code:: sh - - meson setup build/ --prefix=$TAISEI_PREFIX -Dwerror=true -Ddeprecation_warnings=no-error - meson compile -C build/ - meson install -C build/ - -There are a bunch of different arguments attached to the ``setup`` command. -Here's an explanation of what they do: - -- ``--prefix=$TAISEI_PREFIX`` installs Taisei to the prefix you specified in - the previous step. -- ``-Dwerror=true`` makes compilation **hard fail** on ``Warnings`` put out by - the compiler. This can be a bit of a pain, but a lot of the time the warnings - are there for a good reason, so we treat them as errors. As an example, it - can detect potential null-pointer errors under certain conditions. -- ``-Ddeprecation_warnings=no-error`` turns off those warnings-as-errors for - deprecation warnings specifically, as some system libraries (such as OpenGL - on macOS) may have deprecation warnings for things not related to Taisei's - code. - -These commands will set up your build environment, compile the game, and -install it to the ``*/bin`` directory you specified earlier. You can then run -the game by executing the ``taisei`` binary in that directory (or running the -``Taisei.app`` for macOS). - -Development ------------ - -Build Options -""""""""""""" - -Game Data Path -'''''''''''''' - -When compiling with ``TAISEI_PREFIX`` set, game file data will be -installed to ``$TAISEI_PREFIX/share/taisei/``, and this path will be built -*statically* into the executable. You can decide whether or not you want this -based on your own preferences. Alternatively, you can install game data -relatively as well: - -.. code:: sh - - meson configure build/ -Dinstall_relative=true - -Which will cause save game data to be installed to: - -.. code:: sh - - $TAISEI_PREFIX/taisei/ - $TAISEI_PREFIX/data/ - -Note that ``install_relative`` is always set when building for Windows. - -Debugging -''''''''' - -You can enable debugging options/output for development purposes: - -.. code:: sh - - meson configure build/ -Dbuildtype=debug -Db_ndebug=false - -Faster Builds -''''''''''''' - -This option also helps for speeding up build times, although there is a -theoretical reduction in performance with these options: - -.. code:: sh - - meson configure build/ -Db_lto=false -Dstrip=false - -Developer Mode -'''''''''''''' - -For debugging actual gameplay, you can set this option and it will enable cheats -and other 'fast-forward' options by the pressing keys defined in -``src/config.h``. - -.. code:: sh - - meson config build/ -Ddeveloper=true - -Stack Trace Debugging -''''''''''''''''''''' - -This is useful for debugging crashes in the game. It uses -`AddressSanitizer `__: - -.. code:: sh - - meson configure build/ -Db_sanitize=address,undefined - -Depending on your platform, you may need to specify the specific library binary -to use to launch ASan appropriately. Using macOS as an example: - -.. code:: sh - - export DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib - -The ``../12.0.0/..`` in the path of ``DYLD_INSERT_LIBRARIES`` changes with each -version of XCode. If it fails to launch for you, ensure that the version number -is correct by browsing to the parent directory of ``../clang``. - -Then, you can launch Taisei's binary from the command line (using macOS as an -example): - -.. code:: sh - - /path/to/Taisei.app/Contents/MacOS/Taisei - - -OpenGL ES Support (Optional) -"""""""""""""""""""""""""""" - -3.0 -''' - -The OpenGL ES 3.0 backend is not built by default. To enable it, do: - -.. code:: sh - - meson configure build/ -Dr_gles30=true -Dshader_transpiler=true -Dr_default=gles30 - -2.0 -''' - -An experimental OpenGL ES 2.0 backend can be enabled similarly, using: - -.. code:: sh - - meson configure build/ -Dr_gles20=true -Dshader_transpiler=true -Dr_default=gles20 - -However, GLES 2.0 requires a few extensions to be present on your system -to function correctly, most notably: - -- ``OES_depth_texture`` or ``GL_ANGLE_depth_texture`` -- ``OES_standard_derivatives`` -- ``OES_vertex_array_object`` -- ``EXT_frag_depth`` -- ``EXT_instanced_arrays`` or ``ANGLE_instanced_arrays`` or - ``NV_instanced_arrays`` - -ANGLE (Windows/macOS) -''''''''''''''''''''' - -ANGLE support is semi-optional for macOS, and *mandatory* for Windows. Due to -long-standing OpenGL bugs on Windows, it's required so that Taisei runs -correctly on as many GPU configurations as possible. macOS runs fine with the -standard OpenGL 3.3 backend, but requires ANGLE for GL ES 3.0 support. - -For Windows and macOS, you will need Google's ANGLE library for both ES 3.0 and -2.0. You'll need to check out -`ANGLE `__ and build it first. Refer to their -documentation on how to do that. - -Once you've compiled ANGLE, enable it with: - -.. code:: sh - - export LIBGLES=/path/to/libGLESv2.{dll,dylib} - export LIBEGL=/path/to/libEGL.{dll,dylib} - meson configure build/ -Dinstall_angle=true -Dangle_libgles=$LIBGLES -Dangle_libegl=$LIBEGL - -Ensure you use the correct file extension for your platform. (``.dll`` for -Windows, ``.dylib`` for macOS.) - -``meson`` will copy those files over into the package itself when packaging with -``ninja zip`` or ``ninja dmg``. - Coding Style ------------ @@ -252,31 +40,6 @@ In general, things like ``for`` loops should have no spaces between the ``for`` Platform-Specific Tips ---------------------- -Linux (Debian/Ubuntu) -""""""""""""""""""""" - -On an apt-based system (Debian/Ubuntu), ensure you have build dependencies -installed: - -.. code:: sh - - apt-get install meson cmake build-essential - apt-get install libsdl2-dev libsdl2-mixer-dev libogg-dev libopusfile-dev libpng-dev libzip-dev libx11-dev - -If your distribution of Linux uses Wayland as its default window server, ensure -that Wayland deps are installed: - -.. code:: sh - - apt-get install libwayland-dev - -For packaging, your best bet is ``.zip``. Invoke ``ninja`` to package a -``.zip``: - -.. code:: sh - - ninja zip -C build/ - macOS """"" @@ -289,21 +52,6 @@ On macOS, you need to begin with installing the Xcode Command Line Tools: There are additional command line tools that you'll need. You can acquire those by using `Homebrew `__. -Follow the instructions for installing Homebrew, and then install the following -tools: - -.. code:: sh - - brew install meson cmake pkg-config docutils imagemagick pygments - -The following dependencies are technically optional, and can be pulled in at -build-time, but you're better off installing them yourself to reduce compile -times: - -.. code:: sh - - brew install freetype2 libzip opusfile libvorbis webp sdl2 - As of 2021-08-05, you should **not** install the following packages via Homebrew, as the versions available do not compile against Taisei correctly. If you're having mysterious errors, ensure that they're not installed. @@ -333,52 +81,6 @@ following option: meson configure build/ --wrap-mode=forcefallback -Optionally, if you're on macOS and compiling for macOS, you can to install -`create-dmg `__, which will allow -you to have nicer-looking macOS ``.dmg`` files for distribution: - -.. code:: sh - - brew install create-dmg - -You can create a ``.dmg`` on either Linux or macOS (although with ``create-dmg`` -on macOS, the macOS-produced ``.dmg`` will look nicer): - -.. code:: sh - - ninja dmg -C build/ - -Windows -""""""" - -While the game itself officially supports Windows, building the project -directly on Windows is a bit difficult to set up due to the radically different -tooling required for a native Windows build environment. - -However, you can still compile on a Windows-based computer by leveraging Windows -10's -`Windows For Linux (WSL) Subsystem `__ -to cross-compile to Windows. Ironically enough, compiling for Windows on Linux -ends up being easier and more consistent than trying to compile with Windows's -native toolset. - -Taisei uses `mstorsjo/llvm-mingw `__ to -achieve cross-compiling on Windows. We also have a ``meson`` machine file -located at ``misc/ci/windows-llvm_mingw-x86_64-build-test-ci.ini`` to go with -that toolchain. In general, you'll need the following tools for compiling Taisei -for Windows on Linux: - -- ``llvm-mingw`` -- `nsis `__ >= 3.0 - -On macOS, you're probably better off using Docker and the -`Docker container `__ that -``llvm-mingw`` provides, and installing ``nsis`` on top of it. Refer to -``misc/ci/Dockerfile.windows`` for more insight. - -Additionally, on Windows, you'll need to make sure you have *ANGLE support* -enabled, as previously mentioned. - Compiling Issues ---------------- From bf3b3852f1abac4c4892780f0856cf5578dd1048 Mon Sep 17 00:00:00 2001 From: Alice D Date: Fri, 24 Sep 2021 13:03:27 -0400 Subject: [PATCH 07/10] add ninja upkeep section, move stuff around --- doc/DEVELOPMENT.rst | 74 +++++++++++++++++++++++++++------------------ doc/README.rst | 2 -- 2 files changed, 45 insertions(+), 31 deletions(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 14e70af05d..f077b619fa 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -6,12 +6,28 @@ Taisei Project - Development FAQ Introduction ------------ -This document contains some important tips on compiling and developing for -specific platforms. +Some development tips for working with Taisei's code. Coding Style ------------ +Upkeep Script +""""""""""""" + +``ninja`` has a function called ``upkeep`` which uses scripts found in +``taisei/scripts/upkeep/`` to check against common issues such as poor RNG use, +deprecation warnings, and other helpful code health checks. You don't have to +run it constantly, but once in a while will make sure that basic things are +more readily caught. + +It requires a setup ``build/`` directory, so make sure you've completed the basic +``meson`` setup instructions seen on the `main README `__. + +.. code:: sh + + # from the root taisei/ directory + ninja upkeep -C build/ + Tabs/Spaces """"""""""" @@ -37,6 +53,33 @@ In general, things like ``for`` loops should have no spaces between the ``for`` # correct for(int i = 0; i < 10; i++) { log_debug(i); } +Compiling Issues +---------------- + +-Wunused-variable +""""""""""""""""" + +If you get an error compiling your code, but you're 100% sure that you've +actually used the variable, chances are you're using that variable in an +``assert()`` and are compiling with ``clang``. + +``clang`` won't recognize that the variable is actually being used in an +``assert()``. + +You can use the macro ``attr_unused`` to bypass that warning. This: + +.. code:: c + + int x = 0; + assert(x == 0); + +Becomes this: + +.. code:: c + + attr_unused int x = 0; + assert(x == 0); + Platform-Specific Tips ---------------------- @@ -80,30 +123,3 @@ following option: .. code:: sh meson configure build/ --wrap-mode=forcefallback - -Compiling Issues ----------------- - --Wunused-variable -""""""""""""""""" - -If you get an error compiling your code, but you're 100% sure that you've -actually used the variable, chances are you're using that variable in an -``assert()`` and are compiling with ``clang``. - -``clang`` won't recognize that the variable is actually being used in an -``assert()``. - -You can use the macro ``attr_unused`` to bypass that warning. This: - -.. code:: c - - int x = 0; - assert(x == 0); - -Becomes this: - -.. code:: c - - attr_unused int x = 0; - assert(x == 0); diff --git a/doc/README.rst b/doc/README.rst index b380d2c270..c93d8e2957 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1,8 +1,6 @@ Taisei Project - Documentation ============================== -Here's a list of all the docs we have for working with Taisei. - Gameplay & Troubleshooting -------------------------- From 45889ee3747a1cb00e3378e468219c54cfffb51b Mon Sep 17 00:00:00 2001 From: Alice D Date: Mon, 25 Oct 2021 12:19:20 -0400 Subject: [PATCH 08/10] add ctags command --- doc/DEVELOPMENT.rst | 42 ++++++++++++++++++++++++++++++++++++++++-- meson.build | 4 ++++ 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index f077b619fa..47d27e444b 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -53,6 +53,24 @@ In general, things like ``for`` loops should have no spaces between the ``for`` # correct for(int i = 0; i < 10; i++) { log_debug(i); } +``ctags`` Support +''''''''''''''''' + +A ``.ctagsdb`` file can assist certain code editors (like ``vim``) with jump-to-definition support and other useful features. To generate a ``taisei/.ctagsdb`` file. + +.. code:: sh + + ninja ctags -C build/ + +You then have to let your editor know that a ``.ctagsdb`` file exists. + +Using ``.vimrc`` as an example: + +.. code:: sh + + # this will walk the project directory until it finds a .ctagsdb file + set tags=.ctagsdb; + Compiling Issues ---------------- @@ -86,14 +104,20 @@ Platform-Specific Tips macOS """"" +Tools +''''' + On macOS, you need to begin with installing the Xcode Command Line Tools: .. code:: sh xcode-select --install -There are additional command line tools that you'll need. You can acquire those -by using `Homebrew `__. +For other tools, such as ``meson``, you can acquire those by using +`Homebrew `__. + +Libraries +''''''''' As of 2021-08-05, you should **not** install the following packages via Homebrew, as the versions available do not compile against Taisei correctly. @@ -123,3 +147,17 @@ following option: .. code:: sh meson configure build/ --wrap-mode=forcefallback + +``ctags`` Error +''''''''''''''' + +You may run into an error when generating ``.ctagsdb`` file, such as ``illegal option -- L`` or something similar. This is because the version of ``ctags`` that ships with Xcode isn't directly supported by ``ninja``. + +You can install and alias the Homebrew version of ``ctags`` by doing the following: + +.. code:: sh + + brew install ctags + # either run this in console, or add to your shell profile + alias ctags='/usr/local/bin/ctags' + diff --git a/meson.build b/meson.build index 451b9dd3ce..07f46a4f92 100644 --- a/meson.build +++ b/meson.build @@ -513,6 +513,10 @@ foreach bindist_target : bindist_targets ) endforeach +run_target('ctags', + command : ['ctags', '-R', '--exclude=.git', '-f', '.ctagsdb', join_paths(meson.source_root(), 'src')] +) + summary = ''' Summary: From 40da1079103fe6e052188cf08c5afa48b351eee6 Mon Sep 17 00:00:00 2001 From: Alice D Date: Fri, 5 Nov 2021 19:07:53 -0400 Subject: [PATCH 09/10] remove meson ctags, as built-in one works fine, and add to gitignore --- .gitignore | 1 + doc/DEVELOPMENT.rst | 6 +++--- meson.build | 4 ---- 3 files changed, 4 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index c7c1f03304..de1454d07d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ build/ winbuild/ osxbuild/ .ctagsdb +tags .*DS_Store __pycache__ *.out diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 47d27e444b..83c97b51b1 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -56,20 +56,20 @@ In general, things like ``for`` loops should have no spaces between the ``for`` ``ctags`` Support ''''''''''''''''' -A ``.ctagsdb`` file can assist certain code editors (like ``vim``) with jump-to-definition support and other useful features. To generate a ``taisei/.ctagsdb`` file. +A ``tags`` file can assist certain code editors (like ``vim``) with jump-to-definition support and other useful features. To generate a ``taisei/tags`` file. .. code:: sh ninja ctags -C build/ -You then have to let your editor know that a ``.ctagsdb`` file exists. +You then have to let your editor know that a ``tags`` file exists. Using ``.vimrc`` as an example: .. code:: sh # this will walk the project directory until it finds a .ctagsdb file - set tags=.ctagsdb; + set tags=tags; Compiling Issues ---------------- diff --git a/meson.build b/meson.build index 07f46a4f92..451b9dd3ce 100644 --- a/meson.build +++ b/meson.build @@ -513,10 +513,6 @@ foreach bindist_target : bindist_targets ) endforeach -run_target('ctags', - command : ['ctags', '-R', '--exclude=.git', '-f', '.ctagsdb', join_paths(meson.source_root(), 'src')] -) - summary = ''' Summary: From ef776bcd1f7208635eb640c5dc76ea2a1c3d2c3c Mon Sep 17 00:00:00 2001 From: Alice D Date: Sat, 25 Dec 2021 13:06:26 -0500 Subject: [PATCH 10/10] add note about live-reloading on macOS (not finished, but presumed to be when this gets merged) --- doc/DEVELOPMENT.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/doc/DEVELOPMENT.rst b/doc/DEVELOPMENT.rst index 83c97b51b1..ff3c63b803 100644 --- a/doc/DEVELOPMENT.rst +++ b/doc/DEVELOPMENT.rst @@ -161,3 +161,38 @@ You can install and alias the Homebrew version of ``ctags`` by doing the followi # either run this in console, or add to your shell profile alias ctags='/usr/local/bin/ctags' +Live Resource Reloading (macOS) +''''''''''''''''''''''''''''''' + +The required library for live resource reloading of shaders, etc., known as +``libinotify``, is available natively on Linux, but macOS requires a +third-party driver to gain ths same functionality. + +In order to use live resource reloading on macOS, you'll need to download, +build, and install +`libinotify-kqueue `__ +onto your system. + +Once that's done, you'll also need to boost the limit on open file handlers. +This is due to an OS-level limit on how many files an application can open at a +single time, and Taisei keeps many files open for monitoring with +live-reloading enabled. + +⚠️ **In summary, if you run into an error of ``Too many open files``,** you'll +need to fix it using this command: + +.. code:: sh + # '1024' is a reasonable boost from macOS's default of `256` + # but it can also be any number you want + ulimit -n 1024 + +This is not a system-wide or permanent setting, and will need to be executed on +every shell you start. The simplest way to do this is to add the above command +to your ``~/.zshrc`` or ``~/.bashrc`` depending on what shell you use. (The +default on modern macOS is ``zsh``.) You can check the status of the limit with: + +.. code:: sh + # this should output `1024` if everything worked + ulimit -n + > 1024 +