1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
---
id: cppclient
title: C++ Client
layout: docs
section: Invocation
permalink: docs/cppclient.html
---
*Since 4.8.*
Watchman includes a C++ client library to facilitate easy access to Watchman
data from C++ applications. This library provides APIs for:
* Opening and maintaining a connection to a local Watchman server.
* Executing request-response Watchman commands.
* Subscribing to updates with in directory trees.
## Installation
Provided the Folly library is present when Watchman is built, the C++ client
library is automatically built and installed. For details on building Watchman
see [Installation](/watchman/docs/install.html).
## API
The public Watchman C++ client API is entirely covered in the installed
`watchman/WatchmanClient.h` header file. This header contains a usage synopsis
and notes on the public API features.
For a simple example of API usage, sending simple request-response commands
to Watchman, see `cppclient/CLI.cpp` in the Watchman source tree. For a more
extensive example of the API including use of subscriptions, see the integration
test `tests/integration/cppclient.cpp` also in the Watchman source.
The C++ client library and its API make heavy use of the Folly library and as
such familiarity with this is highly recommended. Specifically, the client
library makes extensive use of [Folly's async features](https://github.com/facebook/folly/blob/master/folly/io/async/README.md)
to provide high-performance asynchronous I/O, and [Folly's dynamics](https://github.com/facebook/folly/blob/master/folly/docs/Dynamic.md)
to avoid needing to construct/process raw JSON in C++.
## Using the C++ client in your application's build
To facilitate integration into your application's build, the Watchman C++ client
library provides support for [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/).
For example, if your application was contained entirely in one C++ file called
`app.cpp` the following would be sufficient for build on a system with GNU Make:
```bash
make LDFLAGS=$(pkg-config watchmanclient --libs) CPPFLAGS=$(pkg-config watchmanclient --cflags) app
```
If Watchman is installed in a location `pkg-config` does not search for packages
by default, you may need to modify the `PKG_CONFIG_PATH` environment
variable. For example:
```bash
export PKG_CONFIG_PATH=<watchman path>/lib/pkgconfig:$PKG_CONFIG_PATH
```
|
