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, 2.64 and 2.71 have all
  47 been used successfully).
  48
  49 <p>The wxWidgets library is used for aven's UI.  Currently >= 3.0.0 is
  50 supported.
  51
  52 <p>The PROJ library is used for coordinate conversions.  Currently >= 6.2.0 is
  53 supported.
  54
  55 <P>The Perl Locale::PO module is used for process message translation files.
  56
  57 <P>For building the documentation you'll need docbook-utils (also
  58 known as docbook-tools) and w3m.
  59
  60 <P>And for building unifont.pixelfont, you'll need unifont installed.
  61
  62 <P>On Debian, you can install the required packages using:
  63
  64 <pre>
  65 sudo apt-get install autoconf automake liblocale-po-perl libproj-dev libwxgtk3.0-gtk3-dev inkscape netpbm docbook-utils w3m unifont
  66 </pre>
  67
  68 <H2>Building on Non-Unix Platforms</H2>
  69
  70 <H3>Mingw (Microsoft Windows)</H3>
  71
  72 <P>Currently I build this with a Linux hosted cross-compiler.  I use
  73 the packaged cross-compiler in the debian testing/unstable distribution:
  74
  75 <pre>
  76 sudo apt-get install mingw-w64-i686-dev
  77 </pre>
  78
  79 <p>
  80 I then install the various libraries by compiling from source.  For wxWidgets
  81 I apply a
  82 <a href="https://survex.com/software/wxWidgets-3.1.6.patch">patch</a> to
  83 disable a pointless and annoying compiler ABI check
  84 (with this check aven stops working each time my cross compiler package is
  85 upgraded to a new GCC version; without it everything works fine).
  86 </p>
  87
  88 <p>
  89 Then I configure, build and install with:
  90 </p>
  91
  92 <pre>
  93 ./configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --with-msw --with-opengl --without-libtiff --enable-display --disable-shared host_alias=i686-w64-mingw32 DOCBOOK_TO_MAN="xmlto man --skip-validation"
  94 make
  95 sudo make install
  96 </pre>
  97
  98 <p>With wxWidgets 3.1.6, there's a linking problem with aven if libtiff isn't
  99 disabled, and Survex doesn't use it so it's simplest to just disable it:
 100 </p>
 101
 102 <pre>
 103 /usr/bin/i686-w64-mingw32-ld: /usr/i686-w64-mingw32/lib/libwxtiff-3.1-i686-w64-mingw32.a(wxtiff_tif_dirinfo.o):tif_dirinfo.c:(.text+0x80d): undefined reference to `_TIFF_snprintf_f'
 104 </pre>
 105
 106 <p>
 107 For sqlite (needed by PROJ):
 108 </p>
 109
 110 <pre>
 111 wget https://www.sqlite.org/2021/sqlite-autoconf-3360000.tar.gz
 112 tar xvf sqlite-autoconf-3360000.tar.gz
 113 mkdir BUILD
 114 cd BUILD
 115 ../configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --disable-shared --disable-fts4 --disable-fts5 --disable-json1 --disable-rtree host_alias=i686-w64-mingw32
 116 make
 117 sudo make install
 118 </pre>
 119
 120 <p>
 121 For PROJ 8.2.0 (TIFF apparently useful for some grids, but would also need libtiff):
 122 </p>
 123
 124 <pre>
 125 mkdir BUILD
 126 cd BUILD
 127 ../configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --disable-shared host_alias=i686-w64-mingw32 --without-curl --disable-tiff
 128 make
 129 sudo make install
 130 </pre>
 131
 132 <p>
 133 For ffmpeg 4.4.1:
 134 </p>
 135
 136 <pre>
 137 sudo apt-get install yasm
 138 mkdir BUILD
 139 cd BUILD
 140 ../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
 141 make
 142 sudo make install
 143 </pre>
 144
 145 <P>Building on Windows in a native mingw environment will probably
 146 require tinkering.  Best bet is probably to install bash and use the
 147 current configure script.  I'm happy to help if you want to try this,
 148 and I'll incorporate patches provided they're fairly clean.
 149
 150 <H2>Microsoft Windows Installer Builder</H2>
 151
 152 <P>We use <A HREF="http://www.jrsoftware.org/isinfo.php">InnoSetup</A> to
 153 build the MS Windows Installer.  Survex 1.4.2 was built using InnoSetup
 154 6.2.0.
 155
 156 <P>Here are some random notes:
 157
 158 <H3>Packages Needed</H3>
 159
 160 <P>On Debian unstable/testing:
 161
 162 <pre>
 163 sudo apt-get install wine wx3.0-i18n
 164 </pre>
 165
 166 <P>And then run:
 167
 168 <pre>
 169 wine ~/Downloads/innosetup-6.2.0.exe
 170 </pre>
 171
 172 <H3>Translations</H3>
 173
 174 <P>In addition to the translations included with InnoSetup as standard, we also
 175 add these, which you can find in the <code>lib</code> subdirectory of Survex's
 176 source tree:
 177
 178 <UL>
 179 <li>ChineseSimplified.isl (6.1.0+)
 180 <li>ChineseTraditional.isl (6.1.0+)
 181 <li>EnglishBritish.isl (6.1.0+)
 182 <li>Greek.isl (6.1.0+)
 183 <li>Hungarian.isl (6.1.0+)
 184 <li>Indonesian.isl (6.1.0+)
 185 <li>Romanian.isl (5.5.3+)
 186 </UL>
 187
 188 These are taken from the <a href="https://jrsoftware.org/files/istrans/">Inno
 189 Setup Translations</a> page.
 190
 191 <H3>survex.iss</H3>
 192
 193 <P>This file is generated by configure (from the template survex.iss.in).
 194 We could instead have a static survex.iss which uses #include to pull in
 195 a file with the Survex version info in, but the current method works well
 196 enough so we'll stick with it for now (I suspect #include was introduced since
 197 we started using InnoSetup).
 198
 199 </BODY></HTML>