1![libuv][libuv_banner]
2
3## Overview
4
5libuv is a multi-platform support library with a focus on asynchronous I/O. It
6was primarily developed for use by [Node.js][], but it's also
7used by [Luvit](http://luvit.io/), [Julia](http://julialang.org/),
8[pyuv](https://github.com/saghul/pyuv), and [others](https://github.com/libuv/libuv/blob/v1.x/LINKS.md).
9
10## Feature highlights
11
12 * Full-featured event loop backed by epoll, kqueue, IOCP, event ports.
13
14 * Asynchronous TCP and UDP sockets
15
16 * Asynchronous DNS resolution
17
18 * Asynchronous file and file system operations
19
20 * File system events
21
22 * ANSI escape code controlled TTY
23
24 * IPC with socket sharing, using Unix domain sockets or named pipes (Windows)
25
26 * Child processes
27
28 * Thread pool
29
30 * Signal handling
31
32 * High resolution clock
33
34 * Threading and synchronization primitives
35
36## Versioning
37
38Starting with version 1.0.0 libuv follows the [semantic versioning](http://semver.org/)
39scheme. The API change and backwards compatibility rules are those indicated by
40SemVer. libuv will keep a stable ABI across major releases.
41
42The ABI/API changes can be tracked [here](http://abi-laboratory.pro/tracker/timeline/libuv/).
43
44## Licensing
45
46libuv is licensed under the MIT license. Check the [LICENSE file](LICENSE).
47The documentation is licensed under the CC BY 4.0 license. Check the [LICENSE-docs file](LICENSE-docs).
48
49## Community
50
51 * [Support](https://github.com/libuv/libuv/discussions)
52 * [Mailing list](http://groups.google.com/group/libuv)
53
54## Documentation
55
56### Official documentation
57
58Located in the docs/ subdirectory. It uses the [Sphinx](http://sphinx-doc.org/)
59framework, which makes it possible to build the documentation in multiple
60formats.
61
62Show different supported building options:
63
64```bash
65$ make help
66```
67
68Build documentation as HTML:
69
70```bash
71$ make html
72```
73
74Build documentation as HTML and live reload it when it changes (this requires
75sphinx-autobuild to be installed and is only supported on Unix):
76
77```bash
78$ make livehtml
79```
80
81Build documentation as man pages:
82
83```bash
84$ make man
85```
86
87Build documentation as ePub:
88
89```bash
90$ make epub
91```
92
93NOTE: Windows users need to use make.bat instead of plain 'make'.
94
95Documentation can be browsed online [here](http://docs.libuv.org).
96
97The [tests and benchmarks](https://github.com/libuv/libuv/tree/master/test)
98also serve as API specification and usage examples.
99
100### Other resources
101
102 * [LXJS 2012 talk](http://www.youtube.com/watch?v=nGn60vDSxQ4)
103   — High-level introductory talk about libuv.
104 * [libuv-dox](https://github.com/thlorenz/libuv-dox)
105   — Documenting types and methods of libuv, mostly by reading uv.h.
106 * [learnuv](https://github.com/thlorenz/learnuv)
107   — Learn uv for fun and profit, a self guided workshop to libuv.
108
109These resources are not handled by libuv maintainers and might be out of
110date. Please verify it before opening new issues.
111
112## Downloading
113
114libuv can be downloaded either from the
115[GitHub repository](https://github.com/libuv/libuv)
116or from the [downloads site](http://dist.libuv.org/dist/).
117
118Before verifying the git tags or signature files, importing the relevant keys
119is necessary. Key IDs are listed in the
120[MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md)
121file, but are also available as git blob objects for easier use.
122
123Importing a key the usual way:
124
125```bash
126$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059
127```
128
129Importing a key from a git blob object:
130
131```bash
132$ git show pubkey-saghul | gpg --import
133```
134
135### Verifying releases
136
137Git tags are signed with the developer's key, they can be verified as follows:
138
139```bash
140$ git verify-tag v1.6.1
141```
142
143Starting with libuv 1.7.0, the tarballs stored in the
144[downloads site](http://dist.libuv.org/dist/) are signed and an accompanying
145signature file sit alongside each. Once both the release tarball and the
146signature file are downloaded, the file can be verified as follows:
147
148```bash
149$ gpg --verify libuv-1.7.0.tar.gz.sign
150```
151
152## Build Instructions
153
154For UNIX-like platforms, including macOS, there are two build methods:
155autotools or [CMake][].
156
157For Windows, [CMake][] is the only supported build method and has the
158following prerequisites:
159
160<details>
161
162* One of:
163  * [Visual C++ Build Tools][]
164  * [Visual Studio 2015 Update 3][], all editions
165    including the Community edition (remember to select
166    "Common Tools for Visual C++ 2015" feature during installation).
167  * [Visual Studio 2017][], any edition (including the Build Tools SKU).
168    **Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the
169    Windows SDKs (10 or 8.1).
170* Basic Unix tools required for some tests,
171  [Git for Windows][] includes Git Bash
172  and tools which can be included in the global `PATH`.
173
174</details>
175
176To build with autotools:
177
178```bash
179$ sh autogen.sh
180$ ./configure
181$ make
182$ make check
183$ make install
184```
185
186To build with [CMake][]:
187
188```bash
189$ mkdir -p build
190
191$ (cd build && cmake .. -DBUILD_TESTING=ON) # generate project with tests
192$ cmake --build build                       # add `-j <n>` with cmake >= 3.12
193
194# Run tests:
195$ (cd build && ctest -C Debug --output-on-failure)
196
197# Or manually run tests:
198$ build/uv_run_tests                        # shared library build
199$ build/uv_run_tests_a                      # static library build
200```
201
202To cross-compile with [CMake][] (unsupported but generally works):
203
204```bash
205$ cmake ../..                 \
206  -DCMAKE_SYSTEM_NAME=Windows \
207  -DCMAKE_SYSTEM_VERSION=6.1  \
208  -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc
209```
210
211### Install with Homebrew
212
213```bash
214$ brew install --HEAD libuv
215```
216
217Note to OS X users:
218
219Make sure that you specify the architecture you wish to build for in the
220"ARCHS" flag. You can specify more than one by delimiting with a space
221(e.g. "x86_64 i386").
222
223### Running tests
224
225Some tests are timing sensitive. Relaxing test timeouts may be necessary
226on slow or overloaded machines:
227
228```bash
229$ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests # 10s instead of 5s
230```
231
232#### Run one test
233
234The list of all tests is in `test/test-list.h`.
235
236This invocation will cause the test driver to fork and execute `TEST_NAME` in
237a child process:
238
239```bash
240$ build/uv_run_tests_a TEST_NAME
241```
242
243This invocation will cause the test driver to execute the test in
244the same process:
245
246```bash
247$ build/uv_run_tests_a TEST_NAME TEST_NAME
248```
249
250#### Debugging tools
251
252When running the test from within the test driver process
253(`build/uv_run_tests_a TEST_NAME TEST_NAME`), tools like gdb and valgrind
254work normally.
255
256When running the test from a child of the test driver process
257(`build/uv_run_tests_a TEST_NAME`), use these tools in a fork-aware manner.
258
259##### Fork-aware gdb
260
261Use the [follow-fork-mode](https://sourceware.org/gdb/onlinedocs/gdb/Forks.html) setting:
262
263```
264$ gdb --args build/uv_run_tests_a TEST_NAME
265
266(gdb) set follow-fork-mode child
267...
268```
269
270##### Fork-aware valgrind
271
272Use the `--trace-children=yes` parameter:
273
274```bash
275$ valgrind --trace-children=yes -v --tool=memcheck --leak-check=full --track-origins=yes --leak-resolution=high --show-reachable=yes --log-file=memcheck-%p.log build/uv_run_tests_a TEST_NAME
276```
277
278### Running benchmarks
279
280See the section on running tests.
281The benchmark driver is `./uv_run_benchmarks_a` and the benchmarks are
282listed in `test/benchmark-list.h`.
283
284## Supported Platforms
285
286Check the [SUPPORTED_PLATFORMS file](SUPPORTED_PLATFORMS.md).
287
288### `-fno-strict-aliasing`
289
290It is recommended to turn on the `-fno-strict-aliasing` compiler flag in
291projects that use libuv. The use of ad hoc "inheritance" in the libuv API
292may not be safe in the presence of compiler optimizations that depend on
293strict aliasing.
294
295MSVC does not have an equivalent flag but it also does not appear to need it
296at the time of writing (December 2019.)
297
298### AIX Notes
299
300AIX compilation using IBM XL C/C++ requires version 12.1 or greater.
301
302AIX support for filesystem events requires the non-default IBM `bos.ahafs`
303package to be installed.  This package provides the AIX Event Infrastructure
304that is detected by `autoconf`.
305[IBM documentation](http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/)
306describes the package in more detail.
307
308### z/OS Notes
309
310z/OS compilation requires [ZOSLIB](https://github.com/ibmruntimes/zoslib) to be installed. When building with [CMake][], use the flag `-DZOSLIB_DIR` to specify the path to [ZOSLIB](https://github.com/ibmruntimes/zoslib):
311
312```bash
313$ (cd build && cmake .. -DBUILD_TESTING=ON -DZOSLIB_DIR=/path/to/zoslib)
314$ cmake --build build
315```
316
317z/OS creates System V semaphores and message queues. These persist on the system
318after the process terminates unless the event loop is closed.
319
320Use the `ipcrm` command to manually clear up System V resources.
321
322## Patches
323
324See the [guidelines for contributing][].
325
326[CMake]: https://cmake.org/
327[node.js]: http://nodejs.org/
328[guidelines for contributing]: https://github.com/libuv/libuv/blob/master/CONTRIBUTING.md
329[libuv_banner]: https://raw.githubusercontent.com/libuv/libuv/master/img/banner.png
330[Visual C++ Build Tools]: https://visualstudio.microsoft.com/visual-cpp-build-tools/
331[Visual Studio 2015 Update 3]: https://www.visualstudio.com/vs/older-downloads/
332[Visual Studio 2017]: https://www.visualstudio.com/downloads/
333[Git for Windows]: http://git-scm.com/download/win
334