Debian Codegraph @

doc/user/building.rst

raw
1 .. _building_libinput:
2
3 ==============================================================================
4 libinput build instructions
5 ==============================================================================
6
7
8 .. contents::
9 :local:
10 :backlinks: entry
11
12 Instructions on how to build libinput and its tools and how to build against
13 libinput.
14
15 The build instruction on this page detail how to overwrite your
16 system-provided libinput with one from the git repository, see
17 see :ref:`reverting_install` to revert to the previous state.
18
19 .. _distribution_repos:
20
21 ------------------------------------------------------------------------------
22 Distribution repositories for libinput from git
23 ------------------------------------------------------------------------------
24
25 Some distributions provide package repositories for users that want to test
26 the latest libinput without building it manually.
27
28 .. note:: The list below is provided for convenience. The libinput community
29 cannot provide any guarantees that the packages in those repositories are
30 correct, up-to-date and/or unmodified from the git branch. Due dilligence
31 is recommended.
32
33 The following repositories provide an up-to-date package for libinput:
34
35 - **Arch:** https://aur.archlinux.org/packages/libinput-git/
36 - **Fedora:** https://copr.fedorainfracloud.org/coprs/whot/libinput-git/
37
38 Please follow the respective repositories for instructions on how to enable
39 the repository and install libinput.
40
41
42 .. _building:
43
44 ------------------------------------------------------------------------------
45 Building libinput
46 ------------------------------------------------------------------------------
47
48 libinput uses `meson <https://www.mesonbuild.com>`_ and
49 `ninja <https://www.ninja-build.org>`_. A build is usually the three-step
50 process below. A successful build requires the
51 :ref:`building_dependencies` to be installed before running meson.
52
53
54 ::
55
56 $> git clone https://gitlab.freedesktop.org/libinput/libinput
57 $> cd libinput
58 $> meson setup --prefix=/usr builddir/
59 $> ninja -C builddir/
60 $> sudo ninja -C builddir/ install
61
62
63 When running libinput versions 1.11.x or earlier, you must run
64
65 ::
66
67 $> sudo systemd-hwdb update
68
69
70 Additional options may also be specified. For example:
71
72 ::
73
74 $> meson setup --prefix=/usr -Ddocumentation=false builddir/
75
76
77 We recommend that users disable the documentation, it's not usually required
78 for testing and reduces the number of dependencies needed.
79
80 The ``prefix`` or other options can be changed later with the
81 ``meson configure`` command. For example:
82
83 ::
84
85 $> meson configure builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
86 $> ninja -C builddir
87 $> sudo ninja -C builddir/ install
88
89
90 Running ``meson configure builddir/`` with no other arguments lists all
91 configurable options meson provides.
92
93 To rebuild from scratch, simply remove the build directory and run meson
94 again:
95
96 ::
97
98 $> rm -r builddir/
99 $> meson setup --prefix=....
100
101
102 .. _verifying_install:
103
104 ..............................................................................
105 Verifying the install
106 ..............................................................................
107
108 To verify the install worked correctly, check that libinput.so.x.x.x is in
109 the library path and that all symlinks point to the new library.
110
111 ::
112
113 $> ldconfig -p | grep libinput | awk '{print $NF}' | xargs ls -l
114 lrwxrwxrwx 1 root root 14 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so -> libinput.so.10
115 lrwxrwxrwx 1 root root 19 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so.10 -> libinput.so.10.13.0
116 -rwxr-xr-x 1 root root 1064144 lug 22 13:06 /usr/lib/x86_64-linux-gnu/libinput.so.10.13.0
117
118 .. _reverting_install:
119
120 ..............................................................................
121 Reverting to the system-provided libinput package
122 ..............................................................................
123
124 The recommended way to revert to the system install is to use the package
125 manager to reinstall the libinput package. In some cases, this may leave
126 files in the system (e.g. ``/usr/lib/libinput.la``) but these files are
127 usually harmless. To definitely remove all files, run the following command
128 from the libinput source directory:
129
130
131 ::
132
133 $> sudo ninja -C builddir/ uninstall
134 # WARNING: Do not restart the computer/X/the Wayland compositor after
135 # uninstall, reinstall the system package immediately!
136
137
138 The following commands reinstall the current system package for libinput,
139 overwriting manually installed files.
140
141 - **Debian/Ubuntu** based distributions: ``sudo apt-get install --reinstall libinput``
142 - **Fedora 22** and later: ``sudo dnf reinstall libinput``
143 - **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum reinstall libinput``
144 - **openSUSE**: ``sudo zypper install --force libinput10``
145 - **Arch**: ``sudo pacman -S libinput``
146
147 .. _building_selinux:
148
149 ..............................................................................
150 SELinux adjustments
151 ..............................................................................
152
153 .. note:: This section only applies to meson version < 0.42.0
154
155 On systems with SELinux, overwriting the distribution-provided package with
156 a manually built libinput may cause SELinux denials. This usually manifests
157 when gdm does not start because it is denied access to libinput. The journal
158 shows a log message in the form of:
159
160
161 ::
162
163 May 25 15:28:42 localhost.localdomain audit[23268]: AVC avc: denied { execute } for pid=23268 comm="gnome-shell" path="/usr/lib64/libinput.so.10.12.2" dev="dm-0" ino=1709093 scontext=system_u:system_r:xdm_t:s0-s0:c0.c1023 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file permissive=0
164 May 25 15:28:42 localhost.localdomain org.gnome.Shell.desktop[23270]: /usr/bin/gnome-shell: error while loading shared libraries: libinput.so.10: failed to map segment from shared object
165
166
167 The summary of this error message is that gdm's gnome-shell runs in the
168 ``system_u:system_r:xdm_t`` context but libinput is installed with the
169 context ``unconfined_u:object_r:user_home_t``.
170
171 To avoid this issue, restore the SELinux context for any system files.
172
173
174 ::
175
176 $> sudo restorecon /usr/lib*/libinput.so.*
177
178
179 This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.
180
181 .. _building_dependencies:
182
183 ------------------------------------------------------------------------------
184 Build dependencies
185 ------------------------------------------------------------------------------
186
187 libinput has a few build-time dependencies that must be installed prior to
188 running meson.
189
190 .. hint:: The build dependencies for some distributions can be found in the
191 `GitLab Continuous Integration file <https://gitlab.freedesktop.org/libinput/libinput/blob/main/.gitlab-ci.yml>`_.
192 Search for **FEDORA_PACKAGES** in the **variables:** definition
193 and check the list for an entry for your distribution.
194
195 In most cases, it is sufficient to install the dependencies that your
196 distribution uses to build the libinput package. These can be installed
197 with one of the following commands:
198
199 - **Debian/Ubuntu** based distributions: ``sudo apt-get build-dep libinput``
200 - **Fedora 22** and later: ``sudo dnf builddep libinput``
201 - **RHEL/CentOS/Fedora 21** and earlier: ``sudo yum-builddep libinput``
202 - **openSUSE**: ::
203
204 $> sudo zypper modifyrepo --enable ``zypper repos | grep source | awk '{print $5}'``
205 $> sudo zypper source-install -d libinput10
206 $> sudo zypper install autoconf automake libtool
207 $> sudo zypper modifyrepo --disable ``zypper repos | grep source | awk '{print $5}'``
208
209
210 - **Arch**: ::
211
212 $> sudo pacman -S asp
213 $> cd $(mktemp -d)
214 $> asp export libinput
215 $> cd libinput
216 $> makepkg --syncdeps --nobuild --noextract
217
218
219
220 If dependencies are missing, meson shows a message ``No package 'foo'
221 found``. See
222 `this blog post here <https://who-t.blogspot.com/2018/07/meson-fails-with-native-dependency-not-found.html>`_
223 for instructions on how to fix it.
224
225 ..............................................................................
226 Build dependencies per distribution
227 ..............................................................................
228
229
230 .. include:: dependencies.rst
231
232
233 .. _building_conditional:
234
235 ------------------------------------------------------------------------------
236 Conditional builds
237 ------------------------------------------------------------------------------
238
239 libinput supports several meson options to disable parts of the build. See
240 the ``meson_options.txt`` file in the source tree for a full list of
241 available options. The default build enables most options and thus requires
242 more build dependencies. On systems where build dependencies are an issue,
243 options may be disabled with this meson command: ::
244
245 meson setup --prefix=/usr -Dsomefeature=false builddir
246
247 Where ``-Dsomefeature=false`` may be one of:
248
249 - ``-Ddocumentation=false``
250 Disables the documentation build (this website). Building the
251 documentation is only needed on the maintainer machine.
252 - ``-Dtests=false``
253 Disables the test suite. The test suite is only needed on developer
254 systems.
255 - ``-Ddebug-gui=false``
256 Disables the ``libinput debug-gui`` helper tool (see :ref:`tools`),
257 dropping GTK and other build dependencies. The debug-gui is only
258 required for troubleshooting.
259 - ``-Dlibwacom=false``
260 libwacom is required by libinput's tablet code to gather additional
261 information about tablets that is not available from the kernel device.
262 It is not recommended to disable libwacom unless libinput is used in an
263 environment where tablet support is not required. libinput provides tablet
264 support even without libwacom, but some features may be missing or working
265 differently.
266
267 .. _building_against:
268
269 ------------------------------------------------------------------------------
270 Building against libinput
271 ------------------------------------------------------------------------------
272
273 libinput provides a
274 `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ file.
275 Software that uses autotools should use the ``PKG_CHECK_MODULES`` autoconf
276 macro: ::
277
278 PKG_CHECK_MODULES(LIBINPUT, "libinput")
279
280 Software that uses meson should use the ``dependency()`` function: ::
281
282 pkgconfig = import('pkgconfig')
283 dep_libinput = dependency('libinput')
284
285 Software that uses CMake should use: ::
286
287 find_package(Libinput)
288 target_link_libraries(myprogram PRIVATE Libinput::Libinput)
289
290 Otherwise, the most rudimentary way to compile and link a program against
291 libinput is:
292
293
294 ::
295
296 gcc -o myprogram myprogram.c ``pkg-config --cflags --libs libinput``
297
298
299 For further information on using pkgconfig see the pkg-config documentation.