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