xref: /libuv/
Name Date Size #Lines LOC

..26-Dec-2020-

.github/H17-May-2020-

docs/H24-Feb-2020-

img/H24-Feb-2020-

include/H04-Apr-2021-

m4/H16-Jun-2020-

src/H18-Nov-2020-

test/H04-Apr-2021-

tools/H28-Dec-2020-

.gitattributesH A D24-Feb-202042 21

.gitignoreH A D17-May-2020842 7769

.mailmapH A D13-Feb-20212.8 KiB5756

AUTHORSH A D13-Feb-202116.7 KiB462461

CMakeLists.txtH A D04-Apr-202122.3 KiB663618

CONTRIBUTING.mdH A D07-Apr-20205.6 KiB172115

ChangeLogH A D13-Feb-2021147.5 KiB5,0552,500

LICENSEH A D24-Feb-20203.1 KiB7153

LICENSE-docsH A D24-Feb-202018.2 KiB397305

MAINTAINERS.mdH A D24-Feb-20202.2 KiB5137

Makefile.amH A D28-Dec-202020.6 KiB544485

README.mdH A D15-Feb-20219.2 KiB335225

SUPPORTED_PLATFORMS.mdH A D28-Dec-20202.7 KiB7051

autogen.shH A D24-Feb-20201.7 KiB4724

configure.acH A D13-Feb-20214 KiB8684

libuv-static.pc.inH A D22-Sep-2020283 1310

libuv.pc.inH A D24-Feb-2020274 1310

uv_win_longpath.manifestH A D28-Apr-2020426 98

README.md

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