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[pyuv](https://github.com/saghul/pyuv), and [others](https://github.com/libuv/libuv/wiki/Projects-that-use-libuv). 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 file](LICENSE). 47The documentation is licensed under the CC BY 4.0 license. Check the [LICENSE-docs file](LICENSE-docs). 48 49## Community 50 51 * [Support](https://github.com/libuv/help) 52 * [Mailing list](http://groups.google.com/group/libuv) 53 * [IRC chatroom (#libuv@irc.freenode.org)](http://webchat.freenode.net?channels=libuv&uio=d4) 54 55## Documentation 56 57### Official documentation 58 59Located in the docs/ subdirectory. It uses the [Sphinx](http://sphinx-doc.org/) 60framework, which makes it possible to build the documentation in multiple 61formats. 62 63Show different supported building options: 64 65```bash 66$ make help 67``` 68 69Build documentation as HTML: 70 71```bash 72$ make html 73``` 74 75Build documentation as HTML and live reload it when it changes (this requires 76sphinx-autobuild to be installed and is only supported on Unix): 77 78```bash 79$ make livehtml 80``` 81 82Build documentation as man pages: 83 84```bash 85$ make man 86``` 87 88Build documentation as ePub: 89 90```bash 91$ make epub 92``` 93 94NOTE: Windows users need to use make.bat instead of plain 'make'. 95 96Documentation can be browsed online [here](http://docs.libuv.org). 97 98The [tests and benchmarks](https://github.com/libuv/libuv/tree/master/test) 99also serve as API specification and usage examples. 100 101### Other resources 102 103 * [LXJS 2012 talk](http://www.youtube.com/watch?v=nGn60vDSxQ4) 104 — High-level introductory talk about libuv. 105 * [libuv-dox](https://github.com/thlorenz/libuv-dox) 106 — Documenting types and methods of libuv, mostly by reading uv.h. 107 * [learnuv](https://github.com/thlorenz/learnuv) 108 — Learn uv for fun and profit, a self guided workshop to libuv. 109 110These resources are not handled by libuv maintainers and might be out of 111date. Please verify it before opening new issues. 112 113## Downloading 114 115libuv can be downloaded either from the 116[GitHub repository](https://github.com/libuv/libuv) 117or from the [downloads site](http://dist.libuv.org/dist/). 118 119Before verifying the git tags or signature files, importing the relevant keys 120is necessary. Key IDs are listed in the 121[MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md) 122file, but are also available as git blob objects for easier use. 123 124Importing a key the usual way: 125 126```bash 127$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059 128``` 129 130Importing a key from a git blob object: 131 132```bash 133$ git show pubkey-saghul | gpg --import 134``` 135 136### Verifying releases 137 138Git tags are signed with the developer's key, they can be verified as follows: 139 140```bash 141$ git verify-tag v1.6.1 142``` 143 144Starting with libuv 1.7.0, the tarballs stored in the 145[downloads site](http://dist.libuv.org/dist/) are signed and an accompanying 146signature file sit alongside each. Once both the release tarball and the 147signature file are downloaded, the file can be verified as follows: 148 149```bash 150$ gpg --verify libuv-1.7.0.tar.gz.sign 151``` 152 153## Build Instructions 154 155For GCC there are two build methods: via autotools or via [GYP][]. 156GYP is a meta-build system which can generate MSVS, Makefile, and XCode 157backends. It is best used for integration into other projects. 158 159To build with autotools: 160 161```bash 162$ sh autogen.sh 163$ ./configure 164$ make 165$ make check 166$ make install 167``` 168 169To build with [CMake](https://cmake.org/): 170 171```bash 172$ mkdir -p out/cmake ; cd out/cmake # create build directory 173$ cmake ../.. -DBUILD_TESTING=ON # generate project with test 174$ cmake --build . # build 175$ ctest -C Debug --output-on-failure # run tests 176 177# Or manually run tests: 178$ ./out/cmake/uv_run_tests # shared library build 179$ ./out/cmake/uv_run_tests_a # static library build 180``` 181 182To build with GYP, first run: 183 184```bash 185$ git clone https://chromium.googlesource.com/external/gyp build/gyp 186``` 187 188### Windows 189 190Prerequisites: 191 192* [Python 2.6 or 2.7][] as it is required 193 by [GYP][]. 194 If python is not in your path, set the environment variable `PYTHON` to its 195 location. For example: `set PYTHON=C:\Python27\python.exe` 196* One of: 197 * [Visual C++ Build Tools][] 198 * [Visual Studio 2015 Update 3][], all editions 199 including the Community edition (remember to select 200 "Common Tools for Visual C++ 2015" feature during installation). 201 * [Visual Studio 2017][], any edition (including the Build Tools SKU). 202 **Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the 203 Windows SDKs (10 or 8.1). 204* Basic Unix tools required for some tests, 205 [Git for Windows][] includes Git Bash 206 and tools which can be included in the global `PATH`. 207 208To build, launch a git shell (e.g. Cmd or PowerShell), run `vcbuild.bat` 209(to build with VS2017 you need to explicitly add a `vs2017` argument), 210which will checkout the GYP code into `build/gyp`, generate `uv.sln` 211as well as the necesery related project files, and start building. 212 213```console 214> vcbuild 215``` 216 217Or: 218 219```console 220> vcbuild vs2017 221``` 222 223To run the tests: 224 225```console 226> vcbuild test 227``` 228 229To see all the options that could passed to `vcbuild`: 230 231```console 232> vcbuild help 233vcbuild.bat [debug/release] [test/bench] [clean] [noprojgen] [nobuild] [vs2017] [x86/x64] [static/shared] 234Examples: 235 vcbuild.bat : builds debug build 236 vcbuild.bat test : builds debug build and runs tests 237 vcbuild.bat release bench: builds release build and runs benchmarks 238``` 239 240 241### Unix 242 243For Debug builds (recommended) run: 244 245```bash 246$ ./gyp_uv.py -f make 247$ make -C out 248``` 249 250For Release builds run: 251 252```bash 253$ ./gyp_uv.py -f make 254$ BUILDTYPE=Release make -C out 255``` 256 257Run `./gyp_uv.py -f make -Dtarget_arch=x32` to build [x32][] binaries. 258 259### OS X 260 261Run: 262 263```bash 264$ ./gyp_uv.py -f xcode 265$ xcodebuild -ARCHS="x86_64" -project out/uv.xcodeproj -configuration Release -alltargets 266``` 267 268Using Homebrew: 269 270```bash 271$ brew install --HEAD libuv 272``` 273 274Note to OS X users: 275 276Make sure that you specify the architecture you wish to build for in the 277"ARCHS" flag. You can specify more than one by delimiting with a space 278(e.g. "x86_64 i386"). 279 280### Android 281 282Run: 283 284For arm 285 286```bash 287$ source ./android-configure-arm NDK_PATH gyp [API_LEVEL] 288$ make -C out 289``` 290 291or for arm64 292 293```bash 294$ source ./android-configure-arm64 NDK_PATH gyp [API_LEVEL] 295$ make -C out 296``` 297 298or for x86 299 300```bash 301$ source ./android-configure-x86 NDK_PATH gyp [API_LEVEL] 302$ make -C out 303``` 304 305or for x86_64 306 307```bash 308$ source ./android-configure-x86_64 NDK_PATH gyp [API_LEVEL] 309$ make -C out 310``` 311 312The default API level is 24, but a different one can be selected as follows: 313 314```bash 315$ source ./android-configure-arm ~/android-ndk-r15b gyp 21 316$ make -C out 317``` 318 319Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and 320`-D_FILE_OFFSET_BITS=64`. GYP builds take care of that automatically. 321 322### Using Ninja 323 324To use ninja for build on ninja supported platforms, run: 325 326```bash 327$ ./gyp_uv.py -f ninja 328$ ninja -C out/Debug #for debug build OR 329$ ninja -C out/Release 330``` 331 332 333### Running tests 334 335#### Build 336 337Build (includes tests): 338 339```bash 340$ ./gyp_uv.py -f make 341$ make -C out 342``` 343 344#### Run all tests 345 346```bash 347$ ./out/Debug/run-tests 348``` 349 350#### Run one test 351 352The list of all tests is in `test/test-list.h`. 353 354This invocation will cause the `run-tests` driver to fork and execute `TEST_NAME` in a child process: 355 356```bash 357$ ./out/Debug/run-tests TEST_NAME 358``` 359 360This invocation will cause the `run-tests` driver to execute the test within the `run-tests` process: 361 362```bash 363$ ./out/Debug/run-tests TEST_NAME TEST_NAME 364``` 365 366#### Debugging tools 367 368When running the test from within the `run-tests` process (`run-tests TEST_NAME TEST_NAME`), tools like gdb and valgrind work normally. 369When running the test from a child of the `run-tests` process (`run-tests TEST_NAME`), use these tools in a fork-aware manner. 370 371##### Fork-aware gdb 372 373Use the [follow-fork-mode](https://sourceware.org/gdb/onlinedocs/gdb/Forks.html) setting: 374 375``` 376$ gdb --args out/Debug/run-tests TEST_NAME 377 378(gdb) set follow-fork-mode child 379... 380``` 381 382##### Fork-aware valgrind 383 384Use the `--trace-children=yes` parameter: 385 386```bash 387$ valgrind --trace-children=yes -v --tool=memcheck --leak-check=full --track-origins=yes --leak-resolution=high --show-reachable=yes --log-file=memcheck-%p.log out/Debug/run-tests TEST_NAME 388``` 389 390### Running benchmarks 391 392See the section on running tests. 393The benchmark driver is `out/Debug/run-benchmarks` and the benchmarks are listed in `test/benchmark-list.h`. 394 395## Supported Platforms 396 397Check the [SUPPORTED_PLATFORMS file](SUPPORTED_PLATFORMS.md). 398 399### AIX Notes 400 401AIX compilation using IBM XL C/C++ requires version 12.1 or greater. 402 403AIX support for filesystem events requires the non-default IBM `bos.ahafs` 404package to be installed. This package provides the AIX Event Infrastructure 405that is detected by `autoconf`. 406[IBM documentation](http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/) 407describes the package in more detail. 408 409AIX support for filesystem events is not compiled when building with `gyp`. 410 411### z/OS Notes 412 413z/OS creates System V semaphores and message queues. These persist on the system 414after the process terminates unless the event loop is closed. 415 416Use the `ipcrm` command to manually clear up System V resources. 417 418## Patches 419 420See the [guidelines for contributing][]. 421 422[node.js]: http://nodejs.org/ 423[GYP]: http://code.google.com/p/gyp/ 424[guidelines for contributing]: https://github.com/libuv/libuv/blob/master/CONTRIBUTING.md 425[libuv_banner]: https://raw.githubusercontent.com/libuv/libuv/master/img/banner.png 426[x32]: https://en.wikipedia.org/wiki/X32_ABI 427[Python 2.6 or 2.7]: https://www.python.org/downloads/ 428[Visual C++ Build Tools]: https://visualstudio.microsoft.com/visual-cpp-build-tools/ 429[Visual Studio 2015 Update 3]: https://www.visualstudio.com/vs/older-downloads/ 430[Visual Studio 2017]: https://www.visualstudio.com/downloads/ 431[Git for Windows]: http://git-scm.com/download/win 432