0
# Installation and Build
1

2
Build and install Watchman from source code. Watchman is distributed as source code and must be compiled for your target system.
3

4
## System Requirements
5

6
### Supported Platforms
7

8
Watchman compiles and runs on systems with the following notification facilities:
9

10
**Linux:**
11
- Systems with `inotify` support (kernel 2.6.13+)
12
- Most modern Linux distributions
13

14
**BSD/macOS:**
15
- Systems with `kqueue(2)` facility
16
- macOS 10.7+
17
- FreeBSD 9.1+
18
- OpenBSD 5.2+
19

20
**Solaris:**
21
- Systems with `port_create(3C)` facility
22
- Illumos and Solaris 10+
23

24
### Build Dependencies
25

26
**Required:**
27
- C compiler (GCC 4.8+ or Clang 3.4+)
28
- GNU Autotools (autoconf, automake, libtool)
29
- pkg-config
30
- Python (for build scripts)
31

32
**Optional:**
33
- PCRE library (for regex pattern support)
34
- OpenSSL (for certain features)
35

36
## Build Process
37

38
### Standard Build
39

40
```bash { .api }
41
# Generate build configuration
42
./autogen.sh
43

44
# Configure build system
45
./configure
46

47
# Compile the binary
48
make
49

50
# Install system-wide (optional)
51
sudo make install
52
```
53

54
**Build steps:**
55

56
1. **`./autogen.sh`**: Generates configure script from configure.ac
57
2. **`./configure`**: Detects system capabilities and creates Makefiles
58
3. **`make`**: Compiles the watchman binary
59
4. **`make install`**: Installs to system directories (optional)
60

61
### Configure Options
62

63
The configure script accepts various options to customize the build:
64

65
```bash { .api }
66
# Configure with options
67
./configure [options]
68

69
# Common options:
70
--prefix=<path>           # Installation prefix (default: /usr/local)
71
--enable-statedir=<path>  # Enable state directory support
72
--with-pcre               # Enable PCRE regex support
73
--with-python=<path>      # Specify Python interpreter
74
--disable-shared          # Build static binary
75
```
76

77
**Examples:**
78
```bash
79
# Install to /opt/watchman
80
./configure --prefix=/opt/watchman
81

82
# Enable state directory and PCRE
83
./configure --enable-statedir=/var/lib/watchman --with-pcre
84

85
# Custom Python for build scripts
86
./configure --with-python=/usr/bin/python3
87
```
88

89
### Build Variants
90

91
**Debug build:**
92
```bash
93
./configure --enable-debug
94
make
95
```
96

97
**Static build:**
98
```bash
99
./configure --disable-shared
100
make
101
```
102

103
**Minimal build:**
104
```bash
105
./configure --disable-python --without-pcre
106
make
107
```
108

109
## Installation Options
110

111
### System Installation
112

113
Install Watchman system-wide for all users:
114

115
```bash
116
# Standard system installation
117
sudo make install
118

119
# Verify installation
120
watchman --version
121
which watchman
122
```
123

124
**Default locations:**
125
- Binary: `/usr/local/bin/watchman`
126
- Manual: `/usr/local/share/man/man1/watchman.1`
127

128
### User Installation
129

130
Install to user directory without root privileges:
131

132
```bash
133
# Configure for user installation
134
./configure --prefix=$HOME/.local
135

136
# Build and install
137
make install
138

139
# Add to PATH
140
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
141
source ~/.bashrc
142
```
143

144
### Custom Installation
145

146
Install to specific directory:
147

148
```bash
149
# Configure custom prefix
150
./configure --prefix=/opt/tools/watchman
151

152
# Build and install
153
make install
154

155
# Create symlink for system access
156
sudo ln -s /opt/tools/watchman/bin/watchman /usr/local/bin/watchman
157
```
158

159
## Platform-Specific Instructions
160

161
### Linux (Ubuntu/Debian)
162

163
```bash
164
# Install build dependencies
165
sudo apt-get update
166
sudo apt-get install build-essential autoconf automake libtool pkg-config libpcre3-dev
167

168
# Clone and build
169
git clone https://github.com/facebook/watchman.git
170
cd watchman
171
git checkout v2.0
172
./autogen.sh
173
./configure --with-pcre
174
make
175
sudo make install
176
```
177

178
### Linux (CentOS/RHEL)
179

180
```bash
181
# Install build dependencies
182
sudo yum groupinstall "Development Tools"
183
sudo yum install autoconf automake libtool pkgconfig pcre-devel
184

185
# Build process
186
./autogen.sh
187
./configure --with-pcre
188
make
189
sudo make install
190
```
191

192
### macOS
193

194
```bash
195
# Install Xcode command line tools
196
xcode-select --install
197

198
# Install Homebrew dependencies (optional)
199
brew install autoconf automake libtool pkg-config pcre
200

201
# Build
202
./autogen.sh
203
./configure --with-pcre
204
make
205
sudo make install
206
```
207

208
### FreeBSD
209

210
```bash
211
# Install dependencies
212
sudo pkg install autotools pkgconf pcre
213

214
# Build with FreeBSD paths
215
./autogen.sh
216
./configure --with-pcre --prefix=/usr/local
217
make
218
sudo make install
219
```
220

