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 &gt;= 3.0.0 is
  50 supported.
  51
  52 <p>The PROJ library is used for coordinate conversions.  Currently &gt;= 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 sphinx-doc (Debian/Ubuntu package
  58 <tt>python3-sphinx</tt>) 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 python3-sphinx w3m unifont
  66 </pre>
  67
  68 <H2>Building on Non-Unix Platforms</H2>
  69
  70 <H3>Mingw (Microsoft Windows)</H3>
  71
  72 <p>Survex can be built in an MSYS2+mingw64 environment - since 1.4.9 the
  73 pre-built installer for Microsoft Windows is built in such an environment
  74 by a CI job running on Github Actions.
  75 </p>
  76
  77 <p>
  78 It should also be possible to use a Linux-hosted cross-compiler, which is
  79 how we used to built releases, but this requires cross-building a lot of
  80 required libraries so we gave up on doing this.  Some notes on this are
  81 left below in case anyone wants to try.
  82 </p>
  83
  84 <p>
  85 I use the packaged cross-compiler in the debian testing/unstable distribution:
  86 </p>
  87
  88 <pre>
  89 sudo apt-get install mingw-w64-i686-dev
  90 </pre>
  91
  92 <p>
  93 Then install the various libraries by compiling from source.  For wxWidgets
  94 I apply a
  95 <a href="https://survex.com/software/wxWidgets-3.2.4.patch">patch</a> to
  96 disable a pointless and annoying compiler ABI check
  97 (with this check aven stops working each time my cross compiler package is
  98 upgraded to a new GCC version; without it everything works fine).
  99 </p>
 100
 101 <p>
 102 Then I configure, build and install with:
 103 </p>
 104
 105 <pre>
 106 ./configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --with-msw --with-opengl --enable-display --disable-shared host_alias=i686-w64-mingw32
 107 make
 108 sudo make install
 109 </pre>
 110
 111 <p>
 112 For sqlite (needed by PROJ):
 113 </p>
 114
 115 <pre>
 116 wget https://www.sqlite.org/2021/sqlite-autoconf-3360000.tar.gz
 117 tar xvf sqlite-autoconf-3360000.tar.gz
 118 mkdir BUILD
 119 cd BUILD
 120 ../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
 121 make
 122 sudo make install
 123 </pre>
 124
 125 <p>
 126 Sadly newer versions of PROJ have to be built with cmake.  For PROJ 9.3.0
 127 I used the following (TIFF is apparently useful for some grids, but would also
 128 need libtiff):
 129 </p>
 130
 131 <pre>
 132 mkdir BUILD
 133 cd BUILD
 134 cmake .. -DCMAKE_TOOLCHAIN_FILE=~/git/survex/cross-mingw.cmake -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32 -DENABLE_CURL=OFF -DENABLE_TIFF=OFF -DBUILD_PROJSYNC=OFF -DBUILD_SHARED_LIBS=OFF -DCMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON -DCMAKE_FIND_USE_PACKAGE_REGISTRY=OFF -DCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON -DFETCHCONTENT_FULLY_DISCONNECTED=ON -DBUILD_TESTING=OFF
 135 make
 136 sudo make install
 137 </pre>
 138
 139 <p>where <tt>cross-mingw.cmake</tt> contains:</p>
 140
 141 <pre>
 142 # the name of the target operating system
 143 set(CMAKE_SYSTEM_NAME Windows)
 144
 145 # which compilers to use for C and C++
 146 set(CMAKE_C_COMPILER   i686-w64-mingw32-gcc)
 147 set(CMAKE_CXX_COMPILER i686-w64-mingw32-g++)
 148
 149 # where is the target environment located
 150 set(CMAKE_FIND_ROOT_PATH  /usr/i686-w64-mingw32)
 151
 152 # adjust the default behaviour of the FIND_XXX() commands:
 153 # search programs in the host environment
 154 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
 155
 156 # search headers and libraries in the target environment
 157 set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
 158 set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
 159 </pre>
 160
 161 <p>
 162 For ffmpeg 4.4.1:
 163 </p>
 164
 165 <pre>
 166 sudo apt-get install yasm
 167 mkdir BUILD
 168 cd BUILD
 169 ../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
 170 make
 171 sudo make install
 172 </pre>
 173
 174 <p>
 175 You'll also need to install GDAL, which requires a lot of other libraries
 176 installed to build.  I gave up at this point.
 177 </p>
 178
 179 <H2>Microsoft Windows Installer Builder</H2>
 180
 181 <p>We use <A HREF="http://www.jrsoftware.org/isinfo.php">InnoSetup</A> to
 182 build the MS Windows Installer.  Since 1.4.9 we use the InnoSetup version
 183 which is pre-installed in the Github CI images.
 184 </p>
 185
 186 <p>
 187 Survex 1.4.8 was built using InnoSetup 6.2.2.
 188 </p>
 189
 190 <p>
 191 Here are some random notes on the old cross-building approach:
 192 </p>
 193
 194 <H3>Packages Needed</H3>
 195
 196 <P>On Debian unstable/testing:
 197
 198 <pre>
 199 sudo apt-get install wine wx3.0-i18n
 200 </pre>
 201
 202 <P>And then run:
 203
 204 <pre>
 205 wine ~/Downloads/innosetup-6.2.2.exe
 206 </pre>
 207
 208 <H3>Translations</H3>
 209
 210 <P>In addition to the translations included with InnoSetup as standard, we also
 211 add these, which you can find in the <code>lib</code> subdirectory of Survex's
 212 source tree:
 213
 214 <UL>
 215 <li>ChineseSimplified.isl (6.1.0+)
 216 <li>ChineseTraditional.isl (6.1.0+)
 217 <li>EnglishBritish.isl (6.1.0+)
 218 <li>Greek.isl (6.1.0+)
 219 <li>Indonesian.isl (6.1.0+)
 220 <li>Romanian.isl (6.1.0+)
 221 </UL>
 222
 223 These are taken from the <a href="https://jrsoftware.org/files/istrans/">Inno
 224 Setup Translations</a> page.
 225
 226 <H3>survex.iss</H3>
 227
 228 <P>This file is generated by configure (from the template survex.iss.in).
 229 We could instead have a static survex.iss which uses #include to pull in
 230 a file with the Survex version info in, but the current method works well
 231 enough so we'll stick with it for now (I suspect #include was introduced since
 232 we started using InnoSetup).
 233
 234 </BODY></HTML>