[e7839be] | 1 | <HTML><HEAD> |
---|
| 2 | <TITLE>Survex Hacker's Guide</TITLE> |
---|
| 3 | <STYLE type="text/css"><!-- |
---|
| 4 | BODY, TD, CENTER, UL, OL {font-family: sans-serif;} |
---|
| 5 | --> |
---|
| 6 | </STYLE> |
---|
| 7 | </HEAD><BODY BGCOLOR=white TEXT=black> |
---|
| 8 | <H1>Hacking Survex</H1> |
---|
| 9 | |
---|
| 10 | <p>(That's hacking in the "tinkering with code" sense, not in the |
---|
| 11 | "breaking into other people's computer systems" sense). |
---|
| 12 | |
---|
| 13 | <p>This is currently a random collection of notes that need to be written |
---|
| 14 | down while I remember. With time it should evolve into a more |
---|
| 15 | coherent document. If you have any questions which this should answer |
---|
| 16 | but doesn't then ask me and I'll add them. |
---|
| 17 | |
---|
| 18 | <H2>Network code debugging</H2> |
---|
| 19 | |
---|
| 20 | <P>You can pick which network simplifications are attempted using "-z" |
---|
| 21 | with an argument listing code letters. So: |
---|
| 22 | |
---|
| 23 | <ul> |
---|
| 24 | <li>-z= no special simplifications (articulation still performed) |
---|
| 25 | <li>-z=l remove "lollipops" |
---|
| 26 | <li>-z=p remove parallel legs |
---|
| 27 | <li>-z=d convert deltas to stars |
---|
| 28 | </ul> |
---|
| 29 | |
---|
| 30 | <P>And you can combine these in any combination: |
---|
| 31 | |
---|
| 32 | <ul> |
---|
| 33 | <li>-z=lp remove "lollipops" and parallel legs |
---|
| 34 | <li>-z=lpd remove "lollipops" and parallel legs; convert deltas to stars |
---|
| 35 | </ul> |
---|
| 36 | |
---|
| 37 | <P>"-z=lpd" is the default (in 0.99 at least - more transformations may |
---|
| 38 | conceivably be added in future, although the simple common cases are |
---|
| 39 | already covered). |
---|
| 40 | |
---|
| 41 | <H2>Developing on Unix Platforms</H2> |
---|
| 42 | |
---|
[b63c928d] | 43 | <P>You'll need automake 1.5 or later (earlier versions don't support |
---|
[61b4202] | 44 | per-executable CFLAGS; 1.6 has been tested and works, but wasn't a |
---|
| 45 | very stable release - automake 1.6.1 is a better bet) |
---|
[e7c04bc] | 46 | and autoconf 2.50 or later (autoconf 2.52, 2.53 and 2.64 have all |
---|
| 47 | been used successfully). |
---|
[c372fc9] | 48 | |
---|
| 49 | <P>For building the documentation you'll need sgmltools 2 or later, |
---|
[e7c04bc] | 50 | jadetex, docbook-to-man, and w3m. |
---|
[e7839be] | 51 | |
---|
[089bf7d] | 52 | <P>On debian squeeze: sudo apt-get install sgmltools-lite jadetex docbook-to-man w3m |
---|
| 53 | |
---|
[e7839be] | 54 | <H2>Building on Non-Unix Platforms</H2> |
---|
| 55 | |
---|
| 56 | <H3>DJGPP (MSDOS for 386 or better)</H3> |
---|
| 57 | |
---|
| 58 | <P>Currently I build this with a Linux hosted cross-compiler. I built |
---|
| 59 | this myself mostly following instructions from: |
---|
| 60 | |
---|
| 61 | <P><A |
---|
| 62 | HREF="http://www.objsw.com/CrossGCC/">http://www.objsw.com/CrossGCC/</A> |
---|
| 63 | |
---|
[e364af7] | 64 | <P>I suggest using binutils-2.14 rather than binutils-2.9.1, and also newer |
---|
| 65 | version of the DJGPP crosscompiler kit (djcrx - use 204 which is in beta at |
---|
| 66 | the time of writing) and GCC. Newer binutils versions include the patch they |
---|
| 67 | supply, so the instructions boil down to this sequence of commands: |
---|
[e7839be] | 68 | |
---|
| 69 | <pre> |
---|
| 70 | bash |
---|
| 71 | mkdir ~/djcross |
---|
| 72 | cd ~/djcross |
---|
| 73 | wget ftp://ftp.objsw.com/pub/crossgcc/build-djgpp.sh |
---|
| 74 | mkdir tars |
---|
| 75 | cd tars |
---|
[e364af7] | 76 | wget http://www.mirror.ac.uk/sites/ftp.delorie.com/pub/djgpp/current/v2/beta/djcrx204.zip |
---|
| 77 | wget http://www.mirror.ac.uk/sites/ftp.gnu.org/gnu/gcc/gcc-3.3.2.tar.gz |
---|
| 78 | wget http://www.mirror.ac.uk/sites/ftp.gnu.org/gnu/binutils/binutils-2.14.tar.gz |
---|
[e7839be] | 79 | cd .. |
---|
| 80 | patch -l build-djgpp.sh <<END |
---|
[e364af7] | 81 | 24,26c24,26 |
---|
| 82 | < binfile=djcrx202.zip |
---|
| 83 | < gcc=gcc-2.95.2 |
---|
[e7839be] | 84 | < binutils=binutils-2.9.1 |
---|
| 85 | --- |
---|
[e364af7] | 86 | > binfile=djcrx204.zip |
---|
| 87 | > gcc=gcc-3.3.2 |
---|
| 88 | > binutils=binutils-2.14 |
---|
[e7839be] | 89 | 97c97 |
---|
| 90 | < patch -p1 <\$patches/\$binutilsdiff |
---|
| 91 | --- |
---|
| 92 | > #patch -p1 <\$patches/\$binutilsdiff |
---|
| 93 | END |
---|
| 94 | sh build-djgpp.sh |
---|
| 95 | </pre> |
---|
| 96 | |
---|
[e364af7] | 97 | If the build of GCC fails, you may need to apply this patch: |
---|
| 98 | |
---|
| 99 | <pre> |
---|
| 100 | --- gcc-3.3.2-orig/libiberty/getpwd.c 2001-10-07 22:53:31.000000000 +0100 |
---|
| 101 | +++ gcc-3.3.2/libiberty/getpwd.c 2004-01-12 02:00:41.000000000 +0000 |
---|
| 102 | @@ -50,2 +50,3 @@ |
---|
| 103 | |
---|
| 104 | +#undef MAXPATHLEN |
---|
| 105 | #ifdef MAXPATHLEN |
---|
| 106 | </pre> |
---|
| 107 | |
---|
| 108 | You may also need to configure and build GCC without support for C++ (the script |
---|
| 109 | downloaded configures all languages and builds C and C++). Sorry if that's |
---|
| 110 | a bit vague - email Olly if you can't work out what to do. |
---|
| 111 | |
---|
[c372fc9] | 112 | <P>Then you need to build and install the |
---|
| 113 | <A HREF="http://www.talula.demon.co.uk/allegro/">Allegro graphics library</A>: |
---|
[e7839be] | 114 | |
---|
| 115 | <P><A |
---|
[e364af7] | 116 | HREF="http://prdownloads.sourceforge.net/alleg/allegro-4.0.3.tar.gz" |
---|
| 117 | >http://prdownloads.sourceforge.net/alleg/allegro-4.0.3.tar.gz</A> |
---|
[61b4202] | 118 | |
---|
[857f8a6] | 119 | <P>And follow the instructions for building using a cross-compiler which |
---|
[e364af7] | 120 | you can in docs/build/djgpp.txt. In 4.0.3 these boil down to: |
---|
[e7839be] | 121 | |
---|
[b63c928d] | 122 | <pre> |
---|
[e364af7] | 123 | cd allegro-4.0.3 |
---|
[857f8a6] | 124 | ./fix.sh djgpp --quick |
---|
[b63c928d] | 125 | NATIVEPATH=$PATH |
---|
| 126 | export NATIVEPATH |
---|
[e364af7] | 127 | DJDIR=/usr/i386-pc-msdosdjgpp |
---|
[b63c928d] | 128 | export DJDIR |
---|
[e364af7] | 129 | PATH=$DJDIR/bin:$PATH |
---|
[b63c928d] | 130 | CROSSCOMPILE=1 |
---|
| 131 | export CROSSCOMPILE |
---|
[e364af7] | 132 | make msg lib |
---|
[b63c928d] | 133 | make install |
---|
| 134 | PATH=$NATIVEPATH |
---|
| 135 | </pre> |
---|
| 136 | |
---|
| 137 | <P>Building Survex under DOS in a native djgpp environment will require |
---|
| 138 | some tinkering. Best bet is either to install bash and use the current |
---|
[e7839be] | 139 | configure script, or perhaps simpler to modify miniam.pl to generate a |
---|
| 140 | suitable makefile. I'm happy to help if you want to try this, and |
---|
| 141 | I'll incorporate patches provided they're fairly clean. |
---|
| 142 | |
---|
[c372fc9] | 143 | <H3>Mingw (Microsoft Windows)</H3> |
---|
[e7839be] | 144 | |
---|
| 145 | <P>Currently I build this with a Linux hosted cross-compiler. I use |
---|
| 146 | the packaged cross-compiler in the debian testing/unstable distribution. |
---|
| 147 | You can probably install these on other distributions using alien to |
---|
[e7c04bc] | 148 | convert them to RPMs or similar. |
---|
[e7839be] | 149 | |
---|
| 150 | <P>Building on Windows in a native mingw environment will probably |
---|
| 151 | require tinkering. Best bet is probably to install bash and use the |
---|
| 152 | current configure script. I'm happy to help if you want to try this, |
---|
| 153 | and I'll incorporate patches provided they're fairly clean. |
---|
| 154 | |
---|
| 155 | <H3>MSDOS for 286 and earlier (BorlandC)</H3> |
---|
| 156 | |
---|
| 157 | <P>Wookey currently builds this with a rather elderly BorlandC++ 3.1. |
---|
| 158 | BorlandC++ 5.5 can be downloaded for free, but it appears to only compile to |
---|
| 159 | 32 bit code. You can also download TurboC version 2, which might do the job |
---|
[857f8a6] | 160 | (I've not tried). |
---|
[e7839be] | 161 | |
---|
| 162 | <P>You can build a suitable source archive for this version using |
---|
| 163 | `make alien_src_zip' on the source distribution on a Unix box (you need to |
---|
[857f8a6] | 164 | have run `./configure' first). Then unzip the src<version>.zip file |
---|
| 165 | produced on the MSDOS machine and run <code>make.bat</code>. |
---|
[e7839be] | 166 | |
---|
| 167 | <H3>RISC OS</H3> |
---|
| 168 | |
---|
| 169 | <P>We now build this with Acorn C V5. It will probably still build with |
---|
| 170 | Acorn C V4. You also need to get and install OSLib from: |
---|
| 171 | |
---|
| 172 | <P><A HREF="http://www.arcade.demon.co.uk/oslib/homepage.html" |
---|
| 173 | >http://www.arcade.demon.co.uk/oslib/homepage.html</A> |
---|
| 174 | |
---|
| 175 | <P>You can build a suitable source archive for compiling the RISC OS version by |
---|
| 176 | running `make alien_src_zip' on the source distribution on a Unix box (you |
---|
| 177 | need to have run `./configure' first). However for this you'll need a |
---|
| 178 | specially tweaked version of zip to create the zip file with the correct |
---|
| 179 | RISC OS file types. I can supply this on request. You need to put it in the |
---|
| 180 | top level of the source tree and call it `zip-magic'. |
---|
| 181 | |
---|
| 182 | <P>You'll probably need to use Acorn's Make Utility (`amu') to build - the GNU |
---|
| 183 | make 1.02 port doesn't seem up to the job. |
---|
| 184 | |
---|
| 185 | <P>To build, create a fresh directory (or empty one) and unpack the contents of |
---|
| 186 | srcN_NN.zip into it (using !SparkFS or similar). Then double-click on |
---|
| 187 | `!ObeyMe' in the unpacked directory to rename the source files into c and h |
---|
| 188 | subdirectories. Then double-click on `!MakeMe' to build survex. |
---|
| 189 | |
---|
[089bf7d] | 190 | <H2>Microsoft Windows Installer Builder</H2> |
---|
| 191 | |
---|
| 192 | <P>We use <A HREF="http://www.jrsoftware.org/isinfo.php">InnoSetup</A> to |
---|
| 193 | build the MS Windows Installer. Survex 1.0.40 was built using InnoSetup |
---|
| 194 | 5.4.2 (non-Unicode version, so that the installer works on older versions |
---|
| 195 | of Microsoft Windows). |
---|
| 196 | |
---|
| 197 | <P>Here are some random notes: |
---|
| 198 | |
---|
| 199 | <H3>Packages Needed</H3> |
---|
| 200 | |
---|
| 201 | <P>On Debian, you'll need to install these packages to build the installer: |
---|
| 202 | |
---|
| 203 | <P>apt-get install wine wx2.8-i18n |
---|
| 204 | |
---|
| 205 | <H3>Translations</H3> |
---|
| 206 | |
---|
| 207 | <P>In addition to the translations included with InnoSetup as standard, we also |
---|
| 208 | add these, which you can find in the <code>lib</code> subdirectory of Xapian's |
---|
| 209 | SVN tree: |
---|
| 210 | |
---|
| 211 | <UL> |
---|
| 212 | <LI>English_GB.isl (unofficial, done by Olly) |
---|
| 213 | <LI>Romanian-7-5.1.11.isl (unofficial, asked Cristian to check it over) |
---|
| 214 | </UL> |
---|
| 215 | |
---|
| 216 | <H3>survex.iss</H3> |
---|
| 217 | |
---|
| 218 | <P>This file is generated by configure (from the template survex.iss.in). |
---|
| 219 | We could instead have a static survex.iss which uses #include to pull in |
---|
| 220 | a file with the Survex version info in, but the current method works well |
---|
| 221 | enough so we'll stick with it for now (I suspect #include was introduced since |
---|
| 222 | we started using InnoSetup). |
---|
| 223 | |
---|
[e7839be] | 224 | </BODY></HTML> |
---|