doc: add build instructions

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 75 insertions, 0 deletions

diff --git a/doc/building.dox b/doc/building.dox
new file mode 100644
index 0000000..5b4ca52
--- /dev/null
+++ b/doc/building.dox
@@ -0,0 +1,75 @@
+/**
+@page building_libinput libinput build instructions
+
+Instructions on how to build libinput and its tools and how to build against
+libinput.
+
+@section building Building libinput
+
+libinput uses automake, a build is usually the following three-step process
+
+@code
+$> git clone git://anongit.freedesktop.org/git/wayland/libinput
+$> cd libinput
+$> ./autogen.sh --prefix=/usr --libdir=/usr/lib64
+$> make
+$> sudo make install
+@endcode
+
+@note On Debian-based distributions including Ubuntu and its derivatives skip the
+```--libdir=/usr/lib64``` argument.
+
+A description on how to fix "No package 'foo' found" errors during the
+configure stage is available
+<a href="https://who-t.blogspot.com.au/2014/05/configure-fails-with-no-package-foo.html">in
+this blog post here</a>.
+
+@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
+building with the ``--disable-libwacom`` argument.
+
+@code
+$> ./autogen.sh --disable-libwacom --prefix=/usr --libdir=/usr/lib64
+@endcode
+
+Disabling libwacom is safe to do for environments where full tablet support
+is not required. Note that libinput provides tablet support even without
+libwacom, but some features may be missing or working differently.
+
+@subsection buildling_event-gui Building the graphical helper tool
+
+Only the commandline @ref tools are installed by distributions. The
+@ref event-gui graphical helper tools is only available in the source
+repository.
+
+The graphical helper tool is optional by default and requires extra
+libraries to build. If these libraries are not detected, the tool will not
+be built. If you need the tool for debugging purposes, use the
+``--enable-event-gui`` argument when @ref building.
+
+@code
+$> ./autogen.sh --enable-event-gui --prefix=/usr --libdir=/usr/lib64
+@endcode
+
+As usual, any missing library headers will then trigger an error and can be
+addressed one-by-one.
+
+
+@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:
+
+    gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`
+
+For further information on using pkgconfig see the pkg-config documentation.
+
+*/
+