doc/HACKING.htm

   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
  43 <P>You'll need automake 1.5 or later (earlier versions don't support
  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)
  46 and autoconf 2.50 or later (autoconf 2.52, 2.53 and 2.64 have all
  47 been used successfully).
  48
  49 <P>For building the documentation you'll need sgmltools 2 or later,
  50 jadetex, docbook-utils, and w3m.
  51
  52 <P>And for building unifont.pixelfont, you'll need unifont installed.
  53
  54 <P>On Debian, you can install the required packages using:
  55
  56 <pre>
  57 sudo apt-get install autoconf automake inkscape netpbm sgmltools-lite jadetex docbook-utils w3m unifont
  58 </pre>
  59
  60 <H2>Building on Non-Unix Platforms</H2>
  61
  62 <H3>Mingw (Microsoft Windows)</H3>
  63
  64 <P>Currently I build this with a Linux hosted cross-compiler.  I use
  65 the packaged cross-compiler in the debian testing/unstable distribution:
  66
  67 <pre>
  68 sudo apt-get install mingw-w64-i686-dev
  69 </pre>
  70
  71 <p>
  72 I then install the various libraries by compiling from source.  For wxWidgets
  73 3.0.1, I configure, build and install with:
  74 </p>
  75
  76 <pre>
  77 ./configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --with-msw --with-opengl --enable-display --disable-threads --disable-shared host_alias=i686-w64-mingw32 --disable-tls
  78 make
  79 sudo make install
  80 </pre>
  81
  82 <p>
  83 For PROJ 4.8.0:
  84 </p>
  85
  86 <pre>
  87 mkdir BUILD
  88 cd BUILD
  89 ../configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --disable-shared host_alias=i686-w64-mingw32
  90 make
  91 sudo make install
  92 </pre>
  93
  94 <p>
  95 For libav 10.3:
  96 </p>
  97
  98 <pre>
  99 sudo apt-get install yasm
 100 mkdir BUILD
 101 cd BUILD
 102 ../configure --prefix=/usr/i686-w64-mingw32 --cross-prefix=i686-w64-mingw32- --enable-cross-compile --target-os=mingw32 --arch=i686 --disable-shared --disable-decoders --disable-demuxers --disable-programs --disable-network --disable-bsfs --disable-protocols --disable-devices
 103 make
 104 sudo make install
 105 </pre>
 106
 107 <P>Building on Windows in a native mingw environment will probably
 108 require tinkering.  Best bet is probably to install bash and use the
 109 current configure script.  I'm happy to help if you want to try this,
 110 and I'll incorporate patches provided they're fairly clean.
 111
 112 <H2>Microsoft Windows Installer Builder</H2>
 113
 114 <P>We use <A HREF="http://www.jrsoftware.org/isinfo.php">InnoSetup</A> to
 115 build the MS Windows Installer.  Survex 1.2.23 was built using InnoSetup
 116 5.5.6 (non-Unicode version, which apparently produces smaller installer
 117 packages).
 118
 119 <P>Here are some random notes:
 120
 121 <H3>Packages Needed</H3>
 122
 123 <P>On Debian, the commands to install wine vary depending on the architecture
 124 you're running - to check this use:
 125
 126 <pre>
 127 dpkg-architecture -qDEB_HOST_GNU_CPU
 128 </pre>
 129
 130 <H4>For i386</H4>
 131
 132 <pre>
 133 sudo apt-get install wine wx3.0-i18n
 134 </pre>
 135
 136 <H4>For x86_64</H4>
 137
 138 <P>You'll need to enable multi-arch and install the i386 packages of wine:
 139
 140 <pre>
 141 sudo dpkg --add-architecture i386
 142 sudo apt-get update
 143 sudo apt-get install wine wine-bin:i386 wx3.0-i18n
 144 </pre>
 145
 146 <H4>Common</H4>
 147
 148 <P>And then run:
 149
 150 <pre>
 151 wine ~/Downloads/isetup-5.5.3.exe
 152 </pre>
 153
 154 <H3>Translations</H3>
 155
 156 <P>In addition to the translations included with InnoSetup as standard, we also
 157 add these, which you can find in the <code>lib</code> subdirectory of Survex's
 158 source tree:
 159
 160 <UL>
 161 <li>ChineseSimplified.isl (Unofficial translation; for 5.5.3+)
 162 <li>ChineseTraditional.isl (Candidate official translation; for 5.5.3+)
 163 <li>EnglishBritish.isl (Unofficial translation; for 5.5.3+)
 164 <li>Indonesian.isl (Unofficial translation; for 5.5.3+)
 165 <li>Romanian.isl (Unofficial translation; for 5.5.3+)
 166 <li>Slovak.isl (Unofficial translation; for 5.5.3+)
 167 </UL>
 168
 169 These are taken from the innosetup repo at
 170 https://github.com/jrsoftware/issrc.git
 171 (look in the <code>Files/Languages/Unofficial</code> subdirectory).
 172
 173 <H3>survex.iss</H3>
 174
 175 <P>This file is generated by configure (from the template survex.iss.in).
 176 We could instead have a static survex.iss which uses #include to pull in
 177 a file with the Survex version info in, but the current method works well
 178 enough so we'll stick with it for now (I suspect #include was introduced since
 179 we started using InnoSetup).
 180
 181 </BODY></HTML>