libuv/libuv

 ## 概述 libuv 是一个专注于异步 I/O 的多平台支持库。它主要是为 [Node.js][] 开发的，但也 被 [Luvit](http://luvit.io/)、[Julia](http://julialang.org/)、 [uvloop](https://github.com/MagicStack/uvloop) 和 [其他项目](https://github.com/libuv/libuv/blob/v1.x/LINKS.md) 所使用。 ## 主要特性 * 基于 epoll、kqueue、IOCP、event ports 的全功能事件循环。 * 异步 TCP 和 UDP 套接字 * 异步 DNS 解析 * 异步文件和文件系统操作 * 文件系统事件 * ANSI 转义码控制的 TTY * 支持套接字共享的 IPC，使用 Unix 域套接字或命名管道 (Windows) * 子进程 * 线程池 * 信号处理 * 高分辨率时钟 * 线程和同步原语 ## 版本控制 从 1.0.0 版本开始，libuv 遵循 [语义化版本](http://semver.org/) 规范。API 变更和向后兼容性规则遵循 SemVer 的规定。libuv 将在主要版本之间保持稳定的 ABI。 ABI/API 的变更可以在[此处](http://abi-laboratory.pro/tracker/timeline/libuv/)追踪。 ## 许可证 libuv 根据 MIT 许可证授权。请查看 [LICENSE](LICENSE) 和 [LICENSE-extra](LICENSE-extra) 文件。 文档根据 CC BY 4.0 许可证授权。请查看 [LICENSE-docs file](LICENSE-docs)。 ## 文档 ### 官方文档 位于 docs/ 子目录中。它使用 [Sphinx](http://sphinx-doc.org/) 框架，这使得以多种格式构建文档成为可能。 显示不同的支持构建选项： ``` $ make help ``` 将文档构建为 HTML： ``` $ make html ``` 将文档构建为 HTML 并在更改时实时重新加载（这需要 安装 sphinx-autobuild 且仅在 Unix 上受支持）： ``` $ make livehtml ``` 将文档构建为 man 手册页： ``` $ make man ``` 将文档构建为 ePub： ``` $ make epub ``` 注意：Windows 用户需要使用 make.bat 而不是普通的 'make'。 可以在[此处](http://docs.libuv.org)在线浏览文档。 [测试和基准测试](https://github.com/libuv/libuv/tree/master/test) 也可作为 API 规范和使用示例。 ### 其他资源 * [LXJS 2012 演讲](http://www.youtube.com/watch?v=nGn60vDSxQ4) — 关于 libuv 的高层次介绍性演讲。 * [libuv-dox](https://github.com/thlorenz/libuv-dox) — 文档化 libuv 的类型和方法，主要是通过阅读 uv.h。 * [learnuv](https://github.com/thlorenz/learnuv) — 为了乐趣和收益学习 uv，一个 libuv 的自学研讨会。 这些资源不由 libuv 维护者管理，可能已经过时。 请在提出新问题之前进行核实。 ## 下载 libuv 可以从 [GitHub 仓库](https://github.com/libuv/libuv) 或从[下载站点](http://dist.libuv.org/dist/)下载。 在验证 git 标签或签名文件之前，需要导入相关的密钥。 密钥 ID 列在 [MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md) 文件中，但也作为 git blob 对象提供以便于使用。 以通常的方式导入密钥： ``` $ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059 ``` 从 git blob 对象导入密钥： ``` $ git show pubkey-saghul | gpg --import ``` ### 验证发布版本 Git 标签使用开发者的密钥签名，可以通过以下方式进行验证： ``` $ git verify-tag v1.6.1 ``` 从 libuv 1.7.0 开始，存储在 [下载站点](http://dist.libuv.org/dist/) 中的压缩包 已签名，并且每个压缩包旁边都有一个附带的 签名文件。下载发布压缩包和 签名文件后，可以按如下方式验证文件： ``` $ gpg --verify libuv-1.7.0.tar.gz.sign ``` ## 构建说明 对于类 UNIX 平台，包括 macOS，有两种构建方法： autotools 或 [CMake][]。 对于 Windows，[CMake][] 是唯一支持的构建方法，并且 具有以下先决条件：

* 以下之一： * [Visual C++ Build Tools][] * [Visual Studio 2015 Update 3][]，所有版本 包括社区版（请记住在安装过程中选择 “Common Tools for Visual C++ 2015” 功能）。 * [Visual Studio 2017][]，任何版本（包括 Build Tools SKU）。 **所需组件：** “MSbuild”、“VC++ 2017 v141 toolset” 以及其中一个 Windows SDK（10 或 8.1）。 * 某些测试所需的基本 Unix 工具， [Git for Windows][] 包括 Git Bash 和可以包含在全局 `PATH` 中的工具。

