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, 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 use that instead of python.
Installing the 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.
- A reasonably recent Mercurial version, either
- Python 3.3 from http://python.org/download/releases/3.3.2/ (for Windows, use the .MSI installer)
Python version note
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, 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).
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.
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 venv name>
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, 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:
- Scripts\activate.bat on Windows, or
- source bin/activate on unix-like systems.
While the environment is active, you should see a (ttgx) in front of the prompt. You are now in an isolated environment and can proceed without affecting Python code run outside of the environment. 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.
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 xfish/main.py. There's two other things you may want to run:
There are also unit tests for some (but 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 kill time and assure quality.
Should your setup be broken, you may get SyntaxErrors or ImportErrors, titled "ERROR collecting test_foo.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 by mkenv.py.