Repository files navigation

libuv is a multi-platform support library with a focus on asynchronous I/O. Itwas primarily developed for use byNode.js, but it's alsoused byLuvit,Julia,uvloop, andothers.

• Full-featured event loop backed by epoll, kqueue, IOCP, event ports.

• Asynchronous TCP and UDP sockets

• Asynchronous DNS resolution

• Asynchronous file and file system operations

• File system events

• ANSI escape code controlled TTY

• IPC with socket sharing, using Unix domain sockets or named pipes (Windows)

• Child processes

• Thread pool

• Signal handling

• High resolution clock

• Threading and synchronization primitives

Starting with version 1.0.0 libuv follows thesemantic versioningscheme. The API change and backwards compatibility rules are those indicated bySemVer. libuv will keep a stable ABI across major releases.

The ABI/API changes can be trackedhere.

libuv is licensed under the MIT license. Check theLICENSE andLICENSE-extra files.

The documentation is licensed under the CC BY 4.0 license. Check theLICENSE-docs file.

• Support
• Mailing list

Located in the docs/ subdirectory. It uses theSphinxframework, which makes it possible to build the documentation in multipleformats.

Show different supported building options:

$ makehelp

Build documentation as HTML:

$ make html

Build documentation as HTML and live reload it when it changes (this requiressphinx-autobuild to be installed and is only supported on Unix):

$ make livehtml

Build documentation as man pages:

$ make man

Build documentation as ePub:

$ make epub

NOTE: Windows users need to use make.bat instead of plain 'make'.

Documentation can be browsed onlinehere.

Thetests and benchmarksalso serve as API specification and usage examples.

• LXJS 2012 talk— High-level introductory talk about libuv.
• libuv-dox— Documenting types and methods of libuv, mostly by reading uv.h.
• learnuv— Learn uv for fun and profit, a self guided workshop to libuv.

These resources are not handled by libuv maintainers and might be out ofdate. Please verify it before opening new issues.

libuv can be downloaded either from theGitHub repositoryor from thedownloads site.

Before verifying the git tags or signature files, importing the relevant keysis necessary. Key IDs are listed in theMAINTAINERSfile, but are also available as git blob objects for easier use.

Importing a key the usual way:

$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059

Importing a key from a git blob object:

$ git show pubkey-saghul| gpg --import

Git tags are signed with the developer's key, they can be verified as follows:

$ git verify-tag v1.6.1

Starting with libuv 1.7.0, the tarballs stored in thedownloads site are signed and an accompanyingsignature file sit alongside each. Once both the release tarball and thesignature file are downloaded, the file can be verified as follows:

$ gpg --verify libuv-1.7.0.tar.gz.sign

For UNIX-like platforms, including macOS, there are two build methods:autotools orCMake.

For Windows,CMake is the only supported build method and has thefollowing prerequisites:

To build with autotools:

$ sh autogen.sh$ ./configure$ make$ make check$ make install

To build withCMake:

$ cmake -B build -DBUILD_TESTING=ON# generate project with tests$ cmake --build build# add `-j <n>` with cmake >= 3.12# Run tests:$ (cd build&& ctest -C Debug --output-on-failure)# Or manually run tests:$ build/uv_run_tests# shared library build$ build/uv_run_tests_a# static library build

To cross-compile withCMake (unsupported but generally works):

$ cmake ../..                 \  -DCMAKE_SYSTEM_NAME=Windows \  -DCMAKE_SYSTEM_VERSION=6.1  \  -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc

$ brew install --HEAD libuv

Note to OS X users:

Make sure that you specify the architecture you wish to build for in the"ARCHS" flag. You can specify more than one by delimiting with a space(e.g. "x86_64 i386").

$ git clone https://github.com/microsoft/vcpkg.git$ ./bootstrap-vcpkg.bat# for powershell$ ./bootstrap-vcpkg.sh# for bash$ ./vcpkg install libuv

You can install pre-built binaries for libuv or build it from source usingConan. Use the following command:

conan install --requires="libuv/[*]" --build=missing

The libuv Conan recipe is kept up to date by Conan maintainers and community contributors.If the version is out of date, pleasecreate an issue or pull request on the ConanCenterIndex repository.

Some tests are timing sensitive. Relaxing test timeouts may be necessaryon slow or overloaded machines:

$ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests# 10s instead of 5s

The list of all tests is intest/test-list.h.

This invocation will cause the test driver to fork and executeTEST_NAME ina child process:

$ build/uv_run_tests_a TEST_NAME

This invocation will cause the test driver to execute the test inthe same process:

$ build/uv_run_tests_a TEST_NAME TEST_NAME

When running the test from within the test driver process(build/uv_run_tests_a TEST_NAME TEST_NAME), tools like gdb and valgrindwork normally.

When running the test from a child of the test driver process(build/uv_run_tests_a TEST_NAME), use these tools in a fork-aware manner.

Use thefollow-fork-mode setting:

$ gdb --args build/uv_run_tests_a TEST_NAME(gdb) set follow-fork-mode child...

Use the--trace-children=yes parameter:

$ 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

See the section on running tests.The benchmark driver is./uv_run_benchmarks_a and the benchmarks arelisted intest/benchmark-list.h.

Check theSUPPORTED_PLATFORMS file.

It is recommended to turn on the-fno-strict-aliasing compiler flag inprojects that use libuv. The use of ad hoc "inheritance" in the libuv APImay not be safe in the presence of compiler optimizations that depend onstrict aliasing.

MSVC does not have an equivalent flag but it also does not appear to need itat the time of writing (December 2019.)

AIX compilation using IBM XL C/C++ requires version 12.1 or greater.

AIX support for filesystem events requires the non-default IBMbos.ahafspackage to be installed. This package provides the AIX Event Infrastructurethat is detected byautoconf.IBM documentationdescribes the package in more detail.

z/OS compilation requiresZOSLIB to be installed. When building withCMake, use the flag-DZOSLIB_DIR to specify the path toZOSLIB:

$ (cd build&& cmake .. -DBUILD_TESTING=ON -DZOSLIB_DIR=/path/to/zoslib)$ cmake --build build

z/OS creates System V semaphores and message queues. These persist on the systemafter the process terminates unless the event loop is closed.

Use theipcrm command to manually clear up System V resources.

See theguidelines for contributing.