使用 autotools 构建： ``` $ sh autogen.sh $ ./configure $ make $ make check $ make install ``` 使用 [CMake][] 构建： ``` $ cmake -B build -DBUILD_TESTING=ON # generate project with tests $ cmake --build build # add `-j ` with cmake >= 3.12 # 运行测试： $ (cd build && ctest -C Debug --output-on-failure) # 或手动运行测试： $ build/uv_run_tests # shared library build $ build/uv_run_tests_a # static library build ``` 使用 [CMake][] 进行交叉编译（不受支持但通常有效）： ``` $ cmake ../.. \ -DCMAKE_SYSTEM_NAME=Windows \ -DCMAKE_SYSTEM_VERSION=6.1 \ -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc ``` ### 使用 Homebrew 安装 ``` $ brew install --HEAD libuv ``` 致 macOS 用户注意： 确保在“ARCHS”标志中指定您希望构建的 架构。您可以通过用空格分隔来指定多个架构 （例如 "x86_64 i386"）。 ### 使用 vcpkg 安装 ``` $ git clone https://github.com/microsoft/vcpkg.git $ ./bootstrap-vcpkg.bat # for powershell $ ./bootstrap-vcpkg.sh # for bash $ ./vcpkg install libuv ``` ### 使用 Conan 安装 您可以使用 [Conan](https://conan.io/) 安装 libuv 的预构建二进制文件或从源代码构建它。使用以下命令： ``` conan install --requires="libuv/[*]" --build=missing ``` libuv Conan 配方由 Conan 维护者和社区贡献者保持最新。 如果版本已过时，请在 ConanCenterIndex 仓库中[创建 issue 或 pull request](https://github.com/conan-io/conan-center-index)。 ### 运行测试 某些测试对时间敏感。在缓慢或超载的机器上，可能需要放宽测试超时时间： ``` $ env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests # 10s instead of 5s ``` #### 运行单个测试 所有测试的列表位于 `test/test-list.h` 中。 此调用将导致测试驱动程序分叉并在 子进程中执行 `TEST_NAME`： ``` $ build/uv_run_tests_a TEST_NAME ``` 此调用将导致测试驱动程序在 同一进程中执行测试： ``` $ build/uv_run_tests_a TEST_NAME TEST_NAME ``` #### 调试工具 在测试驱动程序进程内运行测试时 （`build/uv_run_tests_a TEST_NAME TEST_NAME`），gdb 和 valgrind 等工具可以正常工作。 在测试驱动程序进程的子进程中运行测试时 （`build/uv_run_tests_a TEST_NAME`），请以支持分叉的方式使用这些工具。 ##### 支持分叉的 gdb 使用 [follow-fork-mode](https://sourceware.org/gdb/onlinedocs/gdb/Forks.html) 设置： ``` $ gdb --args build/uv_run_tests_a TEST_NAME (gdb) set follow-fork-mode child ... ``` ##### 支持分叉的 valgrind 使用 `--trace-children=yes` 参数： ``` $ 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 ``` ### 运行基准测试 请参阅运行测试部分。 基准测试驱动程序是 `./uv_run_benchmarks_a`，基准测试 列在 `test/benchmark-list.h` 中。 ## 支持的平台 请查看 [SUPPORTED_PLATFORMS 文件](SUPPORTED_PLATFORMS.md)。 ### `-fno-strict-aliasing` 建议在使用 libuv 的项目中开启 `-fno-strict-aliasing` 编译器标志。 libuv API 中临时性的“继承”使用在存在依赖于 严格别名的编译器优化的情况下可能不安全。 MSVC 没有等效的标志，但在撰写本文时 （2019 年 12 月）它似乎也不需要它。 ### AIX 说明 使用 IBM XL C/C++ 进行 AIX 编译需要 12.1 或更高版本。 AIX 对文件系统事件的支持需要安装非默认的 IBM `bos.ahafs` 包。此包提供了 `autoconf` 检测到的 AIX 事件基础设施。 [IBM 文档](http://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/) 更详细地描述了该包。 ### z/OS 说明 z/OS 编译需要安装 [ZOSLIB](https://github.com/ibmruntimes/zoslib)。使用 [CMake][] 构建时，使用标志 `-DZOSLIB_DIR` 指定 [ZOSLIB](https://github.com/ibmruntimes/zoslib) 的路径： ``` $ (cd build && cmake .. -DBUILD_TESTING=ON -DZOSLIB_DIR=/path/to/zoslib) $ cmake --build build ``` z/OS 创建 System V 信号量和消息队列。除非关闭事件循环，否则这些资源在进程终止后 仍会保留在系统上。 使用 `ipcrm` 命令手动清理 System V 资源。 ## 补丁 请参阅 [贡献指南][]。

标签：API, Bash脚本, C语言库, epoll, GNU通用公共许可证, IOCP, kqueue, libuv, Node.js, TCP/UDP, 事件循环, 事件驱动, 后端开发, 子域名枚举工具, 客户端加密, 底层开发, 开源库, 异步I/O, 搜索引擎爬虫, 文件系统, 系统编程, 网络编程, 跨平台库