Commits

rkruppe committed b9254ca

Overhaul and shrink README

  • Participants
  • Parent commits 79c0bb2

Comments (0)

Files changed (1)

-=========================
-Development Version Guide
-=========================
+============
+Tutagx/XFish
+============
 
-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``.
 
 Software Requirements
 ---------------------
-Installing following software is required to run development versions of this application directly.
+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.
 
   - 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)
 
 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, 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).
 
 Using ``mkenv.py``
 ------------------
-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 ttgx
+    python mkenv.py <the venv name>
 
-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``.
 
 .. WARNING::
-    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`_.
-
-Getting The Code
-----------------
-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...".
-
-Libraries
----------
-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 ``ttgx/demo.py``.
+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 (though not all) parts of the code base.
+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 spend time.
+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_xy.py".
+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 through ``requirements.txt``.
+That program was already installed by ``mkenv.py``.