source: git/doc/HACKING.htm @ cdb5c7f

stereo-2025
Last change on this file since cdb5c7f was d84d9e5, checked in by Olly Betts <olly@…>, 6 months ago

Use https for URLs which support it
  • Property mode set to 100644
File size: 6.9 KB
Line 
1<HTML><HEAD>
2<TITLE>Survex Hacker's Guide</TITLE>
3<STYLE type="text/css"><!--
4BODY, 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
14down while I remember.  With time it should evolve into a more
15coherent document.  If you have any questions which this should answer
16but 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"
21with 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
38conceivably be added in future, although the simple common cases are
39already 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
44per-executable CFLAGS; 1.6 has been tested and works, but wasn't a
45very stable release - automake 1.6.1 is a better bet)
46and autoconf 2.50 or later (autoconf 2.52, 2.53, 2.64 and 2.71 have all
47been used successfully).
48
49<p>The wxWidgets library is used for aven's UI.  Currently &gt;= 3.0.0 is
50supported.
51
52<p>The PROJ library is used for coordinate conversions.  Currently &gt;= 6.2.0 is
53supported.
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>
65sudo 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
73pre-built installer for Microsoft Windows is built in such an environment
74by a CI job running on Github Actions.
75</p>
76
77<p>
78It should also be possible to use a Linux-hosted cross-compiler, which is
79how we used to built releases, but this requires cross-building a lot of
80required libraries so we gave up on doing this.  Some notes on this are
81left below in case anyone wants to try.
82</p>
83
84<p>
85I use the packaged cross-compiler in the debian testing/unstable distribution:
86</p>
87
88<pre>
89sudo apt-get install mingw-w64-i686-dev
90</pre>
91
92<p>
93Then install the various libraries by compiling from source.  For wxWidgets
94I apply a
95<a href="https://survex.com/software/wxWidgets-3.2.4.patch">patch</a> to
96disable a pointless and annoying compiler ABI check
97(with this check aven stops working each time my cross compiler package is
98upgraded to a new GCC version; without it everything works fine).
99</p>
100
101<p>
102Then 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
107make
108sudo make install
109</pre>
110
111<p>
112For sqlite (needed by PROJ):
113</p>
114
115<pre>
116wget https://www.sqlite.org/2021/sqlite-autoconf-3360000.tar.gz
117tar xvf sqlite-autoconf-3360000.tar.gz
118mkdir BUILD
119cd 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
121make
122sudo make install
123</pre>
124
125<p>
126Sadly newer versions of PROJ have to be built with cmake.  For PROJ 9.3.0
127I used the following (TIFF is apparently useful for some grids, but would also
128need libtiff):
129</p>
130
131<pre>
132mkdir BUILD
133cd BUILD
134cmake .. -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
135make
136sudo 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
143set(CMAKE_SYSTEM_NAME Windows)
144
145# which compilers to use for C and C++
146set(CMAKE_C_COMPILER   i686-w64-mingw32-gcc)
147set(CMAKE_CXX_COMPILER i686-w64-mingw32-g++)
148
149# where is the target environment located
150set(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
154set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
155
156# search headers and libraries in the target environment
157set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
158set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
159</pre>
160
161<p>
162For ffmpeg 4.4.1:
163</p>
164
165<pre>
166sudo apt-get install yasm
167mkdir BUILD
168cd 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
170make
171sudo make install
172</pre>
173
174<p>
175You'll also need to install GDAL, which requires a lot of other libraries
176installed 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="https://jrsoftware.org/isinfo.php">InnoSetup</A> to
182build the MS Windows Installer.  Since 1.4.9 we use the InnoSetup version
183which is pre-installed in the Github CI images.
184</p>
185
186<p>
187Survex 1.4.8 was built using InnoSetup 6.2.2.
188</p>
189
190<p>
191Here 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>
199sudo apt-get install wine wx3.0-i18n
200</pre>
201
202<P>And then run:
203
204<pre>
205wine ~/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
211add these, which you can find in the <code>lib</code> subdirectory of Survex's
212source 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
223These are taken from the <a href="https://jrsoftware.org/files/istrans/">Inno
224Setup Translations</a> page.
225
226<H3>survex.iss</H3>
227
228<P>This file is generated by configure (from the template survex.iss.in).
229We could instead have a static survex.iss which uses #include to pull in
230a file with the Survex version info in, but the current method works well
231enough so we'll stick with it for now (I suspect #include was introduced since
232we started using InnoSetup).
233
234</BODY></HTML>
Note: See TracBrowser for help on using the repository browser.