-Development Version Guide
-The following document provides step-by-step instructions on getting a development environment up and running.
-Most of it requires some command line work.
-There is a script in this repository which does most of the same work.
+This document provides step-by-step instructions on getting a development environment up and running.
+Most of it requires some command line work, CLI commands are typeset ``like this``.
+A script in this repository does most of the work, you just need to install the software requirements and run this script.
You can download it from https://bitbucket.org/rkruppe/tutagx/raw/default/mkenv.py after installing the software requirements.
-It creates the virtual environment (the section also describes how to use it, so don't skim it).
-It installs required Python libraries, checks out the source code, re-creates the preferred directory layout, and does some sanity checks.
+It creates the virtual environment, installs required libraries, checks out the source code, and does some sanity checks.
We'll assume the Python 3.3 executable is called ``python``.
-If you're on a system that calls Python 3.3 ``python3.3`` (such as most linux distributions), you should
probably use that instead of ``python``.
+If you're on a system that calls Python 3.3 ``python3.3`` (such as most linux distributions), you should use that instead of ``python``.
-Installing following software is required to run development versions of this application directly.
+Installing following software is required to run development versions of this application directly.
Of course, everything you already have installed needn't be installed again.
If you're on a Linux system, you should obviously check your package manager before using the links below.
- The command-line tool directly from http://mercurial.selenic.com/
- The GUI + shell integration (Windows only) from http://tortoisehg.bitbucket.org/
-- Python 3.3 from http://python.org/download/releases/3.3.0/ (for Windows, use the .MSI installer)
-- ImageMagick (the command line tool, not one of the Python bindings): http://www.imagemagick.org/script/binary-releases.php
+- Python 3.3 from http://python.org/download/releases/3.3.2/ (for Windows, use the .MSI installer)
Under Windows, multiple installs of (distinct versions of) Python clash in some non-vital areas.
Most notably, the executables have the same names, so you can only invoke one from the command line.
Take care if you have Python 2.x installed.
-Older 3.x versions should be fine to replace, there's backwards compability.
-Just make sure you use 3.3 for running all of the following.
-Next up, either use ``mkenv.py`` (recommended), or skip to `Getting The Code`_ (if you want to do it manually).
+Older 3.x versions should be fine to replace, newer 3.x versions are backwards compatible to them.
+Just make sure you use 3.3 for running all of the following (mkenv.py will error out instantly if you don't).
-For sanity and to avoid various kinds of messes, the entire game should be kept in a so-called "virtual environment".
-This allows keeping libraries isolated, and avoids accessing system-wide files.
+To avoid various kinds of messes, the entire game should be kept in a so-called "virtual environment", venv for short.
+A venv is primarily a directory with its own set of Python binaries, tools and libraries that is isolated from the system-wide install.
+It can be *activated* in a command line session and replace the system Python for this session; otherwise it doesn't interfere with the rest of the system.
+This allows keeping a project and its dependencies isolated, and avoids unnecessary system-wide installations.
It's even more useful if you actually have several Python projects with incompatible dependencies around.
-But in any case, it simplifies getting started and with the ``mkenv.py`` script it's actually easier than the wrong way.
-Python 3.3 (but no earlier version) has this built in, with the "venv" module.
-We wrap it to do the numerous customization (package managers, libraries, directory layout, etc.) we need.
-In effect, you should only need to download https://bitbucket.org/rkruppe/tutagx/raw/default/mkenv.py to the directory where the virtualenv should live and run::
+Download https://bitbucket.org/rkruppe/tutagx/raw/default/mkenv.py to the directory where the venv should live.
+Decide what to call the venv, make sure that directory doesn't exist yet, and run::
+ python mkenv.py
-The environment's name (here, ``ttgx``) doesn't matter, and it can be almost anywhere you like.
-Putting it into the installation directory of Python does *not* work.
+The environment's name doesn't matter, and it can be almost anywhere you like.
+Putting it into the installation directory of Python does *not* work though.
+We'll assume the venv is called ``ttgx``.
- A venv is practically impossible to rename/relocate.
- As re-creation can several minutes minutes (it does on my computer), think well when choosing a location.
+ A venv is practically impossible to rename/relocate, think well when choosing a location.
+ If you need to move it, it's easier and less error prone to just re-create it.
Now switch into the ttgx directory.
To actually "activate" the environment, run either:
**Both "python" and "python3.3" should now refer to the venv's installation, not to the system-wide one.**
You can exit the environment via ``deactivate``.
-You're not all set up to start `Actually Running Anything`_.
-The files you'll need are split into two repositories:
-- the source code of the game engine
-- the "default" gameset, including some assets
-For the preferred directory layout, place the checkouts like this::
- https://bitbucket.org/rkruppe/tutagx -> tutagx/
- https://bitbucket.org/rkruppe/tutagx-default-gameset -> gamesets/default/
-The target directory names (the latter part) are chosen to fit the default config.yaml, but you can change them to your liking.
-You'd have to adjust ``tutagx/config.yaml`` though, and maintain it on your own.
-In any case, you'll have to prepare the assets, as only the high-resolution source files are stored in mercurial.
-Enter the gameset directory and run ``make.py build``.
-TortoiseHg's shell extensions offer the same feature under the same name.
-Search the context menu for "Clone...".
-There is a file ``requirements.txt`` in the repository which should include all python libraries used, including exact versions.
-Should you find that a library is missing, or the version listed doesn't work, please report it.
-Using ``pip``, all the libraries can be installed with one command::
- pip install --upgrade -r requirements.txt
-The ``--upgrade`` flag forces a fresh install of libraries that happen to be installed already.
-It's recommended as it ensures you've got the right version.
Actually Running Anything
To make sure PYTHONPATH is correct, you may want to run pythonpath.sh/.bat every time you start a new terminal (ideally, immediately after issuing ``activate``).
Note that on Linux, you have to ``source`` the script, i.e., run it in the same way you run ``activate``.
-The main game, insofar it exists, is run through ``
+The main game, insofar it exists, is run through ``.py``.
There's two other things you may want to run:
-There are also unit tests for some (
though not all) parts of the code base.
+There are also unit tests for some ( not all) parts of the code base.
Running them can give a bit of confidence that nothing's broken about your setup.
-For developers, writing new and extending existing tests is a good way to
+For developers, writing new and extending existing tests is a good way to .
-Should your setup be broken, you may get SyntaxErrors or ImportErrors, titled "ERROR collecting test_
+Should your setup be broken, you may get SyntaxErrors or ImportErrors, titled "ERROR collecting test_.py".
Should the current source code be broken, you might get similar errors, or merely failed tests.
To run the unit tests, simply issue the command ``py.test`` at the project root directory.
-That program was already installed
+That program was already installed ``.