README.dev

This file is intended for developers wishing to run/inspect/modify Trelby
using the source code and is not intended for end users using a released package.

1. Requirements
===============

To build and run Trelby, you will need Python (2.6 or 2.7) and wxWidgets (2.8)
and its Python bindings. You also need the lxml Python library (http://lxml.de/).

To build the manual, you will also need xsltproc and docbook-xsl.

2. Preparing data files
=======================

Trelby needs special preparation for three of its data files. If you do not do
this, that aspect of the program will not work.

 * Name list

  $ make names.txt.gz

 * Dictionary

  $ make dict_en.dat.gz

 * Manual

  $ make manual.html

You can run "make dist", which prepares all 3 and also generates a Linux
distribution package which you can ignore.

2.5. Preparing for a Windows build
==================================

If you want to create the Windows package, you'll need to place the
Windows redistributable runtime file vcredist_x86.exe in the trelby
directory.

Be sure to have the following installed:

 * python-2.7.2.msi
  - py2exe-0.6.9.win32-py2.7.exe
  - wxPython2.8-win32-unicode-2.8.12.1-py27.exe
  - nsis-2.46-setup.exe
  - lxml-2.3.win32-py2.7.exe
  - pycrypto exe

Install vcredist_x86.exe locally. On Win Vista/7, msvcp90.dll will not be
under windows/system32, but under windows/winsxs. Hunt this file down,
and copy it over to system32. This just causes duplication, nothing else,
but is required so nsis won't complain about a missing DLL.

Finally ensure you had run make dist in the directory on a linux machine,
so all files are in place. (and ensure vcredist_x86.exe is here as well)

Then, on Windows, to create the installer:

1) cd <trelby directory>
2) build.bat

Your freshly created Setup-Trelby-<version>.exe should be ready.


2.7. Preparing for a Mac OS X build
==================================

Building Trelby.app for MacOS X requires the following:

*  MacOS X -- Versions 10.6.x - 10.8.x have been tested and are known to work
*  XCode --  Use the latest.  You can also install a non-Apple toolchain from
   https://github.com/kennethreitz/osx-gcc-installer
*  Python 2.7.x -- http://www.python.org/download/releases/2.7.3/ (or latest)
*  A recent version of lxml - see http://lxml.de/  Best to build this from source
   using "python setup.py build --static-deps".  See the site for more details.
*  py2app -- http://packages.python.org/py2app/
*  wxPython 2.9 -- http://wxpython.org/download.php#stable
   Make sure you get the cocoa version, which requires Python 2.7 or higher
*  To build the manual, you will need docbook-xsl and xsltproc, which you can install
   using Mac Ports ( www.macports.org )

Once you've installed the above, do this from the root source directory:

make dist-osx

The above command should cause Trelby.app to appear in a "dist" subdirectory.  Or do:

make install-osx

The results of the above command should install Trelby.app to the /Applications directory
and create a folder on your Desktop with supporting documents as well as a symlink.

3. Running Trelby in test mode
==============================

On Linux:

 $ cd ~/trelby/
 $ bin/trelby --test

On Windows:

 $ cd \trelby
 $ python bin/trelby --test sample.trelby

 The file t.bat contains the last command.

4. Differences from packaged versions
=====================================

The "--test" command line argument makes Trelby differ from normal running
as follows:

 -No splash window is displayed on startup.

 -No global directory locations are used; configuration/state files
 instead go under ".trelby" in the current directory.

 -The following characters activate special behavior:

  -"å": Load "sample.trelby".

  -"¤": Call function MyCtrl.cmdTest.

  -"½": Run speed tests.

   (The above characters are in the ISO-8859-1 character set.)