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