source: git/doc/HACKING.htm @ b3721bf

main
Last change on this file since b3721bf was ce243b0, checked in by Olly Betts <olly@…>, 7 days ago

Require automake 1.14

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