repos/MysteryMachine
view README @ 313:d7591777a9f6
New installer,README and version bump for 0.14
| author | Roger Gammans <rgammans@computer-surgery.co.uk> |
|---|---|
| date | Thu Apr 07 20:53:16 2011 +0100 (13 months ago) |
| parents | 28020e2320b9 |
| children | 131e18250f7b |
line source
1 Installation
2 ============
4 If you are installing from a built source distribution then the command:-
6 python setup.py install -d <DirectoryToInstallInto>
8 should work, if you have python virtualenv and setuptools already installed, and
9 windows users should see the note under pyparsing below.
11 This will create a python virtualenv in the specified installation directory and
12 install MysteryMachine, a customised yapsy plus all of the dependencies into to
13 it.
15 You can still install MysteryMachine into you global environment if you don't have
16 or want to install virtualenv by running
18 python setup.py install_here
20 instead.
22 If you are installing from the mercurial repo you need the following libraries
23 on your PYTHONPATH. Once the libraries below and MysteryMachine itself are on your
24 python path the scripts in the 'scripts' directory should work. Or you can install
25 a patched version of yapsy (patch is in the patches directory) and paver then use:-
27 paver sdist
29 to build you own source distribution and install from that.
31 You will also find it useful to install wxPython and mercurial (at least 1.3)
32 seperately . Similiary bpython is recommended for cli affiondadios on platforms
33 which support it.
36 Windows Install Quick Reference
37 -------------------------------
39 To install on windows I suggest the following commands, if you use python for
40 other applications want more control I suggest you read all of this README before
41 doing this
43 1. Download a recent Python (2.6.x is recommended) from www.python.org and install it.
44 2. Download a recent wxPython (2.8.10 is recommoned) from www.wxpython.org and install it.
45 3. Download mercurial from http://bitbucket.org/tortoisehg/thg-winbuild/downloads/ and install it.
46 4. From the MysteryMachine zip file run
47 python setup.py install -d c:\mysterymachine
49 5 Add a Link to the mmcli.exe and mmwx.exe scripts to your Start Menu.
52 Installation on Debian/Unbuntu
53 ------------------------------
55 1. Run 'aptitude install python2.6 python-wxgtk2.8 mercurial'
56 2. From the MysteryMachine zip file run
57 python setup.py install -d /opt/mysterymachine
59 3 Add a Link to the /opt/mysterynachine/mmcli and /opt/mysterymachine/binmmwx
60 to your desktop
63 Libraries Required
64 ------------------
66 You will need to install the following Python packages to use the
67 MysteryMachine .
69 pyparsing > 1.5.0
70 mercurial > 1.3.1
72 Yapsy
73 '''''
74 Yapsy does not currently meet our python3 or other requirements.
76 MysteryMachine ships with a patched version of Yapsy which should
77 be backwardly compatible with 1.7 - but adds a filter mechanism which is currently
78 used so we ignore UnTrusted plugins.
80 Pyparsing
81 '''''''''
83 Actually you may be able to make MysteryMachine work with Pyparsing 1.4, and the
84 parser was orginally written for it.
85 However the whitespace handling code is different between the two releases and 1.4
86 may damage rst documents when used with the settings required for 1.5.
88 Also Pyparsing 1.4 did not throw and exception if it couldn't parse the whole string
89 it would just silently discard the remaining output. SO don't blame me if you
90 attempt to use it with and early version and find your mssing half your character sheet.
92 The automatic setup will try to copy install the current version of pyparsing
93 from my development environment into MysteryMachine's library if you haven't
94 already got a global copy.
96 Mercurial
97 '''''''''
98 MysteryMachine needs to be able to use Mercurial as a library , on a POSIX
99 OS (Linux & MacOs) just installing mercurial asa system applciation should be
100 enough , but on windows you will need to ensure it is install as a python library,
101 if this doesn't work, `easy_install mercurial` will download it for you but
102 it require python2.X-dev and working C toolchain installed . But that is quite
103 common on Unix machines.
105 I haven't yet worked out the best to get Mercurial installed automatically on windows,
106 due to the common lack of Visual Studio , which is required to build the C extension
107 parts. However a binary version which can be used a a library can be downloaded from
108 http://bitbucket.org/tortoisehg/thg-winbuild/downloads/
111 Bpython
112 '''''''
113 This package os no longer considerer required as it doesn't work on windows,
114 however it is recommended on those platforms where it does work.
116 Use easy_install or your OS package manager
117 to install it. If it ia not already installed the installer will try to fetch and
118 install it automatically.
120 Docutils
121 ''''''''
122 MysteryMachine was first developed with docutils 0.4 but I'm currently using 0.6 myself
123 as it generates less noise of on the python comaptiblity tests. I suspect 0.5 and 0.6 should
124 work equally. 0.4 will probably work too but I haven't tested it in a while.
126 Docutils can either be installed wiht easy_install or the installer will pull in the
127 latest version for you.
129 PyYaml
130 ''''''
131 Yaml is the current prefered format for the MysteryMachine config file , and if you
132 intend to start MysteryMachine with it default settings it will need PyYaml.
133 PyYaml can be install easily using easy_install. Like so:
134 easy_install pyyaml
136 But it should pulled in with the installer.
139 Tkinter & Tcl/Tk
140 ''''''''''''''''
141 These are only require for the Idle based Ui, but currently the installer doesn't
142 setup the tcl/tk environment correctly (see https://bitbucket.org/ianb/virtualenv/issue/40/tkinter-fails-in-a-virtual-env )
143 to fix this you need ensure the TCL_LIBARRY environmenr variable point to the TCL script
144 and srtart up files. The easiest way to do this is to add a line to your
145 activate.bat which set this varaibell to pint to the tcl directories tghat ship with
146 python.
148 Running MysteryMachine
149 ======================
151 Running:-
153 mmcli
155 will start the default MysteryMachine API cli for your platform.
157 Mystery machine has a two Cli ui's at the moment which dumps you at the
158 python shell with the global 'ctx' bound to MysteryMachine Library.
160 The are basically identical, the primary one is base on bpython and can
161 be started like this:
163 mysterymachine --ui=Ui.cli.BPython
165 Bpython support auto completion and help pop-up documentation. The
166 down side of Bpython is that it requires a Unix (or unix-like) terminal
167 to run in, so is not compatible with windows.
169 For windows , althought it shoulkd work anywhere that has python there is
170 an alternative Ui based on the Idle development environment, this
171 Ui can be started like this:-
173 mysterymachine --ui=Ui.cli.Idle
175 Similiarily this supports auto-completion and pop-up documentation but
176 where as Bpython will show the complete docstring, Idle tries to
177 shorten it.
180 GUI
181 '''
183 Your more likely to be interested in running the New MysteryMachine GUI
184 and this can be starting by running the mmwx binary from either the bin
185 or scripts directory depending on your platform.