221
## System Configuration
222

223
### File Descriptor Limits
224

225
**Linux (inotify limits):**
226
```bash
227
# Check current limits
228
cat /proc/sys/fs/inotify/max_user_watches
229
cat /proc/sys/fs/inotify/max_user_instances
230

231
# Increase limits (temporary)
232
sudo sysctl fs.inotify.max_user_watches=524288
233
sudo sysctl fs.inotify.max_user_instances=256
234

235
# Permanent configuration
236
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
237
echo 'fs.inotify.max_user_instances=256' | sudo tee -a /etc/sysctl.conf
238
```
239

240
**macOS (file descriptor limits):**
241
```bash
242
# Check current limits
243
ulimit -n
244
sysctl kern.maxfiles
245
sysctl kern.maxfilesperproc
246

247
# Increase limits (temporary)
248
sudo sysctl -w kern.maxfiles=10485760
249
sudo sysctl -w kern.maxfilesperproc=1048576
250

251
# Permanent configuration (/etc/sysctl.conf)
252
kern.maxfiles=10485760
253
kern.maxfilesperproc=1048576
254
```
255

256
### State Directory Configuration
257

258
When configured with `--enable-statedir`, Watchman uses dedicated directories:
259

260
```bash
261
# Configure with state directory
262
./configure --enable-statedir=/var/lib/watchman
263

264
# Create state directory
265
sudo mkdir -p /var/lib/watchman
266
sudo chown $USER:$USER /var/lib/watchman
267

268
# Build and install
269
make
270
sudo make install
271
```
272

273
### Service Integration
274

275
**systemd service (Linux):**
276
```ini
277
# /etc/systemd/system/watchman.service
278
[Unit]
279
Description=Watchman file watching service
280
After=network.target
281

282
[Service]
283
Type=forking
284
User=watchman
285
Group=watchman
286
ExecStart=/usr/local/bin/watchman -f
287
PIDFile=/var/run/watchman.pid
288
Restart=always
289

290
[Install]
291
WantedBy=multi-user.target
292
```
293

294
**launchd service (macOS):**
295
```xml
296
<!-- ~/Library/LaunchAgents/com.facebook.watchman.plist -->
297
<?xml version="1.0" encoding="UTF-8"?>
298
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
299
<plist version="1.0">
300
<dict>
301
    <key>Label</key>
302
    <string>com.facebook.watchman</string>
303
    <key>ProgramArguments</key>
304
    <array>
305
        <string>/usr/local/bin/watchman</string>
306
        <string>-f</string>
307
    </array>
308
    <key>RunAtLoad</key>
309
    <true/>
310
    <key>KeepAlive</key>
311
    <true/>
312
</dict>
313
</plist>
314
```
315

316
## Verification and Testing
317

318
### Basic Verification
319

320
```bash
321
# Check installation
322
watchman --version
323

324
# Test basic functionality
325
mkdir test-dir
326
watchman watch test-dir
327
watchman watch-list
328
watchman watch-del test-dir
329
rmdir test-dir
330
```
331

332
### Build Testing
333

334
```bash
335
# Run build tests (if available)
336
make check
337

338
# Test with sample directory
339
mkdir -p /tmp/watchman-test
340
watchman watch /tmp/watchman-test
341
touch /tmp/watchman-test/testfile
342
watchman find /tmp/watchman-test
343
watchman watch-del /tmp/watchman-test
344
rm -rf /tmp/watchman-test
345
```
346

347
### Performance Testing
348

349
```bash
350
# Test with large directory tree
351
mkdir -p test-perf
352
cd test-perf
353
for i in {1..1000}; do touch file$i; done
354
watchman watch .
355
time watchman find . | wc -l
356
cd ..
357
watchman watch-del test-perf
358
rm -rf test-perf
359
```
360

361
## Troubleshooting
362

363
### Common Build Issues
364

365
**Missing autotools:**
366
```bash
367
# Install autotools
368
sudo apt-get install autoconf automake libtool  # Debian/Ubuntu
369
sudo yum install autoconf automake libtool      # CentOS/RHEL
370
```
371

372
**PCRE not found:**
373
```bash
374
# Install PCRE development headers
375
sudo apt-get install libpcre3-dev     # Debian/Ubuntu
376
sudo yum install pcre-devel           # CentOS/RHEL
377
```
378

379
**Python issues:**
380
```bash
381
# Specify Python version
382
./configure --with-python=/usr/bin/python3
383
```
384

385
### Runtime Issues
386

387
**Permission denied:**
388
```bash
389
# Check socket permissions
390
ls -la /tmp/.watchman.$USER*
391

392
# Remove stale socket
393
rm /tmp/.watchman.$USER*
394
```
395

396
**Resource limits:**
397
```bash
398
# Check and increase limits
399
ulimit -n 65536
400
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
401
```
402

403
### Log Analysis
404

405
```bash
406
# Check Watchman logs
407
tail -f /tmp/.watchman.$USER.log
408

409
# Debug mode
410
watchman -f log-level debug
411
```