README.linux
************

Introduction
============

This file describes the steps required to build fswatch on a supported GNU/Linux
system.

The supported monitors on GNU/Linux systems are:

  * The inotify monitor (on Linux kernels > 2.6.13).
  * The fanotify monitor, when the build host exposes the required fanotify
    headers and symbols.
  * The poll monitor.

The availability of the inotify API is checked by configure and it will be built
into fswatch when found.  When available, the inotify monitor is the default
choice on GNU/Linux systems.

The fanotify monitor is also detected at configure time, but it is not selected
as the default Linux monitor.  Users must request it explicitly:

    $ fswatch -m fanotify_monitor [paths] ...

The fanotify monitor is intended for Linux-specific workflows that need process
attribution.  It uses file-handle based fanotify events and therefore depends on
kernel, C library, and filesystem support for FID/name reporting.  Some
fanotify modes and metadata, including pidfd reporting, may require newer
kernels or additional privileges.  When the kernel omits process attribution,
fswatch leaves the process fields empty.

The current fanotify monitor does not provide macOS FSEvents-style recursive
tree monitoring with a single mark on an arbitrary directory.  Linux fanotify
directory marks report events for the marked directory and, with
`FAN_EVENT_ON_CHILD`, its immediate children.  They do not report events for
grandchildren or deeper descendants.  For this reason, `fswatch -r` still marks
subdirectories explicitly.  Avoiding recursive mark expansion requires
fanotify mount or filesystem marks, which have broader scope and different
permission constraints.

The list of monitors built into libfswatch can be read in the help message of
fswatch:

    $ fswatch --help

Installation
============

See the INSTALL file for detailed information about how to configure and install
fswatch.

fswatch is a C++ program and a C++ compiler compliant with the C++11 standard is
required to compile it.  Reasonably recent GNU/Linux distributions usually ship
at least two such compilers:

  * GCC.
  * Clang.

Please, check your distribution documentation to find an appropriate C++
compiler and how to install it.

The configure script enforces an ordered compiler search list and clang++ will
be used first if available.  If you do not like this choice and wish to use
another compiler set the value of the CXX environment variable to the name of
your compiler binary.  If, for example, you wish to use the g++ compiler, then
use this command to configure the build:

    $ ./configure CXX=g++

-----

Copyright (c) 2014-2026 Enrico M. Crisostomo

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 3, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.
