building.dox 8.32 KB
Newer Older
Peter Hutterer's avatar
Peter Hutterer committed
1 2 3
/**
@page building_libinput libinput build instructions

4 5
@tableofcontents

Peter Hutterer's avatar
Peter Hutterer committed
6 7 8
Instructions on how to build libinput and its tools and how to build against
libinput.

9 10 11 12
The build instruction on this page detail how to overwrite your
system-provided libinput with one from the git repository, see
see @ref reverting_install to revert to the previous state.

Peter Hutterer's avatar
Peter Hutterer committed
13 14
@section building Building libinput

15 16 17 18 19 20 21 22 23 24 25 26 27 28
libinput uses [meson](https://www.mesonbuild.com) and
[ninja](https://www.ninja-build.org). A build is usually the three-step
process below.  A successful build requires the @ref
building_dependencies to be installed before running meson.

@code
$> git clone git://anongit.freedesktop.org/git/wayland/libinput
$> cd libinput
$> meson --prefix=/usr builddir/
$> ninja -C builddir/
$> sudo ninja -C builddir/ install
$> sudo udevadm hwdb --update
@endcode

29 30 31 32
Additional options may also be specified. For example:
@code
$> meson --prefix=/usr -Ddocumentation=false -Dlibwacom=false builddir/
@endcode
33

34 35
The ```prefix``` or other options can be changed later with the
```mesonconf``` command. For example:
36
@code
37
$> mesonconf builddir/ -Dprefix=/some/other/prefix -Ddocumentation=true
38 39 40 41
$> ninja -C builddir
$> sudo ninja -C builddir/ install
@endcode

42 43 44 45 46 47 48 49 50 51
Running ``mesonconf builddir/`` with no other arguments lists all
configurable options meson provides.

To rebuild from scratch, simply remove the build directory and run meson
again:
@code
$> rm -r builddir/
$> meson --prefix=....
@endcode

52 53 54 55 56 57 58
@subsection verifying_install Verifying the install

To verify the install worked correctly, check that libinput.so.x.x.x is in
the library path and that all symlinks point to the new library.
<pre>
$> ls -l /usr/lib64/libinput.*
-rwxr-xr-x 1 root root    946 Apr 28  2015 /usr/lib64/libinput.la
59 60 61
lrwxrwxrwx 1 root root     19 Feb  1 15:12 /usr/lib64/libinput.so -> libinput.so.10.13.0
lrwxrwxrwx 1 root root     19 Feb  1 15:12 /usr/lib64/libinput.so.10 -> libinput.so.10.13.0
-rwxr-xr-x 1 root root 204992 Feb  1 15:12 /usr/lib64/libinput.so.10.13.0
62 63
</pre>

Peter Hutterer's avatar
Peter Hutterer committed
64
@subsection reverting_install Reverting to the system-provided libinput package
65 66 67 68 69 70 71

The recommended way to revert to the system install is to use the package
manager to reinstall the libinput package. In some cases, this may leave
files in the system (e.g. ```/usr/lib/libinput.la```) but these files are
usually harmless. To definitely remove all files, run the following command
from the libinput source directory:

72 73
@code
$> sudo ninja -C builddir/ uninstall
74
# WARNING: Do not restart the computer/X/the Wayland compositor after
75 76 77 78 79 80 81 82 83 84
# uninstall, reinstall the system package immediately!
@endcode

The following commands reinstall the current system package for libinput,
overwriting manually installed files.

<ul>
<li><b>Debian/Ubuntu</b> based distributions: ```sudo apt-get install
--reinstall libinput```</li>
<li><b>Fedora 22</b> and later: ```sudo dnf reinstall libinput```</li>
85 86
<li><b>RHEL/CentOS/Fedora 21</b> and earlier: ```sudo yum reinstall libinput```</li>
<li><b>openSUSE</b>: ```sudo zypper install --force libinput10```</li>
87 88
<li><b>Arch</b>: ```sudo packman -S libinput```</li>
</ul>
89

90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
@subsection building_selinux SELinux adjustments

On systems with SELinux, overwriting the distribution-provided package with
a manually built libinput may cause SELinux denials. This usually manifests
when gdm does not start because it is denied access to libinput. The journal
shows a log message in the form of:

<pre>
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
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
</pre>

The summary of this error message is that gdm's gnome-shell runs in the
```system_u:system_r:xdm_t``` context but libinput is installed with the
context ```unconfined_u:object_r:user_home_t```.

To avoid this issue, restore the SELinux context for any system files.

<pre>
$> sudo restorecon /usr/lib*/libinput.so.*
</pre>

This issue is tracked in https://github.com/mesonbuild/meson/issues/1967.

114 115 116 117 118 119 120 121 122 123 124
@subsection building_dependencies Build dependencies

libinput has a few build-time dependencies that must be installed prior to
running configure. In most cases, it is sufficient to install the
dependencies that your distribution uses to build the libinput package.
These can be installed with one of the following commands:

