[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg?style=flat)](https://github.com/emcrisostomo/fswatch/blob/master/COPYING)

README
======

`fswatch` is a file change monitor that receives notifications when the contents
of the specified files or directories are modified.  `fswatch` implements
several monitors:

  * A monitor based on the _File System Events API_ of Apple OS X.
  * A monitor based on _kqueue_, a notification interface introduced in FreeBSD
    4.1 (and supported on most *BSD systems, including OS X).
  * A monitor based on the _File Events Notification_ API of the Solaris kernel
    and its derivatives.
  * A monitor based on _inotify_, a Linux kernel subsystem that reports file
    system changes to applications.
  * A monitor based on _ReadDirectoryChangesW_, a Microsoft Windows API that
    reports changes to a directory.
  * A monitor which periodically stats the file system, saves file modification
    times in memory, and manually calculates file system changes (which works
    anywhere `stat (2)` can be used).

`fswatch` should build and work correctly on any system shipping either of the
aforementioned APIs.

Table of Contents
-----------------

  * [libfswatch](#libfswatch)
  * [Features](#features)
  * [Limitations](#limitations)
  * [Getting fswatch](#getting-fswatch)
  * [Building from Source](#building-from-source)
  * [Installation](#installation)
  * [Documentation](#documentation)
  * [Localization](#localization)
  * [Usage](#usage)
  * [Contributing](#contributing)
  * [Bug Reports](#bug-reports)

libfswatch
----------

`fswatch` is a frontend of `libfswatch`, a library with C and C++ binding.  More
information on `libfswatch` can be found [here][README.libfswatch.md].

[README.libfswatch.md]: README.libfswatch.md

Features
--------

`fswatch` main features are:

  * Support for many OS-specific APIs such as kevent, inotify, and FSEvents.
  * Recursive directory monitoring.
  * Path filtering using including and excluding regular expressions.
  * Customizable record format.
  * Support for periodic idle events.

Limitations
-----------

The limitations of `fswatch` depend largely on the monitor being used:

  * The **FSEvents** monitor, available only on OS X, has no known limitations,
    and scales very well with the number of files being observed.

  * The **File Events Notification** monitor, available on Solaris kernels and
    its derivatives, has no known limitations.

  * The **kqueue** monitor, available on any \*BSD system featuring kqueue,
    requires a file descriptor to be opened for every file being watched.  As a
    result, this monitor scales badly with the number of files being observed,
    and may begin to misbehave as soon as the `fswatch` process runs out of file
    descriptors.  In this case, `fswatch` dumps one error on standard error for
    every file that cannot be opened.

  * The **inotify** monitor, available on Linux since kernel 2.6.13, may suffer
    a queue overflow if events are generated faster than they are read from the
    queue.  In any case, the application is guaranteed to receive an overflow
    notification which can be handled to gracefully recover.  `fswatch`
    currently throws an exception if a queue overflow occurs.  Future versions
    will handle the overflow by emitting proper notifications.

  * The **Windows** monitor can only establish a watch _directories_, not files.
    To watch a file, its parent directory must be watched in order to receive
    change events for all the directory's children, _recursively_ at any depth.
    Optionally, change events can be filtered to include only changes to the
    desired file.

  * The **poll** monitor, available on any platform, only relies on
    available CPU and memory to perform its task.  The performance of this
    monitor degrades linearly with the number of files being watched.

Usage recommendations are as follows:

  * On OS X, use only the `FSEvents` monitor (which is the default behaviour).

  * On Solaris and its derivatives use the _File Events Notification_ monitor.

  * On Linux, use the `inotify` monitor (which is the default behaviour).

  * If the number of files to observe is sufficiently small, use the `kqueue`
    monitor.  Beware that on some systems the maximum number of file descriptors
    that can be opened by a process is set to a very low value (values as low as
    256 are not uncommon), even if the operating system may allow a much larger
    value.  In this case, check your OS documentation to raise this limit on
    either a per process or a system-wide basis.

  * If feasible, watch directories instead of files.  Properly crafting the
    receiving side of the events to deal with directories may sensibly reduce
    the monitor resource consumption.

  * On Windows, use the `windows` monitor.

  * If none of the above applies, use the poll monitor.  The authors' experience
    indicates that `fswatch` requires approximately 150 MB of RAM memory to
    observe a hierarchy of 500.000 files with a minimum path length of 32
    characters.  A common bottleneck of the poll monitor is disk access, since
    `stat()`-ing a great number of files may take a huge amount of time.  In
    this case, the latency should be set to a sufficiently large value in order
    to reduce the performance degradation that may result from frequent disk
    access.

Getting fswatch
---------------

A regular user may be able to fetch `fswatch` from the package manager of your
OS or a third-party one.  If you are looking for `fswatch` for OS X, you can
install it using either [MacPorts] or [Homebrew]:

```
# MacPorts
$ port install fswatch

# Homebrew
$ brew install fswatch
```

Check your favourite package manager and let us know if `fswatch` is missing
there.

[MacPorts]: https://www.macports.org
[Homebrew]: http://brew.sh

Building from Source
--------------------

A user who wishes to build `fswatch` should get a [release tarball][release].
A release tarball contains everything a user needs to build `fswatch` on their
system, following the instructions detailed in the Installation section below
and the `INSTALL` file.

A developer who wishes to modify `fswatch` should get the sources (either from a
source tarball or cloning the repository) and have the GNU Build System
installed on their machine.  Please read `README.gnu-build-system` to get further
details about how to bootstrap `fswatch` from sources on your machine.

Getting a copy of the source repository is not recommended unless you are a
developer, you have the GNU Build System installed on your machine, and you know
how to bootstrap it on the sources.

[release]: https://github.com/emcrisostomo/fswatch/releases

Installation
------------

See the `INSTALL` file for detailed information about how to configure and
install `fswatch`.  Since the `fswatch` builds and uses dynamic libraries, in
some platforms you may need to perform additional tasks before you can use
`fswatch`:

  * Make sure the installation directory of dynamic libraries (`$PREFIX/lib`) is
    included in the lookup paths of the dynamic linker of your operating system.
    The default path, `/usr/local/lib`, will work in nearly every operating
    system.
  * Refreshing the links and cache to the dynamic libraries may be required.  In
    GNU/Linux systems you may need to run `ldconfig`:

        $ ldconfig

`fswatch` is a C++ program and a C++ compiler compliant with the C++11 standard
is required to compile it.  Check your OS documentation for information about
how to install the C++ toolchain and the C++ runtime.

No other software packages or dependencies are required to configure and install
`fswatch` but the aforementioned APIs used by the file system monitors.

Documentation
-------------

`fswatch` provides the following [documentation]:

  * Texinfo documentation, included with the distribution.
  * HTML documentation.
  * PDF documentation.
  * A [wiki] page.
  * A man page.

`fswatch` official documentation is provided in Texinfo format.  This is the
most comprehensive source of information about `fswatch` and the only
authoritative one.  The man page, in particular, is a stub that suggests the
user to use the info page instead.

If you are installing `fswatch` using a package manager and you would like the
PDF manual to be bundled into the package, please send a feature request to the
package maintainer.

[documentation]: http://emcrisostomo.github.io/fswatch/doc
[wiki]: https://github.com/emcrisostomo/fswatch/wiki

Localization
------------

`fswatch` is localizable and internally uses GNU `gettext` to decouple
localizable string from their translation.  The currently available locales are:

  * English (`en`).
  * Italian (`it`).
  * Spanish (`es`).

To build `fswatch` with localization support, you need to have `gettext`
installed on your system.  If `configure` cannot find `<libintl.h>` or the
linker cannot find `libintl`, then you may need to manually provide their
location to `configure`, usually using the `CPPFLAGS` and the `LDFLAGS`
variables.  See `README.osx` for an example.

If `gettext` is not available on your system, `fswatch` shall build correctly,
but it will lack localization support and the only available locale will be
English.

Usage
-----

`fswatch` accepts a list of paths for which change events should be received:

    $ fswatch [options] ... path-0 ... path-n

The event stream is created even if any of the paths do not exist yet.  If they
are created after `fswatch` is launched, change events will be properly
received.  Depending on the watcher being used, newly created paths will be
monitored after the amount of configured latency has elapsed.

The output of `fswatch` can be piped to other program in order to process it
further:

    $ fswatch -0 path | while read -d "" event \
      do \
        // do something with ${event}
      done

To run a command when a set of change events is printed to standard output but
no event details are required, then the following command can be used:

    $ fswatch -o path | xargs -n1 -I{} program

The behaviour is consistent with earlier versions of `fswatch` (v. 0.x).
Please, read the _Compatibility Issues with fswatch v. 0.x_ section for further
information.

By default `fswatch` chooses the best monitor available on the current platform,
in terms of performance and resource consumption.  If the user wishes to specify
a different monitor, the `-m` option can be used to specify the monitor by name:

    $ fswatch -m kqueue_monitor path

The list of available monitors can be obtained with the `-h` option.

For more information, refer to the `fswatch` documentation.

Contributing
------------

Everybody is welcome to contribute to `fswatch`.  Please, see
[`CONTRIBUTING`][contrib] for further information.

[contrib]: CONTRIBUTING.md

Bug Reports
-----------

Bug reports can be sent directly to the authors.

Contact the Authors
-------------------

The author can be contacted on IRC, using the Freenode `#fswatch` channel.

-----

Copyright (c) 2013-2017 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/>.

README.bsd
**********

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

The kqueue-based monitor should be compatible with any *BSD release with support
for kqueue.  So far, however, the author has only tested this release on FreeBSD
v. >= 10.0.  Feedback on different *BSD systems is much appreciated and will
benefit other users as well.

-----

Copyright (c) 2014-2015 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/>.

README.codestyle
================

The indent style used by `fswatch` is a custom Allman (BSD) style.  The code is
formatted using NetBeans with the following format settings:

    Indents
    Indent Size = 2
    Expand Tabs to Spaces = true
    Tab Size = 2
    Statement Continuation = 2
    Constructor Continuation = 2
    Preprocessor Directive = Preprocessor
    # at Start Line = true
    Indent Namespaces = true
    Indent Case Statements = false
    Absolute Label Indentation = true
    Indent Visibility = None
    Keep Extra Spaces = false

    Braces Placement
    Namespace Declaration = New Line
    Class Declaration = New Line
    Function Declaration = New Line
    Ignore Empty Function = false
    Lambda = New Line
    "switch" statement = New Line
    Other = New Line

    Multiline Alignment
    Function Parameters = true
    Function Call Arguments = true
    Array Initializer = false
    "for" Statement = true
    "if" Condition = true
    "while" Condition = true
    Other Parenthesis = false

    New Line
    Function Name = false
    "catch" = true
    "else" = true
    "while" = true

    Spaces Before Keywords
    "catch" = true
    "else" = true
    "while" = true

    Spaces Before Parentheses
    Function Declaration = false
    Function Call = false
    "catch" = true
    "for" = true
    "if" = true
    "switch" = true
    "while" = true
    Other Keywords = true

    Spaces Around Operators
    Assignment Operators = true
    Binary Operators = true
    Ternary Operators = true
    Unary Operators = false

    Spaces Before Left Braces
    Class Declaration = true
    Function Declaration = true
    Lambda = true
    Array Initializer = false
    "catch" = true
    "do" = true
    "else" = true
    "for" = true
    "if" = true
    "switch" = true
    "try" = true
    "while" = true

    Spaces Within Parentheses
    Function Declaration = false
    Function Call = false
    Braces = false
    Parentheses = false
    "catch" = false
    "for" = false
    "if" = false
    "switch" = false
    Type Cast = false
    "while" = false

    Other Spaces
    Before Comma = false
    After Comma = true
    Before Semicolon = false
    After Semicolon = true
    Before Colon = true
    After Colon = true
    After Type Cast = true
    After operator Keyword = false

    Blank Lines
    Before Class = 1
    After Class Header = 0
    Before Function = 1

    Other
    Add Leading Star in = true
    Toggle block comment = false
    Insert 'inline' keyword = false

README.freebsd
**************

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

This file describes the steps required to build this bundle on a supported
FreeBSD system.  See README for more information about the tested
configurations.

The kqueue-based monitor should be compatible with any *BSD release with support
for kqueue.  So far, however, the author has only tested this release on FreeBSD
v. >= 10.0.  Feedback on different *BSD systems is much appreciated and will
benefit other users as well.

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.  FreeBSD v. >= 10.0 ships by default with the CLang
compiler suite which builds this package correctly.  The GCC compiler collection
shipped with FreeBSD, however, is not C++11 compliant and cannot build this
package.

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-2015 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/>.

README.gnu-build-system
=======================

Introduction
------------

`fswatch` is built using the GNU Build System (a.k.a. the Autotools) and
developers willing to modify the configuration files must have the GNU Build
System installed in order to do so.

For further information about the GNU Build System and its use, please refer to
its official documentation.

Installing the GNU Build System
-------------------------------

To install the GNU Build System, the following operations must be performed:

  * Get the GNU Build System components:
    - [Autoconf] (>= v. 2.69).
    - [Automake]: (>= v. 1.14.1).
    - [Libtool]: (>= v. 2.4.2).
    - [Gettext]: (>= v. 0.19.4).

  * Install the packages in the following order:
    - Autoconf
    - Automake
    - Libtool
    - Gettext

  * From now on, `<bundle>` will indicate any of the above-mentioned
     components.

  * Grab the sources:

        $ wget <sources-url>

  * Uncompress the source bundle:

        $ gunzip <bundle>.tar.gz
        $ tar -xf <bundle>.tar

  * Configure the GNU Build System using the provided `autogen.sh` script:

        $ ./autogen.sh

    Whenever any component of the GNU Build System is updated, the `--force`
    option should be passed to `autogen.sh`, which in turn forwards it to
    `autoreconf`, to make sure that automatically generated scripts and macros
    are updated:

        $ ./autogen.sh --force

  * Configure the package:

        $ ./configure [...]

  * If you want to install the package in the default location
    (`/usr/local/bin`) you can invoke `./configure` with no option, otherwise
    provide the desired installation directory using the `--prefix` option:

        $ ./configure --prefix=/destdir

  * Build the package:

        $ make

  * Test the components:

        $ make check

  * Test the installed components:

        $ make check

  * Install the components:

        $ make install

    Depending on the installation directory additional privileges may be
    required.

  * Add the installation directory to the `PATH`, otherwise builds of the
    package may fail:

        $ export PATH=/destdir/bin:$PATH

[Autoconf]: https://www.gnu.org/software/autoconf/
[Automake]: https://www.gnu.org/software/automake/
[Libtool]: https://www.gnu.org/software/libtool/
[Gettext]: https://www.gnu.org/software/gettext/
-----

Copyright (c) 2014-2017 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/>.

README.solaris
**************

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

This file describes the steps required to build this bundle on a supported
system running the Solaris or the Illumos kernel.  See README for more
information about the tested configurations.

When Illumos was created, the Solaris kernel already included the File Events
Notification API.  Hence, the fen_monitor should be available on any system
running Solaris (> 10) or an Illumos kernel.

Additionally, a Solaris/Illumos system should be able to use the following
monitors:

  * inotify_monitor, depending on the kernel version.

  * poll_monitor.

So far, however, the author has only tested this release on SmartOS.  Feedback
on different Solaris/Illumos systems is much appreciated and will benefit other
users as well.

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.  Check the documentation of your distribution to learn
how to install the required software.

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) 2015 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/>.

README
======

`libfswatch` is a library that provides developers the functionality of
`fswatch`, the main `libfswatch` frontend.  The library provides both C and C++
bindings.

`libfswatch` provides the following [documentation]:

  * Texinfo documentation, included with the distribution.
  * HTML documentation.
  * PDF documentation.
  * A [wiki] page.
  * A man page.

`libfswatch` official documentation is provided in Texinfo format.  This is the
most comprehensive source of information about `libfswatch` and the only
authoritative one.  The man page, in particular, is a stub that suggests the
user to use the info page instead.

If you are installing `libfswatch` using a package manager and you would like
the PDF manual to be bundled into the package, please send a feature request to
the package maintainer.

[documentation]: http://emcrisostomo.github.io/fswatch/doc
[wiki]: https://github.com/emcrisostomo/fswatch/wiki

Bug Reports
-----------

Bug reports can be sent directly to the authors.

Contact the Authors
-------------------

The author can be contacted on IRC, using the Freenode `#fswatch` channel.

-----

Copyright (c) 2013-2016 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/>.

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 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 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-2015 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/>.

[![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg?style=flat)](https://github.com/emcrisostomo/fswatch/blob/master/COPYING)

README
======

`fswatch` is a file change monitor that receives notifications when the contents
of the specified files or directories are modified.  `fswatch` implements
several monitors:

  * A monitor based on the _File System Events API_ of Apple OS X.
  * A monitor based on _kqueue_, a notification interface introduced in FreeBSD
    4.1 (and supported on most *BSD systems, including OS X).
  * A monitor based on the _File Events Notification_ API of the Solaris kernel
    and its derivatives.
  * A monitor based on _inotify_, a Linux kernel subsystem that reports file
    system changes to applications.
  * A monitor based on _ReadDirectoryChangesW_, a Microsoft Windows API that
    reports changes to a directory.
  * A monitor which periodically stats the file system, saves file modification
    times in memory, and manually calculates file system changes (which works
    anywhere `stat (2)` can be used).

`fswatch` should build and work correctly on any system shipping either of the
aforementioned APIs.

Table of Contents
-----------------

  * [libfswatch](#libfswatch)
  * [Features](#features)
  * [Limitations](#limitations)
  * [Getting fswatch](#getting-fswatch)
  * [Building from Source](#building-from-source)
  * [Installation](#installation)
  * [Documentation](#documentation)
  * [Localization](#localization)
  * [Usage](#usage)
  * [Contributing](#contributing)
  * [Bug Reports](#bug-reports)

libfswatch
----------

`fswatch` is a frontend of `libfswatch`, a library with C and C++ binding.  More
information on `libfswatch` can be found [here][README.libfswatch.md].

[README.libfswatch.md]: README.libfswatch.md

Features
--------

`fswatch` main features are:

  * Support for many OS-specific APIs such as kevent, inotify, and FSEvents.
  * Recursive directory monitoring.
  * Path filtering using including and excluding regular expressions.
  * Customizable record format.
  * Support for periodic idle events.

Limitations
-----------

The limitations of `fswatch` depend largely on the monitor being used:

  * The **FSEvents** monitor, available only on OS X, has no known limitations,
    and scales very well with the number of files being observed.

  * The **File Events Notification** monitor, available on Solaris kernels and
    its derivatives, has no known limitations.

  * The **kqueue** monitor, available on any \*BSD system featuring kqueue,
    requires a file descriptor to be opened for every file being watched.  As a
    result, this monitor scales badly with the number of files being observed,
    and may begin to misbehave as soon as the `fswatch` process runs out of file
    descriptors.  In this case, `fswatch` dumps one error on standard error for
    every file that cannot be opened.

  * The **inotify** monitor, available on Linux since kernel 2.6.13, may suffer
    a queue overflow if events are generated faster than they are read from the
    queue.  In any case, the application is guaranteed to receive an overflow
    notification which can be handled to gracefully recover.  `fswatch`
    currently throws an exception if a queue overflow occurs.  Future versions
    will handle the overflow by emitting proper notifications.

  * The **Windows** monitor can only establish a watch _directories_, not files.
    To watch a file, its parent directory must be watched in order to receive
    change events for all the directory's children, _recursively_ at any depth.
    Optionally, change events can be filtered to include only changes to the
    desired file.

  * The **poll** monitor, available on any platform, only relies on
    available CPU and memory to perform its task.  The performance of this
    monitor degrades linearly with the number of files being watched.

Usage recommendations are as follows:

  * On OS X, use only the `FSEvents` monitor (which is the default behaviour).

  * On Solaris and its derivatives use the _File Events Notification_ monitor.

  * On Linux, use the `inotify` monitor (which is the default behaviour).

  * If the number of files to observe is sufficiently small, use the `kqueue`
    monitor.  Beware that on some systems the maximum number of file descriptors
    that can be opened by a process is set to a very low value (values as low as
    256 are not uncommon), even if the operating system may allow a much larger
    value.  In this case, check your OS documentation to raise this limit on
    either a per process or a system-wide basis.

  * If feasible, watch directories instead of files.  Properly crafting the
    receiving side of the events to deal with directories may sensibly reduce
    the monitor resource consumption.

  * On Windows, use the `windows` monitor.

  * If none of the above applies, use the poll monitor.  The authors' experience
    indicates that `fswatch` requires approximately 150 MB of RAM memory to
    observe a hierarchy of 500.000 files with a minimum path length of 32
    characters.  A common bottleneck of the poll monitor is disk access, since
    `stat()`-ing a great number of files may take a huge amount of time.  In
    this case, the latency should be set to a sufficiently large value in order
    to reduce the performance degradation that may result from frequent disk
    access.

Getting fswatch
---------------

A regular user may be able to fetch `fswatch` from the package manager of your
OS or a third-party one.  If you are looking for `fswatch` for OS X, you can
install it using either [MacPorts] or [Homebrew]:

```
# MacPorts
$ port install fswatch

# Homebrew
$ brew install fswatch
```

Check your favourite package manager and let us know if `fswatch` is missing
there.

[MacPorts]: https://www.macports.org
[Homebrew]: http://brew.sh

Building from Source
--------------------

A user who wishes to build `fswatch` should get a [release tarball][release].
A release tarball contains everything a user needs to build `fswatch` on their
system, following the instructions detailed in the Installation section below
and the `INSTALL` file.

A developer who wishes to modify `fswatch` should get the sources (either from a
source tarball or cloning the repository) and have the GNU Build System
installed on their machine.  Please read `README.gnu-build-system` to get further
details about how to bootstrap `fswatch` from sources on your machine.

Getting a copy of the source repository is not recommended unless you are a
developer, you have the GNU Build System installed on your machine, and you know
how to bootstrap it on the sources.

[release]: https://github.com/emcrisostomo/fswatch/releases

Installation
------------

See the `INSTALL` file for detailed information about how to configure and
install `fswatch`.  Since the `fswatch` builds and uses dynamic libraries, in
some platforms you may need to perform additional tasks before you can use
`fswatch`:

  * Make sure the installation directory of dynamic libraries (`$PREFIX/lib`) is
    included in the lookup paths of the dynamic linker of your operating system.
    The default path, `/usr/local/lib`, will work in nearly every operating
    system.
  * Refreshing the links and cache to the dynamic libraries may be required.  In
    GNU/Linux systems you may need to run `ldconfig`:

        $ ldconfig

`fswatch` is a C++ program and a C++ compiler compliant with the C++11 standard
is required to compile it.  Check your OS documentation for information about
how to install the C++ toolchain and the C++ runtime.

No other software packages or dependencies are required to configure and install
`fswatch` but the aforementioned APIs used by the file system monitors.

Documentation
-------------

`fswatch` provides the following [documentation]:

  * Texinfo documentation, included with the distribution.
  * HTML documentation.
  * PDF documentation.
  * A [wiki] page.
  * A man page.

`fswatch` official documentation is provided in Texinfo format.  This is the
most comprehensive source of information about `fswatch` and the only
authoritative one.  The man page, in particular, is a stub that suggests the
user to use the info page instead.

If you are installing `fswatch` using a package manager and you would like the
PDF manual to be bundled into the package, please send a feature request to the
package maintainer.

[documentation]: http://emcrisostomo.github.io/fswatch/doc
[wiki]: https://github.com/emcrisostomo/fswatch/wiki

Localization
------------

`fswatch` is localizable and internally uses GNU `gettext` to decouple
localizable string from their translation.  The currently available locales are:

  * English (`en`).
  * Italian (`it`).
  * Spanish (`es`).

To build `fswatch` with localization support, you need to have `gettext`
installed on your system.  If `configure` cannot find `<libintl.h>` or the
linker cannot find `libintl`, then you may need to manually provide their
location to `configure`, usually using the `CPPFLAGS` and the `LDFLAGS`
variables.  See `README.osx` for an example.

If `gettext` is not available on your system, `fswatch` shall build correctly,
but it will lack localization support and the only available locale will be
English.

Usage
-----

`fswatch` accepts a list of paths for which change events should be received:

    $ fswatch [options] ... path-0 ... path-n

The event stream is created even if any of the paths do not exist yet.  If they
are created after `fswatch` is launched, change events will be properly
received.  Depending on the watcher being used, newly created paths will be
monitored after the amount of configured latency has elapsed.

The output of `fswatch` can be piped to other program in order to process it
further:

    $ fswatch -0 path | while read -d "" event \
      do \
        // do something with ${event}
      done

To run a command when a set of change events is printed to standard output but
no event details are required, then the following command can be used:

    $ fswatch -o path | xargs -n1 -I{} program

The behaviour is consistent with earlier versions of `fswatch` (v. 0.x).
Please, read the _Compatibility Issues with fswatch v. 0.x_ section for further
information.

By default `fswatch` chooses the best monitor available on the current platform,
in terms of performance and resource consumption.  If the user wishes to specify
a different monitor, the `-m` option can be used to specify the monitor by name:

    $ fswatch -m kqueue_monitor path

The list of available monitors can be obtained with the `-h` option.

For more information, refer to the `fswatch` documentation.

Contributing
------------

Everybody is welcome to contribute to `fswatch`.  Please, see
[`CONTRIBUTING`][contrib] for further information.

[contrib]: CONTRIBUTING.md

Bug Reports
-----------

Bug reports can be sent directly to the authors.

Contact the Authors
-------------------

The author can be contacted on IRC, using the Freenode `#fswatch` channel.

-----

Copyright (c) 2013-2017 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/>.

README.osx
**********

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

This file describes the steps required to build this bundle on a supported Apple
OS X system.  A complete C/C++ toolchain for OS X is provided with Apple XCode,
which can be freely installed from the Apple App Store.  See README for more
information about the tested configurations.

XCode
=====

If you plan to build the bundle with CLang/LLVM, the easiest way to get a
working toolchain is installing Apple XCode.  Apple XCode ships with both the
CLang/LLVM and the GCC compiler.

XCode, however, does not install some required command line tools by default.
To install them, the following operations must be performed:

  1. Choose the "XCode/Preferences..." menu item.

  2. Navigate to the "Downloads" pane.

  3. Select the "Components" tab.

  4. Select the "Command Line Tools" item and press the "Install" button.

XCode 4.x
=========

XCode 4 ships with the following C/C++ compilers:

  1. Apple clang++/LLVM v. 4.2:
       Apple LLVM version 4.2 (clang-425.0.28) (based on LLVM 3.2svn)
       Target: x86_64-apple-darwin12.4.0
       Thread model: posix

  2. GNU GCC v. 4.2.1:
       i686-apple-darwin11-llvm-gcc-4.2 (GCC) 4.2.1
       (Based on Apple Inc. build 5658) (LLVM build 2336.11.00)

Only clang++ implements the required C++11 features required by fswatch, so that
it must be configured with this compiler:

  $ CXX=clang++ ./configure

XCode 5.x
=========

XCode 5 ships with the following C/C++ compilers:

  1. Apple clang++/LLVM v. 5.0:
       Apple LLVM version 5.0 (clang-500.2.75) (based on LLVM 3.3svn)
       Target: x86_64-apple-darwin12.5.0
       Thread model: posix

  2. GNU GCC v. 5.0:
       Apple LLVM version 5.0 (clang-500.2.76) (based on LLVM 3.3svn)
       Target: x86_64-apple-darwin12.5.0
       Thread model: posix

The GCC suite has been deprecated in favour of LLVM/CLang and gcc/g++ are now
aliases to clang/clang++.  The project can be configured with the default
compiler:

  $ ./configure

GNU Build System
================

The GNU Build System is required only by developers willing to modify the code
on a OS X machine.  Regular users only willing to install fswatch do not need
the GNU Build System.

Recent XCode Command Line Tools releases are not shipping all the components of
the GNU Build System any longer.  OS X users are thus required to build an
alternate GNU Build System on their system.

The required source bundles can be downloaded from their official web pages:

  1. Autoconf:

     (http://www.gnu.org/software/autoconf/) (>= v. 2.69)

  2. Automake

     (http://www.gnu.org/software/automake/) (>= v. 1.14.1)

  3. Libtool:

     (http://www.gnu.org/software/libtool/)  (>= v. 2.4.2)

Libtool is not required to build this package but it's a core component of the
GNU Build System.

XCode Command Line Tools still ships GNU M4 (v. 1.4.6).

To avoid conflicts with the binaries installed by XCode, it is strongly
suggested to install the GNU Build System in an alternate location (such as the
default /usr/local/bin) or in a private user folder.  To choose the desired
install location, use the --prefix configure option.

For further instruction on building the GNU Build System from scratch, please
check the README.gnu-build-system file.

Localization and gettext
========================

fswatch is localizable and locale support requires GNU gettext to be available
at build time.  OS X does not ship gettext you will need to build it yourself or
use a package manager such as MacPorts or Homebrew to install it.

Depending on gettext installation path, configure may not be able to find
<libintl.h> or libintl.  In this case, you will need to instruct configure about
their location (this example assumes you use MacPorts' default installation path
/opt/local):

  $ CPPFLAGS="-I/opt/local/include" LDFLAGS="-L/opt/local/lib" ./configure

If configure detects that gettext is available, you will find a message such as:

  checking whether to use NLS... yes

or, which is equivalent, config.h will contain the following definition:

  #define ENABLE_NLS 1

-----

Copyright (c) 2014-2015 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/>.

README.smartos
**************

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

This file describes the steps required to build this bundle on SmartOS.  A
complete C/C++ toolchain for SmartOS is provided on the base-multiarch image.

The user is currently using the following image for the development of fswatch
on SmartOS:

    UUID:    9250f5a8-6e9c-11e5-9cdb-67fab8707bfd
    NAME:    base-multiarch
    VERSION: 15.3.0

Setting Up a Development Zone
=============================

A development zone can be setup using the following procedure:

  * Search for the latest base-multiarch image:

        $ imgadm avail | grep base-multiarch
        9250f5a8-6e9c-11e5-9cdb-67fab8707bfd  base-multiarch            15.3.0      smartos  2015-10-09T15:44:05Z

  * Install the latest image available:

        $ imgadm import 9250f5a8-6e9c-11e5-9cdb-67fab8707bfd

  * Create a zone manifest called development.json.  A simple zone manifest
    template is the following:

        {
          "brand": "joyent",
          "image_uuid": "9250f5a8-6e9c-11e5-9cdb-67fab8707bfd",
          "alias": "development",
          "hostname": "development",
          "max_physical_memory": 4096,
          "quota": 10,
          "resolvers": ["8.8.8.8", "8.8.4.4"],
          "nics": [
            {
              "nic_tag": "admin",
              "ip": "dhcp"
            }
          ]
        }

  * Install a zone using the specified image and manifest:

        $ vmadm create -f development.json

Prerequisites
=============

The following packages must be installed on the zone where fswatch is built:

  * autoconf

  * automake

  * gettext

  * libtool

  * gcc49

  * git

  * gmake

  * gtexinfo

Packages can be installed using pkgin:

    $ pkgin update
    $ pkgin install package ...

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.  Check the documentation of your distribution to learn
how to install the required software.

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) 2015 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/>.

README.solaris
**************

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

This file describes the steps required to build this bundle on a supported
system running the Solaris or the Illumos kernel.  See README for more
information about the tested configurations.

When Illumos was created, the Solaris kernel already included the File Events
Notification API.  Hence, the fen_monitor should be available on any system
running Solaris (> 10) or an Illumos kernel.

Additionally, a Solaris/Illumos system should be able to use the following
monitors:

  * inotify_monitor, depending on the kernel version.

  * poll_monitor.

So far, however, the author has only tested this release on SmartOS.  Feedback
on different Solaris/Illumos systems is much appreciated and will benefit other
users as well.

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.  Check the documentation of your distribution to learn
how to install the required software.

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) 2015 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/>.

README.windows
**************

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

This file describes the steps required to build fswatch on Windows.  fswatch was
born as a POSIX application and the Windows monitor has been developed trying to
reduce the dependencies on the Windows API at a minimum.  To fulfill this goal,
a dependency to Cygwin has been introduced.

Windows has historically provided multiple versions of the same API for single
byte and multibyte character sets.  We have decided to only support the
multibyte API: the Windows monitor will thus not build on Windows system
supporting only the single-byte APIs.  In this case, the only available monitor
on the Windows OS will be the poll monitor.

Cygwin
======

Cygwin is a required dependency and must be installed to provide the toolchain
and the libraries required by fswatch.  The current Cygwin distribution can be
downloaded at:

    https://cygwin.com

Cygwin is a modular environment and the following componentes are required to
successfully build fswatch:

  * GNU GCC C++ compiler.

  * GNU Autoconf.

  * GNU Automake.

  * GNU Autoconf.

  * GNU libtool.

The following are optional:

  * GNU gettext (optional)

Windows SDK
===========

The Windows SDK is required to successfully build fswatch since it ships the
headers and the libraries required to build Windows applications.  Please,
consult your Windows documentation to get the latest SDK for your platform.

GNU Build System
================

For further instruction on building the GNU Build System from scratch, please
check the README.gnu-build-system file.

Localization and gettext
========================

fswatch is localizable and locale support requires GNU gettext to be available
at build time.

Depending on gettext installation path, configure may not be able to find
<libintl.h> or libintl.  In this case, you will need to instruct configure about
their location:

  $ CPPFLAGS="-I/path/to/include" LDFLAGS="-L/path/to/lib" ./configure

If configure detects that gettext is available, you will find a message such as:

  checking whether to use NLS... yes

or, which is equivalent, config.h will contain the following definition:

  #define ENABLE_NLS 1

-----

Copyright (c) 2014-2015 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/>.