|
160
|
1 ![libuv][libuv_banner]
|
|
|
2
|
|
|
3 ## Overview
|
|
|
4
|
|
|
5 libuv is a multi-platform support library with a focus on asynchronous I/O. It
|
|
|
6 was primarily developed for use by [Node.js][], but it's also
|
|
|
7 used by [Luvit](http://luvit.io/), [Julia](http://julialang.org/),
|
|
|
8 [uvloop](https://github.com/MagicStack/uvloop), 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
|
|
|
38 Starting with version 1.0.0 libuv follows the [semantic versioning](http://semver.org/)
|
|
|
39 scheme. The API change and backwards compatibility rules are those indicated by
|
|
|
40 SemVer. libuv will keep a stable ABI across major releases.
|
|
|
41
|
|
|
42 The ABI/API changes can be tracked [here](http://abi-laboratory.pro/tracker/timeline/libuv/).
|
|
|
43
|
|
|
44 ## Licensing
|
|
|
45
|
|
|
46 libuv is licensed under the MIT license. Check the [LICENSE](LICENSE) and
|
|
|
47 [LICENSE-extra](LICENSE-extra) files.
|
|
|
48
|
|
|
49 The documentation is licensed under the CC BY 4.0 license. Check the
|
|
|
50 [LICENSE-docs file](LICENSE-docs).
|
|
|
51
|
|
|
52 ## Community
|
|
|
53
|
|
|
54 * [Support](https://github.com/libuv/libuv/discussions)
|
|
|
55 * [Mailing list](http://groups.google.com/group/libuv)
|
|
|
56
|
|
|
57 ## Documentation
|
|
|
58
|
|
|
59 ### Official documentation
|
|
|
60
|
|
|
61 Located in the docs/ subdirectory. It uses the [Sphinx](http://sphinx-doc.org/)
|
|
|
62 framework, which makes it possible to build the documentation in multiple
|
|
|
63 formats.
|
|
|
64
|
|
|
65 Show different supported building options:
|
|
|
66
|
|
|
67 ```bash
|
|
|
68 $ make help
|
|
|
69 ```
|
|
|
70
|
|
|
71 Build documentation as HTML:
|
|
|
72
|
|
|
73 ```bash
|
|
|
74 $ make html
|
|
|
75 ```
|
|
|
76
|
|
|
77 Build documentation as HTML and live reload it when it changes (this requires
|
|
|
78 sphinx-autobuild to be installed and is only supported on Unix):
|
|
|
79
|
|
|
80 ```bash
|
|
|
81 $ make livehtml
|
|
|
82 ```
|
|
|
83
|
|
|
84 Build documentation as man pages:
|
|
|
85
|
|
|
86 ```bash
|
|
|
87 $ make man
|
|
|
88 ```
|
|
|
89
|
|
|
90 Build documentation as ePub:
|
|
|
91
|
|
|
92 ```bash
|
|
|
93 $ make epub
|
|
|
94 ```
|
|
|
95
|
|
|
96 NOTE: Windows users need to use make.bat instead of plain 'make'.
|
|
|
97
|
|
|
98 Documentation can be browsed online [here](http://docs.libuv.org).
|
|
|
99
|
|
|
100 The [tests and benchmarks](https://github.com/libuv/libuv/tree/master/test)
|
|
|
101 also serve as API specification and usage examples.
|
|
|
102
|
|
|
103 ### Other resources
|
|
|
104
|
|
|
105 * [LXJS 2012 talk](http://www.youtube.com/watch?v=nGn60vDSxQ4)
|
|
|
106 — High-level introductory talk about libuv.
|
|
|
107 * [libuv-dox](https://github.com/thlorenz/libuv-dox)
|
|
|
108 — Documenting types and methods of libuv, mostly by reading uv.h.
|
|
|
109 * [learnuv](https://github.com/thlorenz/learnuv)
|
|
|
110 — Learn uv for fun and profit, a self guided workshop to libuv.
|
|
|
111
|
|
|
112 These resources are not handled by libuv maintainers and might be out of
|
|
|
113 date. Please verify it before opening new issues.
|
|
|
114
|
|
|
115 ## Downloading
|
|
|
116
|
|
|
117 libuv can be downloaded either from the
|
|
|
118 [GitHub repository](https://github.com/libuv/libuv)
|
|
|
119 or from the [downloads site](http://dist.libuv.org/dist/).
|
|
|
120
|
|
|
121 Before verifying the git tags or signature files, importing the relevant keys
|
|
|
122 is necessary. Key IDs are listed in the
|
|
|
123 [MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md)
|
|
|
124 file, but are also available as git blob objects for easier use.
|
|
|
125
|
|
|
126 Importing a key the usual way:
|
|
|
127
|
|
|
128 ```bash
|
|
|
129 $ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059
|
|
|
130 ```
|
|
|
131
|
|
|
132 Importing a key from a git blob object:
|
|
|
133
|
|
|
134 ```bash
|
|
|
135 $ git show pubkey-saghul | gpg --import
|
|
|
136 ```
|
|
|
137
|
|
|
138 ### Verifying releases
|
|
|
139
|
|
|
140 Git tags are signed with the developer's key, they can be verified as follows:
|
|
|
141
|
|
|
142 ```bash
|
|
|
143 $ git verify-tag v1.6.1
|
|
|
144 ```
|
|
|
145
|
|
|
146 Starting with libuv 1.7.0, the tarballs stored in the
|
|
|
147 [downloads site](http://dist.libuv.org/dist/) are signed and an accompanying
|
|
|
148 signature file sit alongside each. Once both the release tarball and the
|
|
|
149 signature file are downloaded, the file can be verified as follows:
|
|
|
150
|
|
|
151 ```bash
|
|
|
152 $ gpg --verify libuv-1.7.0.tar.gz.sign
|
|
|
153 ```
|
|
|
154
|
|
|
155 ## Build Instructions
|
|
|
156
|
|
|
157 For UNIX-like platforms, including macOS, there are two build methods:
|
|
|
158 autotools or [CMake][].
|
|
|
159
|
|
|
160 For Windows, [CMake][] is the only supported build method and has the
|
|
|
161 following prerequisites:
|
|
|
162
|
|
|
163 <details>
|
|
|
164
|
|
|
165 * One of:
|
|
|
166 * [Visual C++ Build Tools][]
|
|
|
167 * [Visual Studio 2015 Update 3][], all editions
|
|
|
168 including the Community edition (remember to select
|
|
|
169 "Common Tools for Visual C++ 2015" feature during installation).
|
|
|
170 * [Visual Studio 2017][], any edition (including the Build Tools SKU).
|
|
|
171 **Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the
|
|
|
172 Windows SDKs (10 or 8.1).
|
|
|
173 * Basic Unix tools required for some tests,
|
|
|
174 [Git for Windows][] includes Git Bash
|
|
|
175 and tools which can be included in the global `PATH`.
|
|
|
176
|
|
|
177 </details>
|
|
|
178
|
|
|
179 To build with autotools:
|
|
|
180
|
|
|
181 ```bash
|
|
|
182 $ sh autogen.sh
|
|
|
183 $ ./configure
|
|
|
184 $ make
|
|
|
185 $ make check
|
|
|
186 $ make install
|
|
|
187 ```
|
|
|
188
|
|
|
189 To build with [CMake][]:
|
|
|
190
|
|
|
191 ```bash
|
|
|
192 $ cmake -B build -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
|
|
|
203 To 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
|
|
|
218 Note to OS X users:
|
|
|
219
|
|
|
220 Make 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 ### Install with vcpkg
|
|
|
225
|
|
|
226 ```bash
|
|
|
227 $ git clone https://github.com/microsoft/vcpkg.git
|
|
|
228 $ ./bootstrap-vcpkg.bat # for powershell
|
|
|
229 $ ./bootstrap-vcpkg.sh # for bash
|
|
|
230 $ ./vcpkg install libuv
|
|
|
231 ```
|
|
|
232
|
|
|
233 ### Install with Conan
|
|
|
234
|
|
|
235 You can install pre-built binaries for libuv or build it from source using [Conan](https://conan.io/). Use the following command:
|
|
|
236
|
|
|
237 ```bash
|
|
|
238 conan install --requires="libuv/[*]" --build=missing
|
|
|
239 ```
|
|
|
240
|
|
|
241 The libuv Conan recipe is kept up to date by Conan maintainers and community contributors.
|
|
|
242 If the version is out of date, please [create an issue or pull request](https://github.com/conan-io/conan-center-index) on the ConanCenterIndex repository.
|
|
|
243
|
|
|
244
|
|
|
245 ### Running tests
|
|
|
246
|
|
|
247 Some tests are timing sensitive. Relaxing test timeouts may be necessary
|
|
|
248 on slow or overloaded machines:
|
|
|
249
|
|
|
250 ```bash
|
|
|
251 $ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests # 10s instead of 5s
|
|
|
252 ```
|
|
|
253
|
|
|
254 #### Run one test
|
|
|
255
|
|
|
256 The list of all tests is in `test/test-list.h`.
|
|
|
257
|
|
|
258 This invocation will cause the test driver to fork and execute `TEST_NAME` in
|
|
|
259 a child process:
|
|
|
260
|
|
|
261 ```bash
|
|
|
262 $ build/uv_run_tests_a TEST_NAME
|
|
|
263 ```
|
|
|
264
|
|
|
265 This invocation will cause the test driver to execute the test in
|
|
|
266 the same process:
|
|
|
267
|
|
|
268 ```bash
|
|
|
269 $ build/uv_run_tests_a TEST_NAME TEST_NAME
|
|
|
270 ```
|
|
|
271
|
|
|
272 #### Debugging tools
|
|
|
273
|
|
|
274 When running the test from within the test driver process
|
|
|
275 (`build/uv_run_tests_a TEST_NAME TEST_NAME`), tools like gdb and valgrind
|
|
|
276 work normally.
|
|
|
277
|
|
|
278 When running the test from a child of the test driver process
|
|
|
279 (`build/uv_run_tests_a TEST_NAME`), use these tools in a fork-aware manner.
|
|
|
280
|
|
|
281 ##### Fork-aware gdb
|
|
|
282
|
|
|
283 Use the [follow-fork-mode](https://sourceware.org/gdb/onlinedocs/gdb/Forks.html) setting:
|
|
|
284
|
|
|
285 ```
|
|
|
286 $ gdb --args build/uv_run_tests_a TEST_NAME
|
|
|
287
|
|
|
288 (gdb) set follow-fork-mode child
|
|
|
289 ...
|
|
|
290 ```
|
|
|
291
|
|
|
292 ##### Fork-aware valgrind
|
|
|
293
|
|
|
294 Use the `--trace-children=yes` parameter:
|
|
|
295
|
|
|
296 ```bash
|
|
|
297 $ 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
|
|
|
298 ```
|
|
|
299
|
|
|
300 ### Running benchmarks
|
|
|
301
|
|
|
302 See the section on running tests.
|
|
|
303 The benchmark driver is `./uv_run_benchmarks_a` and the benchmarks are
|
|
|
304 listed in `test/benchmark-list.h`.
|
|
|
305
|
|
|
306 ## Supported Platforms
|
|
|
307
|
|
|
308 Check the [SUPPORTED_PLATFORMS file](SUPPORTED_PLATFORMS.md).
|
|
|
309
|
|
|
310 ### `-fno-strict-aliasing`
|
|
|
311
|
|
|
312 It is recommended to turn on the `-fno-strict-aliasing` compiler flag in
|
|
|
313 projects that use libuv. The use of ad hoc "inheritance" in the libuv API
|
|
|
314 may not be safe in the presence of compiler optimizations that depend on
|
|
|
315 strict aliasing.
|
|
|
316
|
|
|
317 MSVC does not have an equivalent flag but it also does not appear to need it
|
|
|
318 at the time of writing (December 2019.)
|
|
|
319
|
|
|
320 ### AIX Notes
|
|
|
321
|
|
|
322 AIX compilation using IBM XL C/C++ requires version 12.1 or greater.
|
|
|
323
|
|
|
324 AIX support for filesystem events requires the non-default IBM `bos.ahafs`
|
|
|
325 package to be installed. This package provides the AIX Event Infrastructure
|
|
|
326 that is detected by `autoconf`.
|
|
|
327 [IBM documentation](http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/)
|
|
|
328 describes the package in more detail.
|
|
|
329
|
|
|
330 ### z/OS Notes
|
|
|
331
|
|
|
332 z/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):
|
|
|
333
|
|
|
334 ```bash
|
|
|
335 $ (cd build && cmake .. -DBUILD_TESTING=ON -DZOSLIB_DIR=/path/to/zoslib)
|
|
|
336 $ cmake --build build
|
|
|
337 ```
|
|
|
338
|
|
|
339 z/OS creates System V semaphores and message queues. These persist on the system
|
|
|
340 after the process terminates unless the event loop is closed.
|
|
|
341
|
|
|
342 Use the `ipcrm` command to manually clear up System V resources.
|
|
|
343
|
|
|
344 ## Patches
|
|
|
345
|
|
|
346 See the [guidelines for contributing][].
|
|
|
347
|
|
|
348 [CMake]: https://cmake.org/
|
|
|
349 [node.js]: http://nodejs.org/
|
|
|
350 [guidelines for contributing]: https://github.com/libuv/libuv/blob/master/CONTRIBUTING.md
|
|
|
351 [libuv_banner]: https://raw.githubusercontent.com/libuv/libuv/master/img/banner.png
|
|
|
352 [Visual C++ Build Tools]: https://visualstudio.microsoft.com/visual-cpp-build-tools/
|
|
|
353 [Visual Studio 2015 Update 3]: https://www.visualstudio.com/vs/older-downloads/
|
|
|
354 [Visual Studio 2017]: https://www.visualstudio.com/downloads/
|
|
|
355 [Git for Windows]: http://git-scm.com/download/win
|
