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