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 3.0.5, I apply a
  82 <a href="https://survex.com/software/wxWidgets-3.0.5.patch">patch</a> to
  83 fix a compiler error and 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 --enable-display --disable-shared host_alias=i686-w64-mingw32
  94 make
  95 sudo make install
  96 </pre>
  97
  98 <p>
  99 For sqlite (needed by PROJ):
 100 </p>
 101
 102 <pre>
 103 wget https://www.sqlite.org/2021/sqlite-autoconf-3360000.tar.gz
 104 tar xvf sqlite-autoconf-3360000.tar.gz
 105 mkdir BUILD
 106 cd BUILD
 107 ../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
 108 make
 109 sudo make install
 110 </pre>
 111
 112 <p>
 113 For PROJ 8.2.0 (TIFF apparently useful for some grids, but would also need libtiff):
 114 </p>
 115
 116 <pre>
 117 mkdir BUILD
 118 cd BUILD
 119 ../configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --disable-shared host_alias=i686-w64-mingw32 --without-curl --disable-tiff
 120 make
 121 sudo make install
 122 </pre>
 123
 124 <p>
 125 For ffmpeg 4.4.1:
 126 </p>
 127
 128 <pre>
 129 sudo apt-get install yasm
 130 mkdir BUILD
 131 cd BUILD
 132 ../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
 133 make
 134 sudo make install
 135 </pre>
 136
 137 <P>Building on Windows in a native mingw environment will probably
 138 require tinkering.  Best bet is probably to install bash and use the
 139 current configure script.  I'm happy to help if you want to try this,
 140 and I'll incorporate patches provided they're fairly clean.
 141
 142 <H2>Microsoft Windows Installer Builder</H2>
 143
 144 <P>We use <A HREF="http://www.jrsoftware.org/isinfo.php">InnoSetup</A> to
 145 build the MS Windows Installer.  Survex 1.2.23 was built using InnoSetup
 146 5.5.6 (non-Unicode version, which apparently produces smaller installer
 147 packages).
 148
 149 <P>Here are some random notes:
 150
 151 <H3>Packages Needed</H3>
 152
 153 <P>On Debian unstable/testing:
 154
 155 <pre>
 156 sudo apt-get install wine wx3.0-i18n
 157 </pre>
 158
 159 <P>And then run:
 160
 161 <pre>
 162 wine ~/Downloads/isetup-5.5.6.exe
 163 </pre>
 164
 165 <H3>Translations</H3>
 166
 167 <P>In addition to the translations included with InnoSetup as standard, we also
 168 add these, which you can find in the <code>lib</code> subdirectory of Survex's
 169 source tree:
 170
 171 <UL>
 172 <li>ChineseSimplified.isl (Unofficial translation; for 5.5.3+)
 173 <li>ChineseTraditional.isl (Candidate official translation; for 5.5.3+)
 174 <li>EnglishBritish.isl (Unofficial translation; for 5.5.3+)
 175 <li>Indonesian.isl (Unofficial translation; for 5.5.3+)
 176 <li>Romanian.isl (Unofficial translation; for 5.5.3+)
 177 <li>Slovak.isl (Unofficial translation; for 5.5.3+)
 178 </UL>
 179
 180 These are taken from the innosetup repo at
 181 https://github.com/jrsoftware/issrc.git
 182 (look in the <code>Files/Languages/Unofficial</code> subdirectory).
 183
 184 <H3>survex.iss</H3>
 185
 186 <P>This file is generated by configure (from the template survex.iss.in).
 187 We could instead have a static survex.iss which uses #include to pull in
 188 a file with the Survex version info in, but the current method works well
 189 enough so we'll stick with it for now (I suspect #include was introduced since
 190 we started using InnoSetup).
 191
 192 </BODY></HTML>