xref: /libuv/
Name Date Size #Lines LOC

..28-Sep-2023-

.github/H07-Nov-2023-

cmake-toolchains/H19-Jan-2023-

docs/H14-Aug-2023-

img/H24-Feb-2020-

include/H05-Feb-2024-

m4/H12-Jul-2022-

src/H07-Feb-2024-

test/H22-Mar-2024-

tools/H28-Dec-2020-

.gitattributesH A D24-Feb-202042 21

.gitignoreH A D05-Jan-2024896 8173

.mailmapH A D19-May-20233.3 KiB6867

.readthedocs.yamlH A D20-May-2023201 1612

AUTHORSH A D07-Feb-202420.9 KiB570569

CMakeLists.txtH A D21-Mar-202427.3 KiB806746

CONTRIBUTING.mdH A D01-Jul-20215.6 KiB172115

ChangeLogH A D22-Mar-2024177.7 KiB6,1013,020

LICENSEH A D19-Jan-20231.1 KiB2016

LICENSE-docsH A D24-Feb-202018.2 KiB397305

LICENSE-extraH A D19-Jan-20231.6 KiB3727

LINKS.mdH A D16-Jun-20237.3 KiB110107

MAINTAINERS.mdH A D19-Nov-20232.6 KiB5742

Makefile.amH A D21-Mar-202421.3 KiB559499

README.mdH A D19-Jan-20239.3 KiB346233

SECURITY.mdH A D19-Jan-20241.3 KiB2716

SUPPORTED_PLATFORMS.mdH A D02-May-20232.7 KiB6950

autogen.shH A D04-Nov-20222.4 KiB7651

configure.acH A D07-Feb-20244.4 KiB9390

libuv-static.pc.inH A D19-Jan-2023287 1310

libuv.pc.inH A D19-Jan-2023317 1411

tsansupp.txtH A D20-Jan-202389 32

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