<ul>
<li><b>Debian/Ubuntu</b> based distributions: ```sudo apt-get build-dep
libinput```</li>
<li><b>Fedora 22</b> and later: ```sudo dnf builddep libinput```</li>
125 126 127 128 129 130 131 132 133
<li><b>RHEL/CentOS/Fedora 21</b> and earlier: ```sudo yum-builddep libinput```</li>
<li><b>openSUSE</b>:
<pre>
$> sudo zypper modifyrepo --enable `zypper repos | grep source | awk '{print $5}'`
$> sudo zypper source-install -d libinput10
$> sudo zypper install autoconf automake libtool
$> sudo zypper modifyrepo --disable `zypper repos | grep source | awk '{print $5}'`
</pre>
</li>
134 135
<li><b>Arch</b>:
<pre>
136
$> sudo pacman -S asp
137
$> cd $(mktemp -d)
138 139 140
$> asp export libinput
$> cd libinput
$> makepkg --syncdeps --nobuild --noextract
141 142 143 144 145 146 147 148
</pre>
</li>
</ul>

If dependencies are missing, a message ```No package 'foo' found``` will be
shown during the configure stage. See
<a href="https://who-t.blogspot.com.au/2014/05/configure-fails-with-no-package-foo.html">this blog post here</a>.
for instructions on how to fix it.
Peter Hutterer's avatar
Peter Hutterer committed
149 150 151 152 153 154

@subsection building_libwacom Building without libwacom

libwacom is required by libinput's tablet code to gather additional
information about tablets that is not available from the kernel device
itself. libwacom is required by default but can be skipped when @ref
155 156 157 158 159 160
building.

@code
$> meson --prefix=/usr -Dlibwacom=false builddir
@endcode

161 162 163 164
It is not recommended to disable libwacom unless libinput is used in an
environment where tablet support is not required. libinput provides tablet
support even without libwacom, but some features may be missing or working
differently.
Peter Hutterer's avatar
Peter Hutterer committed
165

Peter Hutterer's avatar
Peter Hutterer committed
166
@subsection building_debug_gui Building without the graphical helper tool
Peter Hutterer's avatar
Peter Hutterer committed
167

168 169 170 171 172 173
The @ref tools provide commandline features as well as graphical debugging
features. To keep dependencies in check on some builds, the graphical
features of the @ref tools can be disabled. By default, the `debug-gui`
feature of the `libinput` tool is enabled and if the required libraries are
not available, the build will fail. If the feature is not required, use the
``--disable-debug-gui`` argument when @ref building.
Peter Hutterer's avatar
Peter Hutterer committed
174

175
@code
176
$> meson --prefix=/usr -Ddebug-gui=false builddir
177 178
@endcode

179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
@subsection building_autotools Building with autotools

<b>libinput no longer supports building with autotools.</b> These
instructions are kept for users for libinput versions up to 1.8.x.

A build with automake is usually the process below. A successful build
requires the @ref building_dependencies to be installed at configure
time.

@code
$> git clone git://anongit.freedesktop.org/git/wayland/libinput
$> cd libinput
$> ./autogen.sh --prefix=/usr --libdir=/usr/lib64
$> make
$> sudo make install
$> sudo udevadm hwdb --update
@endcode

@note On Debian-based distributions including Ubuntu and its derivatives skip the
```--libdir=/usr/lib64``` argument.

To uninstall libinput as detailed in section @ref reverting_install, run

@code
$> sudo make uninstall
# WARNING: Do not restart the computer/X/the Wayland compositor after make
# uninstall, reinstall the system package immediately!
@endcode

To disable libwacom as detailed in section @ref building_libwacom, run

@code
$> ./autogen.sh --disable-libwacom --prefix=/usr --libdir=/usr/lib64
@endcode

To disable the graphical helper tool as detailed in section @ref
Peter Hutterer's avatar
Peter Hutterer committed
215
building_debug_gui, run
216

Peter Hutterer's avatar
Peter Hutterer committed
217
@code
218
$> ./autogen.sh --disable-debug-gui --prefix=/usr --libdir=/usr/lib64
Peter Hutterer's avatar
Peter Hutterer committed
219 220
@endcode

221

Peter Hutterer's avatar
Peter Hutterer committed
222 223 224 225 226 227 228 229 230
@section building_against Building against libinput

libinput provides a
[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file.
Software that uses libinput should use pkg-config and the
`PKG_CHECK_MODULES` autoconf macro.
Otherwise, the most rudimentary way to compile and link a program against
libinput is:

231
@code
Peter Hutterer's avatar
Peter Hutterer committed
232
    gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
233
@endcode
Peter Hutterer's avatar
Peter Hutterer committed
234 235 236 237 238

For further information on using pkgconfig see the pkg-config documentation.

*/