libuv Deployment and Usage Guide

1. Prerequisites

Required Tools

• C Compiler: GCC, Clang, or MSVC (Visual Studio 2015 Update 3 or later)
• CMake 3.12+ (recommended for all platforms) or GNU Autotools (Unix-like only)
• Git for source verification and cloning
• Python 3 + Sphinx (optional, for building documentation)

Platform-Specific Requirements

macOS:

• Xcode Command Line Tools: xcode-select --install
• For multi-architecture builds: ensure ARCHS environment variable is set (e.g., x86_64 arm64)

Windows:

• Visual Studio 2015 Update 3, 2017, 2019, or 2022 (Community edition works), OR
• Visual C++ Build Tools with components:
  • MSBuild
  • VC++ toolset (v141 or later)
  • Windows SDK (10 or 8.1)
• Git for Windows (provides Unix tools required for tests)

Linux:

• Build essentials: sudo apt-get install build-essential cmake (Debian/Ubuntu) or equivalent
• Autotools (if using that build method): autoconf, automake, libtool

2. Installation

Method A: Package Managers (Recommended for End Users)

macOS (Homebrew):

brew install libuv
# For latest development version:
brew install --HEAD libuv

Windows/macOS/Linux (vcpkg):

git clone https://github.com/microsoft/vcpkg.git
./bootstrap-vcpkg.bat  # Windows PowerShell
./bootstrap-vcpkg.sh   # Unix shells
./vcpkg install libuv

Method B: Build from Source

Clone and verify:

git clone https://github.com/libuv/libuv.git
cd libuv
git checkout v1.x  # or specific version tag

# Optional: Verify GPG signature
git verify-tag v1.48.0  # replace with your target version

Build with CMake (All Platforms):

cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=ON \
  -DCMAKE_INSTALL_PREFIX=/usr/local

cmake --build build -j$(nproc)  # Linux/macOS
# or: cmake --build build -j %NUMBER_OF_PROCESSORS%  # Windows CMD

# Run tests
cd build && ctest -C Release --output-on-failure

Build with Autotools (Unix-like only):

sh autogen.sh
./configure --prefix=/usr/local
make -j$(nproc)
make check  # Run tests
sudo make install

Install to system:

# CMake
sudo cmake --install build

# Autotools
sudo make install
sudo ldconfig  # Linux only: update library cache

3. Configuration

CMake Build Options

Configure via -DOPTION=value:

Cross-Compilation

Windows (MinGW from Linux):

cmake -B build \
  -DCMAKE_SYSTEM_NAME=Windows \
  -DCMAKE_SYSTEM_VERSION=6.1 \
  -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc

macOS (Universal Binary):

cmake -B build -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"

Environment Variables

# Specify compiler
export CC=clang
export CXX=clang++

# macOS architecture selection
export ARCHS="x86_64 arm64"

4. Build & Run

Development Build (Debug with Tests)

cmake -B build-debug \
  -DCMAKE_BUILD_TYPE=Debug \
  -DBUILD_TESTING=ON \
  -DCMAKE_INSTALL_PREFIX=$PWD/install-debug

cmake --build build-debug -j$(nproc)

# Run all tests
cd build-debug && ctest --output-on-failure

# Run specific test executable
./uv_run_tests_a  # Static version
./uv_run_tests    # Shared version

Production Build (Optimized)

cmake -B build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=OFF \
  -DBUILD_SHARED_LIBS=ON

cmake --build build-release
sudo cmake --install build-release

Building Documentation

cd docs
make html      # Standard HTML
make livehtml  # Auto-reload dev server (Unix only, requires sphinx-autobuild)
make man       # Man pages
make epub      # eBook format

Windows documentation build:

cd docs
make.bat html

5. Deployment

System Integration

pkg-config (Unix): After make install, libuv installs libuv.pc. Use in your builds:

gcc myapp.c $(pkg-config --cflags --libs libuv) -o myapp

CMake Integration: In your project's CMakeLists.txt:

find_package(libuv REQUIRED)
target_link_libraries(myapp PRIVATE uv)

Static Linking (Self-Contained)

For standalone binaries, link statically:

cmake -B build-static -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build-static
# Link against build-static/libuv_a.a (or uv.lib on Windows)

Docker Deployment

# Build stage
FROM gcc:latest as builder
RUN apt-get update && apt-get install -y cmake
COPY . /src
WORKDIR /src
RUN cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build

# Runtime stage (minimal)
FROM debian:stable-slim
COPY --from=builder /src/build/libuv.so* /usr/lib/
# Copy your application that links to libuv

CI/CD Integration

GitHub Actions example:

- name: Install libuv
  run: |
    git clone https://github.com/libuv/libuv.git --depth 1 --branch v1.x
    cd libuv && cmake -B build && sudo cmake --install build

6. Troubleshooting

Build Issues

"CMake Error: Could not find CMAKE_ROOT": Ensure CMake is properly installed and in PATH. On Windows, use "Developer Command Prompt for VS".

Autogen fails with "autoreconf: not found":

# Ubuntu/Debian
sudo apt-get install autoconf automake libtool

# macOS
brew install autoconf automake libtool

Windows: "Windows SDK not found": Re-run Visual Studio Installer and ensure "Windows 10/11 SDK" is checked under Individual Components.

macOS: "Architecture not supported" errors: Explicitly set architectures:

export CFLAGS="-arch x86_64 -arch arm64"
export LDFLAGS="-arch x86_64 -arch arm64"
cmake -B build

Test Failures

Tests fail with "udp_multicast_join6": IPv6 multicast may be disabled on your network interface. This is usually benign; check if ifconfig shows multicast support.

Permission errors in fs tests: Some tests require write access to /tmp or current directory. Run tests from a writable directory.

Runtime Issues

"error while loading shared libraries: libuv.so.1":

# Linux: Update library cache
sudo ldconfig

# Or set LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# macOS
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH

Linking errors (undefined reference to uv_*): Ensure linking order places -luv after your object files:

gcc app.c -o app -luv  # Correct
gcc -luv app.c -o app  # Wrong (usually)

Static linking conflicts: If linking statically against libuv but dynamically against other libs, ensure consistent CRT linkage on Windows (/MD vs /MT).