forked from cory/tildefriends
Cory McWilliams
79022e1e1f
git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@3621 ed5197a5-7fde-0310-b194-c3ffbd925b24
318 lines
8.5 KiB
Markdown
318 lines
8.5 KiB
Markdown
![libuv][libuv_banner]
|
|
|
|
## Overview
|
|
|
|
libuv is a multi-platform support library with a focus on asynchronous I/O. It
|
|
was primarily developed for use by [Node.js][], but it's also
|
|
used by [Luvit](http://luvit.io/), [Julia](http://julialang.org/),
|
|
[pyuv](https://github.com/saghul/pyuv), and [others](https://github.com/libuv/libuv/wiki/Projects-that-use-libuv).
|
|
|
|
## Feature highlights
|
|
|
|
* 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
|
|
|
|
## Versioning
|
|
|
|
Starting with version 1.0.0 libuv follows the [semantic versioning](http://semver.org/)
|
|
scheme. The API change and backwards compatibility rules are those indicated by
|
|
SemVer. libuv will keep a stable ABI across major releases.
|
|
|
|
The ABI/API changes can be tracked [here](http://abi-laboratory.pro/tracker/timeline/libuv/).
|
|
|
|
## Licensing
|
|
|
|
libuv is licensed under the MIT license. Check the [LICENSE file](LICENSE).
|
|
The documentation is licensed under the CC BY 4.0 license. Check the [LICENSE-docs file](LICENSE-docs).
|
|
|
|
## Community
|
|
|
|
* [Support](https://github.com/libuv/help)
|
|
* [Mailing list](http://groups.google.com/group/libuv)
|
|
* [IRC chatroom (#libuv@irc.freenode.org)](http://webchat.freenode.net?channels=libuv&uio=d4)
|
|
|
|
## Documentation
|
|
|
|
### Official documentation
|
|
|
|
Located in the docs/ subdirectory. It uses the [Sphinx](http://sphinx-doc.org/)
|
|
framework, which makes it possible to build the documentation in multiple
|
|
formats.
|
|
|
|
Show different supported building options:
|
|
|
|
```bash
|
|
$ make help
|
|
```
|
|
|
|
Build documentation as HTML:
|
|
|
|
```bash
|
|
$ make html
|
|
```
|
|
|
|
Build documentation as HTML and live reload it when it changes (this requires
|
|
sphinx-autobuild to be installed and is only supported on Unix):
|
|
|
|
```bash
|
|
$ make livehtml
|
|
```
|
|
|
|
Build documentation as man pages:
|
|
|
|
```bash
|
|
$ make man
|
|
```
|
|
|
|
Build documentation as ePub:
|
|
|
|
```bash
|
|
$ make epub
|
|
```
|
|
|
|
NOTE: Windows users need to use make.bat instead of plain 'make'.
|
|
|
|
Documentation can be browsed online [here](http://docs.libuv.org).
|
|
|
|
The [tests and benchmarks](https://github.com/libuv/libuv/tree/master/test)
|
|
also serve as API specification and usage examples.
|
|
|
|
### Other resources
|
|
|
|
* [LXJS 2012 talk](http://www.youtube.com/watch?v=nGn60vDSxQ4)
|
|
— High-level introductory talk about libuv.
|
|
* [libuv-dox](https://github.com/thlorenz/libuv-dox)
|
|
— Documenting types and methods of libuv, mostly by reading uv.h.
|
|
* [learnuv](https://github.com/thlorenz/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 of
|
|
date. Please verify it before opening new issues.
|
|
|
|
## Downloading
|
|
|
|
libuv can be downloaded either from the
|
|
[GitHub repository](https://github.com/libuv/libuv)
|
|
or from the [downloads site](http://dist.libuv.org/dist/).
|
|
|
|
Before verifying the git tags or signature files, importing the relevant keys
|
|
is necessary. Key IDs are listed in the
|
|
[MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md)
|
|
file, but are also available as git blob objects for easier use.
|
|
|
|
Importing a key the usual way:
|
|
|
|
```bash
|
|
$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059
|
|
```
|
|
|
|
Importing a key from a git blob object:
|
|
|
|
```bash
|
|
$ git show pubkey-saghul | gpg --import
|
|
```
|
|
|
|
### Verifying releases
|
|
|
|
Git tags are signed with the developer's key, they can be verified as follows:
|
|
|
|
```bash
|
|
$ git verify-tag v1.6.1
|
|
```
|
|
|
|
Starting with libuv 1.7.0, the tarballs stored in the
|
|
[downloads site](http://dist.libuv.org/dist/) are signed and an accompanying
|
|
signature file sit alongside each. Once both the release tarball and the
|
|
signature file are downloaded, the file can be verified as follows:
|
|
|
|
```bash
|
|
$ gpg --verify libuv-1.7.0.tar.gz.sign
|
|
```
|
|
|
|
## Build Instructions
|
|
|
|
For UNIX-like platforms, including macOS, there are two build methods:
|
|
autotools or [CMake][].
|
|
|
|
For Windows, [CMake][] is the only supported build method and has the
|
|
following prerequisites:
|
|
|
|
<details>
|
|
|
|
* One of:
|
|
* [Visual C++ Build Tools][]
|
|
* [Visual Studio 2015 Update 3][], all editions
|
|
including the Community edition (remember to select
|
|
"Common Tools for Visual C++ 2015" feature during installation).
|
|
* [Visual Studio 2017][], any edition (including the Build Tools SKU).
|
|
**Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the
|
|
Windows SDKs (10 or 8.1).
|
|
* Basic Unix tools required for some tests,
|
|
[Git for Windows][] includes Git Bash
|
|
and tools which can be included in the global `PATH`.
|
|
|
|
</details>
|
|
|
|
To build with autotools:
|
|
|
|
```bash
|
|
$ sh autogen.sh
|
|
$ ./configure
|
|
$ make
|
|
$ make check
|
|
$ make install
|
|
```
|
|
|
|
To build with [CMake][]:
|
|
|
|
```bash
|
|
$ mkdir -p build
|
|
|
|
$ (cd build && cmake .. -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 with [CMake][] (unsupported but generally works):
|
|
|
|
```bash
|
|
$ cmake ../.. \
|
|
-DCMAKE_SYSTEM_NAME=Windows \
|
|
-DCMAKE_SYSTEM_VERSION=6.1 \
|
|
-DCMAKE_C_COMPILER=i686-w64-mingw32-gcc
|
|
```
|
|
|
|
### Install with Homebrew
|
|
|
|
```bash
|
|
$ 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").
|
|
|
|
### Running tests
|
|
|
|
Some tests are timing sensitive. Relaxing test timeouts may be necessary
|
|
on slow or overloaded machines:
|
|
|
|
```bash
|
|
$ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests # 10s instead of 5s
|
|
```
|
|
|
|
#### Run one test
|
|
|
|
The list of all tests is in `test/test-list.h`.
|
|
|
|
This invocation will cause the test driver to fork and execute `TEST_NAME` in
|
|
a child process:
|
|
|
|
```bash
|
|
$ build/uv_run_tests_a TEST_NAME
|
|
```
|
|
|
|
This invocation will cause the test driver to execute the test in
|
|
the same process:
|
|
|
|
```bash
|
|
$ build/uv_run_tests_a TEST_NAME TEST_NAME
|
|
```
|
|
|
|
#### Debugging tools
|
|
|
|
When running the test from within the test driver process
|
|
(`build/uv_run_tests_a TEST_NAME TEST_NAME`), tools like gdb and valgrind
|
|
work 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.
|
|
|
|
##### Fork-aware gdb
|
|
|
|
Use the [follow-fork-mode](https://sourceware.org/gdb/onlinedocs/gdb/Forks.html) setting:
|
|
|
|
```
|
|
$ gdb --args build/uv_run_tests_a TEST_NAME
|
|
|
|
(gdb) set follow-fork-mode child
|
|
...
|
|
```
|
|
|
|
##### Fork-aware valgrind
|
|
|
|
Use the `--trace-children=yes` parameter:
|
|
|
|
```bash
|
|
$ 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
|
|
```
|
|
|
|
### Running benchmarks
|
|
|
|
See the section on running tests.
|
|
The benchmark driver is `./uv_run_benchmarks_a` and the benchmarks are
|
|
listed in `test/benchmark-list.h`.
|
|
|
|
## Supported Platforms
|
|
|
|
Check the [SUPPORTED_PLATFORMS file](SUPPORTED_PLATFORMS.md).
|
|
|
|
### AIX Notes
|
|
|
|
AIX compilation using IBM XL C/C++ requires version 12.1 or greater.
|
|
|
|
AIX support for filesystem events requires the non-default IBM `bos.ahafs`
|
|
package to be installed. This package provides the AIX Event Infrastructure
|
|
that is detected by `autoconf`.
|
|
[IBM documentation](http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/)
|
|
describes the package in more detail.
|
|
|
|
### z/OS Notes
|
|
|
|
z/OS creates System V semaphores and message queues. These persist on the system
|
|
after the process terminates unless the event loop is closed.
|
|
|
|
Use the `ipcrm` command to manually clear up System V resources.
|
|
|
|
## Patches
|
|
|
|
See the [guidelines for contributing][].
|
|
|
|
[CMake]: https://cmake.org/
|
|
[node.js]: http://nodejs.org/
|
|
[guidelines for contributing]: https://github.com/libuv/libuv/blob/master/CONTRIBUTING.md
|
|
[libuv_banner]: https://raw.githubusercontent.com/libuv/libuv/master/img/banner.png
|
|
[Visual C++ Build Tools]: https://visualstudio.microsoft.com/visual-cpp-build-tools/
|
|
[Visual Studio 2015 Update 3]: https://www.visualstudio.com/vs/older-downloads/
|
|
[Visual Studio 2017]: https://www.visualstudio.com/downloads/
|
|
[Git for Windows]: http://git-scm.com/download/win
|