add submodule helper scripts, update readme

README.rst

@@ -6,9 +6,8 @@ Taisei
 Introduction
 ------------
 
-Taisei is an open clone of the Tōhō Project series. Tōhō is a one-man
-project of shoot-em-up games set in an isolated world full of Japanese
-folklore.
+Taisei is an open clone of the Tōhō Project series. Tōhō is a one-man project of
+shoot-em-up games set in an isolated world full of Japanese folklore.
 
 Installation
 ------------
@@ -34,17 +33,49 @@ Optional:
 Build-only dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^
 
--  Python >= 3.4
--  meson >= 0.45.0 (build system)
+-  Python >= 3.5
+-  meson >= 0.45.0 (build system; >=0.48.0 recommended)
 
 Optional:
 
 -  docutils (for documentation)
 
-To build and install Taisei just follow these steps.
+Obtaining the source code
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stable releases
+"""""""""""""""
+
+You can find the source tarballs at the
+`Releases <https://github.com/taisei-project/taisei/releases>`__ section on
+Github. **Do not** grab Github's auto-generated source archives, those do not
+contain the required submodules. This only applies for versions v1.3 and above.
+
+Latest code from git
+""""""""""""""""""""
+
+If you cloned Taisei from git, make sure the submodules are initialized:
+
+::
+
+    git submodule init
+    git submodule update
+
+This step needs to be done just once, and can be skipped if you specified the
+``--recursive`` or ``--recurse-submodules`` option when cloning.
+
+**Important:** You should also run ``git submodule update`` whenever you pull in
+new code, checkout another branch, etc. The ``pull`` and ``checkout`` helper
+scripts can do that for you automatically.
+
+Compiling from source
+^^^^^^^^^^^^^^^^^^^^^
+
+To build and install Taisei on \*nix, just follow these steps:
 
 ::
 
+    cd /path/to/taisei/source
     mkdir build
     cd build
     meson --prefix=$yourprefix ..
@@ -89,18 +120,17 @@ Taisei stores all data in a platform-specific directory:
 -  On **Linux**, **\*BSD**, and most other **Unix**-like systems, it's
    ``$XDG_DATA_HOME/taisei`` or ``$HOME/.local/share/taisei``
 
-This is referred to as the **Storage Directory**. You can set the
-environment variable ``TAISEI_STORAGE_PATH`` to override this behaviour.
+This is referred to as the **Storage Directory**. You can set the environment
+variable ``TAISEI_STORAGE_PATH`` to override this behaviour.
 
 Game controller support
 -----------------------
 
-Taisei uses SDL2's unified GameController API. This allows us to
-correctly support any device that SDL recognizes by default, while
-treating all of them the same way. This also means that if your device
-is not supported by SDL, you will not be able to use it unless you
-provide a custom mapping. If your controller is listed in the settings
-menu, then you're fine. If not, read on.
+Taisei uses SDL2's unified GameController API. This allows us to correctly
+support any device that SDL recognizes by default, while treating all of them
+the same way. This also means that if your device is not supported by SDL, you
+will not be able to use it unless you provide a custom mapping. If your
+controller is listed in the settings menu, then you're fine. If not, read on.
 
 An example mapping string looks like this:
 
@@ -111,63 +141,62 @@ An example mapping string looks like this:
 There are a few ways to generate a custom mapping:
 
 -  You can use the
-   `controllermap <https://aur.archlinux.org/packages/controllermap>`__
-   utility, which `comes with SDL source
-   code <https://hg.libsdl.org/SDL/file/68a767ae3a88/test/controllermap.c>`__.
--  If you use Steam, you can configure your controller there. Then you
-   can add Taisei as a non-Steam game; run it from Steam and everything
-   should *just work™*. In case you don't want to do that, find
-   ``config/config.vdf`` in your Steam installation directory, and look
-   for the ``SDL_GamepadBind`` variable. It contains a list of SDL
-   mappings separated by line breaks.
--  You can also try the `SDL2 Gamepad Tool by General
-   Arcade <http://www.generalarcade.com/gamepadtool/>`__. This program
-   is free to use, but not open source.
--  Finally, you can try to write a mapping by hand. You will probably
-   have to refer to the SDL documentation. See
-   `gamecontrollerdb.txt <misc/gamecontrollerdb/gamecontrollerdb.txt>`__
-   for some more examples.
+   `controllermap <https://aur.archlinux.org/packages/controllermap>`__ utility,
+   which `comes with SDL source code
+   <https://hg.libsdl.org/SDL/file/68a767ae3a88/test/controllermap.c>`__.
+-  If you use Steam, you can configure your controller there. Then you can add
+   Taisei as a non-Steam game; run it from Steam and everything should *just
+   work™*. In case you don't want to do that, find ``config/config.vdf`` in your
+   Steam installation directory, and look for the ``SDL_GamepadBind`` variable.
+   It contains a list of SDL mappings separated by line breaks.
+-  You can also try the `SDL2 Gamepad Tool by General Arcade
+   <http://www.generalarcade.com/gamepadtool/>`__. This program is free to use,
+   but not open source.
+-  Finally, you can try to write a mapping by hand. You will probably have to
+   refer to the SDL documentation. See `gamecontrollerdb.txt
+   <misc/gamecontrollerdb/gamecontrollerdb.txt>`__ for some more examples.
 
 Once you have your mapping, there are two ways to make Taisei use it:
 
--  Create a file named ``gamecontrollerdb.txt`` where your config,
-   replays and screenshots are, and put each mapping on a new line.
--  Put your mappings in the environment variable
-   ``SDL_GAMECONTROLLERCONFIG``, also separated by line breaks. Other
-   games that use the GameController API will also pick them up.
+-  Create a file named ``gamecontrollerdb.txt`` where your config, replays and
+   screenshots are, and put each mapping on a new line.
+-  Put your mappings in the environment variable ``SDL_GAMECONTROLLERCONFIG``,
+   also separated by line breaks. Other games that use the GameController API
+   will also pick them up.
 
 When you're done, please consider contributing your mappings to
 `SDL <https://libsdl.org/>`__,
 `SDL_GameControllerDB <https://github.com/gabomdq/SDL_GameControllerDB>`__,
 and `us <https://github.com/taisei-project/SDL_GameControllerDB>`__, so
 that other people can benefit from your work.
 
-Also note that we currently only handle input from analog axes and
-digital buttons. Hats, analog buttons, and anything more exotic will not
-work, unless remapped.
+Also note that we currently only handle input from analog axes and digital
+buttons. Hats, analog buttons, and anything more exotic will not work, unless
+remapped.
 
 Troubleshooting
 ---------------
 
 Sound problems (Linux)
 ^^^^^^^^^^^^^^^^^^^^^^
 
-If your sound becomes glitchy, and you encounter lot of console messages
-like:
+If your sound becomes glitchy, and you encounter lot of console messages like:
 
 ::
 
     ALSA lib pcm.c:7234:(snd_pcm_recover) underrun occurred
 
-it seems like you possibly have broken ALSA configuration. This may be
-fixed by playing with parameter values of ``pcm.dmixer.slave`` option
-group in ``/etc/asound.conf`` or wherever you have your ALSA
-configuration. Commenting ``period_time``, ``period_size``,
-``buffer_size``, ``rate`` may give you the first approach to what to do.
+it seems like you possibly have broken ALSA configuration. This may be fixed by
+playing with parameter values of ``pcm.dmixer.slave`` option group in
+``/etc/asound.conf`` or wherever you have your ALSA configuration.
+Commenting ``period_time``, ``period_size``, ``buffer_size``, ``rate`` may give
+you the first approach to what to do.
 
 Contact
 -------
 
-http://taisei-project.org/
+-  https://taisei-project.org/
+
+-  `#taisei-project on Freenode <irc://irc.freenode.org/taisei-project>`__
 
-#taisei-project on Freenode
+-  `Our server on Discord <https://discord.gg/JEHCMzW>`__

checkout

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+git checkout "$@" && git submodule update

external/meson.build

@@ -3,4 +3,3 @@ install_data(
     join_paths('gamecontrollerdb', 'gamecontrollerdb.txt'),
     install_dir : data_path
 )
-

meson.build

@@ -77,6 +77,18 @@ foreach arglist : [
     endif
 endforeach
 
+sm_check = run_command(check_submodules_command)
+
+if sm_check.stdout() != ''
+    foreach line : sm_check.stdout().strip().split('\n')
+        warning(line)
+    endforeach
+endif
+
+if sm_check.stderr() != ''
+    warning('Submodule check completed with errors:\n@0@'.format(sm_check.stderr()))
+endif
+
 static = get_option('static')
 
 dep_freetype    = dependency('freetype2',                           required : true,  static : static)
@@ -308,3 +320,5 @@ subdir('atlas')
 subdir('src')
 
 message(summary)
+
+run_command(postconf_command)

pull

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+git pull "$@" && git submodule update

scripts/check-submodules.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+
+from taiseilib.common import (
+    run_main,
+)
+
+import subprocess
+import pathlib
+import sys
+import re
+import os
+
+
+submodule_regex = re.compile('^.[0-9a-f]*? ([^ ]*)(?: .*?)?')
+
+
+def handle_no_git():
+    # TODO
+    pass
+
+
+def main(args):
+    try:
+        p = subprocess.run(['git', 'submodule', 'status'],
+            cwd=os.environ.get('MESON_SOURCE_ROOT', pathlib.Path(__file__).parent),
+            capture_output=True,
+            universal_newlines=True
+        )
+    except FileNotFoundError:
+        return handle_no_git()
+
+    if p.returncode != 0:
+        if p.stderr.startswith('fatal: not a git repository'):
+            return handle_no_git()
+
+        print('Git error:', p.stderr.strip(), file=sys.stderr)
+        exit(1)
+
+    for module in p.stdout.rstrip('\n').split('\n'):
+        status = module[0]
+
+        if status != ' ':
+            match = submodule_regex.match(module)
+
+            try:
+                path = match[1]
+            except TypeError:
+                print('Failed to parse submodule: {0}'.format(module))
+                continue
+
+            if status == '+':
+                print('Submodule `{0}` is not in sync with HEAD. Run `git submodule update` if this is not intended.'.format(path))
+            elif status == '-':
+                print('Submodule `{0}` is not initialized. Run `git submodule update --init` if this is not intended.'.format(path))
+            elif status == 'U':
+                print('Submodule `{0}` has unresolved conflicts.'.format(path))
+            else:
+                print('Status of submodule `{0}` is unknown: {1}'.format(path, module))
+
+
+if __name__ == '__main__':
+    run_main(main)

scripts/meson.build

@@ -115,10 +115,13 @@ upkeep_command = [python_thunk, upkeep_script, common_taiseilib_args]
 upkeep_target = run_target('upkeep', command: upkeep_command)
 
 postconf_script = files('dump-build-options.py')
-run_command(python_thunk, postconf_script)
+postconf_command = [python_thunk, postconf_script]
 
 pack_script = files('pack.py')
 pack_command = [python_thunk, pack_script, common_taiseilib_args]
 
 glob_script = files('glob-search.py')
 glob_command = [python_thunk, glob_script]
+
+check_submodules_script = files('check-submodules.py')
+check_submodules_command = [python_thunk, check_submodules_script]