Skip to content

Commit 3419187

Browse files
jubalhjubalh
authored
Merge pull request #169 from bkmgit/doc-meson
Document building with meson
2 parents 6ec73b4 + 65457da commit 3419187

5 files changed

Lines changed: 339 additions & 191 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The website is generated from XML templates and Markdown sources using [sblg](ht
66

77
| To Change... | Edit File(s) | Format |
88
| :--- | :--- | :--- |
9-
| **Home Page (Landing)** | `index.content.md`, `index.features.md` and `index.screenshots.md` | Markdown |
9+
| **Home Page (Landing)** | `index.md` | Markdown |
1010
| **Top-Level Pages** (FAQ, Donate, etc.) | `pagesource/*.md` | Markdown |
1111
| **Blog Posts** | `blogsource/content/post/*.md` | Markdown |
1212
| **Blog User Profiles** | `blogsource/content/contributors/*.md` | Markdown |
@@ -17,7 +17,7 @@ The website is generated from XML templates and Markdown sources using [sblg](ht
1717
| **Style** | `css/*.css` | CSS |
1818

1919
### Page Sources
20-
The source files for the landing page (`index.content.md`, `index.features.md` and `index.screenshots.md`) and other top level pages in `pagesource/` are writen in Markdown. They are transformed to HTML and then injected into the appropriate header and footer templates. The list of supported XEPS is generated using a git submodule for https://github.com/profanity-im/profanity/blob/master/profanity.doap.
20+
The source files for the landing page (`index.md`) and other top level pages in `pagesource/` are writen in Markdown. They are transformed to HTML and then injected into the appropriate header and footer templates. The list of supported XEPS is generated using a git submodule for https://github.com/profanity-im/profanity/blob/master/profanity.doap.
2121

2222
### Blog
2323
Blog posts and contributor profiles are written in Markdown.

‎guide/0180/build.html‎

Lines changed: 168 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -35,27 +35,32 @@ <h3>Contents</h3>
3535
<a name="build"></a>
3636
<h3>Building</h3>
3737

38-
<p>Profanity uses the Autotools for its build system. The Autotools consist of Autoconf and Automake. This
39-
page doesn't go in any detail about the Autotools, but describes the commands needed to build Profanity,
40-
and brief descriptions of the various stages. You will also need autoconf-archive.</p>
38+
<p>Profanity uses the <a href="https://mesonbuild.com">Meson</a> build
39+
system. This page doesn't go into any detail about Meson, but describes
40+
the commands needed to build Profanity, and brief descriptions of the
41+
various stages.</p>
4142

42-
<p>You can either download the archive from the homepage or use git, a version control system, to get the
43-
latest code.</p>
43+
<p>You can either download the archive from the homepage or use git, a
44+
version control system, to get the latest code.</p>
4445
<p>If you want to get the latest version from git you'll have to do:</p>
4546
<pre><code>git clone https://github.com/profanity-im/profanity</code></pre>
4647

47-
<p>After obtaining the source code, and extracting it, use the following commands to build and install<p>
48-
<pre><code>./bootstrap.sh
49-
./configure
50-
make
51-
make install</code></pre>
52-
<p>The first step is only needed if you pulled from git</p>
48+
<p>After obtaining the source code, use the following
49+
commands to build and install it with no options enabled<p>
50+
<pre><code>cd profanity
51+
meson setup build_run
52+
meson compile -C build_run
53+
meson install -C build_run</code></pre>
5354
<p>The final step requires root privileges.</p>
5455

55-
<p>Various dependencies are required to install Profanity, the <code>./configure</code> script will
56-
fail if the minimum dependencies cannot be found.<p>
57-
<p>The latest code in <code>master</code> is also kept up to date with development changes
58-
to libstrophe, so a manual build of this library may also be needed</p>
56+
<p>Various dependencies are required to install Profanity, the
57+
<code>meson setup build_run</code> step will
58+
fail if the minimum dependencies cannot be found.<p>
59+
<p>To enable greater functionality, additional optional dependencies are required.
60+
Please read on for instructions for how to get the required and optional dependencies
61+
and how to enable different options.</p>
62+
<p>The latest code in <code>master</code> is also kept up to date with development changes
63+
to libstrophe, so a manual build of this library may also be needed</p>
5964
</section>
6065
<section>
6166
<a name="pkgdeps"></a>
@@ -64,15 +69,13 @@ <h3>Dependencies</h3>
6469
<p>The package names below are from Ubuntu and may differ per distribution.</p>
6570

6671
<h4>Build dependencies:</h4>
67-
<pre><code>automake
68-
autoconf
69-
autoconf-archive
70-
libtool
72+
<pre><code>gcc
73+
meson
7174
pkg-config</code></pre>
7275

7376
<h4>Required dependencies:</h4>
7477

75-
<p>Profanity is using <a href="https://github.com/strophe/libstrophe" target="_blank">libstrophe</a>.</p>
78+
<p>Profanity uses <a href="https://github.com/strophe/libstrophe" target="_blank">libstrophe</a>.</p>
7679

7780
<p>Profanity also requires development packages of:</p>
7881
<pre><code>ncurses
@@ -89,40 +92,43 @@ <h4>Optional dependencies:</h4>
8992
libgpgme # PGP support
9093
libsignal-protocol-c # OMEMO support
9194
libgcrypt # OMEMO support (>= 1.7)
92-
gtk2 or gtk3 # Desktop tray icon support
95+
libenchant-2 # Spell check support
96+
gtk3 # Desktop tray icon support
9397
python # Python plugin support
9498
cmocka # To run tests
9599
shared-mime-info # Send files with the correct mime type
96100
gdk-pixbuf2 # Scale the image for `/avatar set`
97-
qrencode # Display OMEMO QR code</code></pre>
101+
qrencode # Display OMEMO QR code
102+
xscreensaver # Idle time detection</code></pre>
98103
</section>
99104
<section>
100105
<a name="distrodeps"></a>
101106
<h3>Distribution details:</h3>
102107

103108
<p>To make it easier to install all the required packages in various distributions we collect copy pastes
104-
here. These are contributed to users and might be out of date. Feel free to create <a href="https://github.com/profanity-im/profanity-im.github.io">pull request</a> to improve this section.</p>
109+
here. These are contributed to users and might be out of date. Feel free to create a
110+
<a href="https://github.com/profanity-im/profanity-im.github.io">pull request</a> to improve this section.</p>
105111

106112
<h4>Debian</h4>
107-
<pre><code>apt-get install libcaca-dev libnotify-dev libgtk2.0-dev libotr5-dev libssl-dev libstrophe-dev pkg-config python3-dev libexpat1-dev libncursesw5-dev libglib2.0-dev libreadline-dev libgpgme11-dev libcurl4-gnutls-dev uuid-dev libcmocka-dev libgcrypt20-dev libsignal-protocol-c-dev libxss-dev libsqlite3-dev autoconf-archive autoconf libgdk-pixbuf-2.0-dev libqrencode-dev
113+
<pre><code>apt-get install libcaca-dev libnotify-dev libgtk2.0-dev libotr5-dev libssl-dev libstrophe-dev pkg-config python3-dev libexpat1-dev libncursesw5-dev libglib2.0-dev libreadline-dev libgpgme11-dev libcurl4-gnutls-dev uuid-dev libcmocka-dev libgcrypt20-dev libsignal-protocol-c-dev libxss-dev libsqlite3-dev libgdk-pixbuf-2.0-dev libqrencode-dev libenchant-2-dev meson
108114
</code></pre>
109115

110116
<h4>openSUSE</h4>
111-
<pre><code>zypper in gcc make automake autoconf libtool glib2-devel gtk2-devel libcmocka-devel libcurl-devel libexpat-devel libgpgme-devel libstrophe-devel libnotify-devel libotr-devel libuuid-devel ncurses-devel python3-devel readline-devel autoconf-archive libsignal-protocol-c-devel libgcrypt-devel sqlite3-devel gdk-pixbuf-devel qrencode-devel</code></pre>
117+
<pre><code>zypper in gcc meson enchant-devel glib2-devel gtk2-devel libcmocka-devel libcurl-devel libexpat-devel libgpgme-devel libstrophe-devel libnotify-devel libotr-devel libuuid-devel ncurses-devel python3-devel readline-devel libsignal-protocol-c-devel libgcrypt-devel sqlite3-devel gdk-pixbuf-devel qrencode-devel</code></pre>
112118

113119
<h4>Alpine Linux (Edge)</h4>
114-
<pre><code>apk add build-base autoconf autoconf-archive automake libtool pkgconf libmesode-dev ncurses-dev glib-dev curl-dev readline-dev libnotify-dev libxscrnsaver libotr-dev gpgme-dev libsignal-protocol-c-dev libgcrypt-dev gtk+2.0-dev python3-dev cmocka-dev</code></pre>
120+
<pre><code>apk add build-base meson enchant2-dev libtool pkgconf libmesode-dev ncurses-dev glib-dev curl-dev readline-dev libnotify-dev libxscrnsaver libotr-dev gpgme-dev libsignal-protocol-c-dev libgcrypt-dev gtk+3.0-dev python3-dev cmocka-dev</code></pre>
115121

116122
<p>Note that some of the packages for Alpine Linux are only available in the "testing" repository</p>
117123

118124
<h4>Arch Linux</h4>
119-
<pre><code>pacman -S --needed autoconf autoconf-archive automake base-devel check cmake cmocka curl doxygen expat gcc git gpgme gtk2 libgcrypt libnotify libotr libtool libxss make openssl pkg-config python wget sqlite gdk-pixbuf2 qrencode</code></pre>
125+
<pre><code>pacman -S --needed base-devel cairo check cmake cmocka curl doxygen expat gcc git gdk-pixbuf2 gpgme gtk3 libcurl.so libgcrypt libgpg-error libncursesw.so libnotify libotr libsignal-protocol-c libstrophe.so libtool libx11 libxss meson openssl pkg-config python qrencode sqlite wget</code></pre>
120126

121127
<h4>Fedora</h4>
122-
<pre><code>dnf install autoconf autoconf-archive automake expect-devel gcc git glib2-devel glibc-all-langpacks gtk2-devel libXScrnSaver-devel libcmocka-devel libcurl-devel expat-devel libgcrypt-devel gpgme-devel libmicrohttpd-devel libnotify-devel libotr-devel libsignal-protocol-c-devel libtool libuuid-devel make ncurses-devel python3 python3-devel readline-devel openssl-devel sqlite-devel gdk-pixbuf2-devel qrencode-devel libstrophe-devel</code></pre>
128+
<pre><code>dnf install enchant2-devel expect-devel gcc git glib2-devel glibc-all-langpacks gtk3-devel libXScrnSaver-devel libcmocka-devel libcurl-devel expat-devel libgcrypt-devel gpgme-devel libmicrohttpd-devel libnotify-devel libotr-devel libsignal-protocol-c-devel libtool libuuid-devel meson ncurses-devel python3 python3-devel readline-devel openssl-devel sqlite-devel gdk-pixbuf2-devel qrencode-devel libstrophe-devel</code></pre>
123129

124130
<h4>Mac OS</h4>
125-
<pre><code>brew install autoconf autoconf-archive automake libtool pkg-config glib gnutls gpgme libotr libstrophe openssl ossp-uuid readline terminal-notifier libsignal-protocol-c</code></pre>
131+
<pre><code>brew install cmocka gettext glib gpgme gtk+3 libomemo-c libotr libstrophe libxscrnsaver meson ninja pkgconf python@3.14 qrencode readline sqlite terminal-notifier</code></pre>
126132

127133
<p>Some required packages are "keg-only", which means they are not symlinked into /usr/local, therefore
128134
pkg-config will fail when detecting the libraries and the build will fail. In order to fix this we need
@@ -137,74 +143,164 @@ <h4>Mac OS</h4>
137143
</code></pre>
138144

139145
<h4>OpenBSD</h4>
140-
<pre><code>pkg_add cmake gmake cmocka libtool automake-1.16.2 pkgconf readline python-3.8.2 autoconf-2.69p2 autoconf-archive libstrophe curl gpgme glib2 gtk+2 libotr libassuan libgpg-error libgcrypt libsignal-protocol-c sqlite3</code></pre>
146+
<pre><code>pkg_add meson cmake gmake cmocka pkgconf readline python-3.12.11 libstrophe curl gpgme glib2 gtk+3 libotr libassuan libgpg-error libgcrypt libsignal-protocol-c sqlite3 enchant2</code></pre>
141147
</section>
142148
<section>
143149
<a name="expl"></a>
144150
<h3>Explanations:</h3>
151+
152+
<p>Profanity is built using the <a href="https://mesonbuild.com">Meson</a> build system.</p>
145153

146154
<h4>Input files</h4>
147-
<p>configure.ac – Macro definitions to configure profanity for the target environment (autoconf)</p>
148-
<p>Makefile.am – Template Makefile (automake)</p>
155+
<p>meson.build – Definitions to setup profanity to build for the target environment</p>
156+
<p>meson_options.txt – Default settings for input options</p>
157+
158+
<p>These files are the inputs to generating the actual build definitions to compile Profanity.</p>
159+
160+
<h4>Preparing for compilation</h4>
161+
162+
<p>Once all needed dependencies are installed, setup a minimal build by using</p>
163+
164+
<pre><code>meson setup build_run</code></pre>
165+
166+
<p>This will result in an out of source build directory <code>build_run</code> being
167+
created.</p>
168+
169+
<h4>Build Options</h4>
170+
<p>Meson requires features to be <strong>explicitly enabled</strong>.
171+
Nothing is auto-enabled; if you want a feature, you must pass the
172+
corresponding <code>-Doption=enabled</code> flag.</p>
173+
174+
<p>The system libstrophe is used by default; if you instead want to
175+
automatically download and link against libstrophe HEAD from upstream
176+
Git, provide <code>-Dforce_fallback_for=libstrophe</code> flag.</p>
177+
178+
<table>
179+
<colgroup>
180+
<col style="width: 33%" />
181+
<col style="width: 33%" />
182+
<col style="width: 33%" />
183+
</colgroup>
184+
<thead>
185+
<tr>
186+
<th>Feature</th>
187+
<th>Description</th>
188+
<th>Meson option</th>
189+
</tr>
190+
</thead>
191+
<tbody>
192+
<tr>
193+
<td><strong>Notifications</strong></td>
194+
<td>Desktop notifications support</td>
195+
<td><code>-Dnotifications=enabled</code></td>
196+
</tr>
197+
<tr>
198+
<td><strong>Python Plugins</strong></td>
199+
<td>Support for Python plugins</td>
200+
<td><code>-Dpython-plugins=enabled</code></td>
201+
</tr>
202+
<tr>
203+
<td><strong>C Plugins</strong></td>
204+
<td>Support for C plugins</td>
205+
<td><code>-Dc-plugins=enabled</code></td>
206+
</tr>
207+
<tr>
208+
<td><strong>OTR</strong></td>
209+
<td>Off-the-Record encryption</td>
210+
<td><code>-Dotr=enabled</code></td>
211+
</tr>
212+
<tr>
213+
<td><strong>PGP</strong></td>
214+
<td>PGP encryption support</td>
215+
<td><code>-Dpgp=enabled</code></td>
216+
</tr>
217+
<tr>
218+
<td><strong>OMEMO</strong></td>
219+
<td>OMEMO encryption support</td>
220+
<td><code>-Domemo=enabled</code></td>
221+
</tr>
222+
<tr>
223+
<td><strong>OMEMO Backend</strong></td>
224+
<td>Select OMEMO backend library</td>
225+
<td><code>-Domemo-backend=libsignal\|libomemo-c</code></td>
226+
</tr>
227+
<tr>
228+
<td><strong>QR Code</strong></td>
229+
<td>OMEMO QR code display</td>
230+
<td><code>-Domemo-qrcode=enabled</code></td>
231+
</tr>
232+
<tr>
233+
<td><strong>Icons/Clipboard</strong></td>
234+
<td>GTK tray icons &amp; clipboard</td>
235+
<td><code>-Dicons-and-clipboard=enabled</code></td>
236+
</tr>
237+
<tr>
238+
<td><strong>GDK Pixbuf</strong></td>
239+
<td>Avatar scaling support</td>
240+
<td><code>-Dgdk-pixbuf=enabled</code></td>
241+
</tr>
242+
<tr>
243+
<td><strong>XScreenSaver</strong></td>
244+
<td>Idle time detection</td>
245+
<td><code>-Dxscreensaver=enabled</code></td>
246+
</tr>
247+
<tr>
248+
<td><strong>Spellcheck</strong></td>
249+
<td>Check spelling</td>
250+
<td><code>-Dspellcheck=enabled</code></td>
251+
</tr>
252+
<tr>
253+
<td><strong>Tests</strong></td>
254+
<td>Build unit tests</td>
255+
<td><code>-Dtests=true</code></td>
256+
</tr>
257+
<tr>
258+
<td><strong>Sanitizers</strong></td>
259+
<td>Run-time error detection</td>
260+
<td><code>-Db_sanitize=address,undefined</code></td>
261+
</tr>
262+
</tbody>
263+
</table>
264+
265+
<h4>Selecting OMEMO Backend</h4>
266+
267+
<p>When building with OMEMO support enabled, you can choose between two
268+
backend libraries: - <code>libsignal</code>: The default backend using
269+
<code>libsignal-protocol-c</code>. - <code>libomemo-c</code>: An
270+
alternative backend using <code>libomemo-c</code>.</p>
271+
272+
<p>Example of choosing the <code>libomemo-c</code> backend:</p>
273+
274+
<pre><code>meson setup build_run -Domemo=enabled -Domemo-backend=libomemo-c</code></pre>
149275

150-
<p>These files are the inputs to generating the actual configure script and Makefile required to configure
151-
and compile Profanity.</p>
152-
153-
<h4>Generating a configure script</h4>
154-
155-
<p>To generate the configure script:</p>
156-
157-
<pre><code>./bootstrap.sh</code></pre>
158-
159-
<p>This phase only needs to be run when changes have been made to configure.ac, however it does no harm to
160-
run it on every build. This phase also generates other files needed to create a config.h header
161-
(variables used in the main code), and a Makefile (used for compilation).</p>
162-
<p>Why not just write configure yourself, instead of writing configure.ac and generating one with
163-
bootstrap.sh? Take a look at the generated configure script and you'll see why, there's a lot of work
164-
involved in writing a configure script.</p>
165-
<p>The bootstrap.sh file is very simple, it just runs autoreconf --install see autoreconf</p>
166-
167-
<h4>Configuring</h4>
168-
169-
<p>Once the configure script has been generated, run it to configure profanity.</p>
170-
171-
<pre><code>./configure</code></pre>
172-
173-
<p>This will result in the following being generated, along with some other files:</p>
174-
175-
<pre><code>src/config.h
176-
Makefile</code></pre>
177276

178277
<h4>Compiling</h4>
179278
<p>The following step will then compile Profanity:</p>
180279

181-
<pre><code>make</code></pre>
280+
<pre><code>meson compile -C build_run</code></pre>
182281

183-
<p>Once you have run ./bootstrap.sh and ./configure once, if all you are doing is making code changes, then
184-
you only need to run make to recompile your changes.</p>
185-
<p>To perform a clean build (i.e. remove all compiled files and recompile)</p>
282+
<p>To clean the build directory before recompiling use:</p>
186283

187-
<pre><code>make clean
188-
make</code></pre>
284+
<pre><code>meson compile --clean -C build_run</code></pre>
189285

190286
<h4>Tests</h4>
191-
<p>All tests (unit and functional) can be run with:</p>
287+
<p>All (functional and unit) tests can be run with:</p>
192288

193-
<pre><code>make check</code></pre>
289+
<pre><code>meson test -C build_run</code></pre>
194290

195-
<p>Unit tests alone can be run with:</p>
291+
<p>Unit tests can be run with:</p>
196292

197-
<pre><code>make check-unit</code></pre>
293+
<pre><code>meson test -C build_run "unit tests"</code></pre>
198294

199295
<h4>Install</h4>
200296

201-
<p>Once you have compiled profanity with make, the executable will be available in the current directory:
297+
<p>Once you have compiled profanity, the executable can be run using:
202298
</p>
203-
<pre><code>./profanity</code></pre>
299+
<pre><code>./build_run/profanity</code></pre>
204300

205301
<p>To install this version on your system, i.e. to be able to run it from anywhere:</p>
206302

207-
<pre><code>sudo make install</code></pre>
303+
<pre><code>sudo meson install -C build_run</code></pre>
208304

209305
<p>This step is not really necessary when doing development (i.e. you can always run the version just
210306
compiled in the project directory), unless you want to have your development version available to any

0 commit comments

Comments
 (0)