| [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 |
|---|
| [27b8b59] | 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) |
|---|
| [1ed5c4e] | 46 | and autoconf 2.50 or later (autoconf 2.52, 2.53, 2.64 and 2.71 have all |
|---|
| [9bf7aa33] | 47 | been used successfully). |
|---|
| [c372fc9] | 48 | |
|---|
| [dc74a56] | 49 | <p>The wxWidgets library is used for aven's UI. Currently >= 3.0.0 is |
|---|
| [1ed5c4e] | 50 | supported. |
|---|
| 51 | |
|---|
| [dc74a56] | 52 | <p>The PROJ library is used for coordinate conversions. Currently >= 6.2.0 is |
|---|
| [1ed5c4e] | 53 | supported. |
|---|
| 54 | |
|---|
| 55 | <P>The Perl Locale::PO module is used for process message translation files. |
|---|
| 56 | |
|---|
| [d1aefbc] | 57 | <P>For building the documentation you'll need sphinx-doc (Debian/Ubuntu package |
|---|
| 58 | <tt>python3-sphinx</tt>) and w3m. |
|---|
| [e7839be] | 59 | |
|---|
| [29e5a96] | 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> |
|---|
| [d1aefbc] | 65 | sudo apt-get install autoconf automake liblocale-po-perl libproj-dev libwxgtk3.0-gtk3-dev inkscape netpbm python3-sphinx w3m unifont |
|---|
| [29e5a96] | 66 | </pre> |
|---|
| [6127c82] | 67 | |
|---|
| [e7839be] | 68 | <H2>Building on Non-Unix Platforms</H2> |
|---|
| 69 | |
|---|
| [c372fc9] | 70 | <H3>Mingw (Microsoft Windows)</H3> |
|---|
| [e7839be] | 71 | |
|---|
| [f5e6be8] | 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> |
|---|
| [adceff5] | 87 | |
|---|
| [bd285e5a] | 88 | <pre> |
|---|
| 89 | sudo apt-get install mingw-w64-i686-dev |
|---|
| 90 | </pre> |
|---|
| [e7839be] | 91 | |
|---|
| [d6a770d] | 92 | <p> |
|---|
| [f5e6be8] | 93 | Then install the various libraries by compiling from source. For wxWidgets |
|---|
| [3e85309] | 94 | I apply a |
|---|
| [b1c66e1] | 95 | <a href="https://survex.com/software/wxWidgets-3.2.4.patch">patch</a> to |
|---|
| [3e85309] | 96 | disable a pointless and annoying compiler ABI check |
|---|
| [38bc415] | 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). |
|---|
| [853438c] | 99 | </p> |
|---|
| 100 | |
|---|
| 101 | <p> |
|---|
| 102 | Then I configure, build and install with: |
|---|
| [bd285e5a] | 103 | </p> |
|---|
| 104 | |
|---|
| 105 | <pre> |
|---|
| [d1aefbc] | 106 | ./configure --prefix=/usr/i686-w64-mingw32 --host i686-w64-mingw32 --with-msw --with-opengl --enable-display --disable-shared host_alias=i686-w64-mingw32 |
|---|
| [bd285e5a] | 107 | make |
|---|
| 108 | sudo make install |
|---|
| 109 | </pre> |
|---|
| 110 | |
|---|
| 111 | <p> |
|---|
| [7576825] | 112 | For sqlite (needed by PROJ): |
|---|
| [d6a770d] | 113 | </p> |
|---|
| 114 | |
|---|
| [bd285e5a] | 115 | <pre> |
|---|
| [7576825] | 116 | wget https://www.sqlite.org/2021/sqlite-autoconf-3360000.tar.gz |
|---|
| 117 | tar xvf sqlite-autoconf-3360000.tar.gz |
|---|
| [bd285e5a] | 118 | mkdir BUILD |
|---|
| 119 | cd BUILD |
|---|
| [7576825] | 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 |
|---|
| [bd285e5a] | 121 | make |
|---|
| 122 | sudo make install |
|---|
| 123 | </pre> |
|---|
| 124 | |
|---|
| 125 | <p> |
|---|
| [9cf9de0] | 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): |
|---|
| [7576825] | 129 | </p> |
|---|
| 130 | |
|---|
| 131 | <pre> |
|---|
| 132 | mkdir BUILD |
|---|
| 133 | cd BUILD |
|---|
| [9cf9de0] | 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 |
|---|
| [7576825] | 135 | make |
|---|
| 136 | sudo make install |
|---|
| 137 | </pre> |
|---|
| 138 | |
|---|
| [dc74a56] | 139 | <p>where <tt>cross-mingw.cmake</tt> contains:</p> |
|---|
| [9cf9de0] | 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 | |
|---|
| [7576825] | 161 | <p> |
|---|
| 162 | For ffmpeg 4.4.1: |
|---|
| [bd285e5a] | 163 | </p> |
|---|
| 164 | |
|---|
| 165 | <pre> |
|---|
| 166 | sudo apt-get install yasm |
|---|
| 167 | mkdir BUILD |
|---|
| 168 | cd BUILD |
|---|
| [86801ff] | 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 |
|---|
| [bd285e5a] | 170 | make |
|---|
| 171 | sudo make install |
|---|
| 172 | </pre> |
|---|
| [d6a770d] | 173 | |
|---|
| [f5e6be8] | 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> |
|---|
| [e7839be] | 178 | |
|---|
| [9fe7af4f] | 179 | <H2>Microsoft Windows Installer Builder</H2> |
|---|
| 180 | |
|---|
| [f5e6be8] | 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> |
|---|
| [ebcdad9] | 185 | |
|---|
| [f5e6be8] | 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> |
|---|
| [9fe7af4f] | 193 | |
|---|
| [85f3565] | 194 | <H3>Packages Needed</H3> |
|---|
| 195 | |
|---|
| [7576825] | 196 | <P>On Debian unstable/testing: |
|---|
| [adceff5] | 197 | |
|---|
| 198 | <pre> |
|---|
| [8aebb0a] | 199 | sudo apt-get install wine wx3.0-i18n |
|---|
| [adceff5] | 200 | </pre> |
|---|
| 201 | |
|---|
| 202 | <P>And then run: |
|---|
| [85f3565] | 203 | |
|---|
| [adceff5] | 204 | <pre> |
|---|
| [fc1d89b] | 205 | wine ~/Downloads/innosetup-6.2.2.exe |
|---|
| [adceff5] | 206 | </pre> |
|---|
| [85f3565] | 207 | |
|---|
| [9fe7af4f] | 208 | <H3>Translations</H3> |
|---|
| 209 | |
|---|
| [ebcdad9] | 210 | <P>In addition to the translations included with InnoSetup as standard, we also |
|---|
| [8b3362b] | 211 | add these, which you can find in the <code>lib</code> subdirectory of Survex's |
|---|
| [e367554] | 212 | source tree: |
|---|
| [9fe7af4f] | 213 | |
|---|
| 214 | <UL> |
|---|
| [9990aab] | 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+) |
|---|
| [fc1d89b] | 220 | <li>Romanian.isl (6.1.0+) |
|---|
| [9fe7af4f] | 221 | </UL> |
|---|
| 222 | |
|---|
| [9990aab] | 223 | These are taken from the <a href="https://jrsoftware.org/files/istrans/">Inno |
|---|
| 224 | Setup Translations</a> page. |
|---|
| [317c11b] | 225 | |
|---|
| [9fe7af4f] | 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 | |
|---|
| [e7839be] | 234 | </BODY></HTML> |
|---|
