Skip to content
Kessel

gRPC Compilation Issues in CI

The Kessel client SDKs depend on gRPC. When using Python or Ruby, you may encounter severe CI slowdowns or timeouts if forced to compile gRPC from source. This guide explains the problem and how to fix it.

Understanding the gRPC Dependency

Section titled “Understanding the gRPC Dependency”

Language-Specific Implementations

Section titled “Language-Specific Implementations”

gRPC has different implementations depending on the language:

  • Native library implementations (Python, Ruby): Use C-based gRPC core for performance

    • Require compilation or pre-built binaries
    • Installation complexity (mitigated by pre-built binaries)

  • Pure language implementations (Go, Java, Node.js): No native dependencies

    • Go: Pure Go implementation (grpc-go)
    • Java: Pure Java implementation (Netty-based)
    • Node.js: Pure JavaScript implementation (@grpc/grpc-js)
    • No external compilation needed (no C compiler required)

Pre-built Binaries vs. Compilation

Section titled “Pre-built Binaries vs. Compilation”

For languages using native libraries (Python, Ruby), installation times are not affected when using pre-built binaries. The gRPC project publishes pre-compiled wheels and gems for:

LanguageSDK RepositoryPre-built Platforms
Pythonkessel-sdk-pyLinux (x86_64, ARM64), macOS (universal2), Windows
Rubykessel-sdk-rubyLinux (gnu/musl, x86_64/ARM64), macOS (Intel/ARM), Windows

Compilation is only needed when:

  • Using an unsupported platform or architecture
  • Using a very new language version (e.g., Python 3.15 pre-release)
  • Pre-built wheels/gems are unavailable for your specific OS/architecture combination
  • You explicitly force compilation (e.g., pip install --no-binary :all: in Python)

When compilation does occur, it:

  • Requires a C/C++ compiler toolchain (gcc, clang, or MSVC)
  • Only happens on first install (or when gRPC versions change)

Local Development

Section titled “Local Development”

For SDK installation instructions and version requirements, see the Getting Started guide or the individual SDK repositories:

CI/CD Considerations

Section titled “CI/CD Considerations”

In most cases, CI builds use pre-built binaries and install quickly with no special configuration needed. Enable standard package manager caching (cache: 'pip' in GitHub Actions, etc.) for faster builds.

You only need special configuration when forced to compile from source (hermetic builds, unusual platforms). See the compilation limits section below for those cases.

When You Need to Compile

Section titled “When You Need to Compile”

In most cases, pre-built binaries handle everything automatically. If you’re doing hermetic builds or working on an unusual platform where pre-built binaries aren’t available, you may need to compile from source.

Limiting Parallel Compilation in CI

Section titled “Limiting Parallel Compilation in CI”

When building from source, limit the number of parallel compilation threads to prevent CI hangs and timeouts:

Terminal window
# Limit gRPC compilation to 4 parallel jobs
export GRPC_PYTHON_BUILD_EXT_COMPILER_JOBS=4
pip install kessel-sdk

In Dockerfile:

ENV GRPC_PYTHON_BUILD_EXT_COMPILER_JOBS=4
RUN pip install kessel-sdk

In GitHub Actions:

- name: Install dependencies
  env:
    GRPC_PYTHON_BUILD_EXT_COMPILER_JOBS: 4
  run: pip install kessel-sdk

See: grpcio parallel compilation

Why this happens:

  1. Package managers (pip, bundler) spawn parallel download/install processes
  2. gRPC’s C compilation also spawns parallel build processes (one per CPU by default)
  3. This double parallelism might cause memory pressure and CPU thrashing
  4. Result: Builds slow down dramatically or timeout

Build Requirements

Section titled “Build Requirements”

If compilation is needed (Python, Ruby only), ensure these tools are available:

  • Python: gcc, g++, python3-dev
  • Ruby: gcc, make, ruby-dev

Note: Node.js, Go, and Java do not require build tools as they don’t use native dependencies.

See the official gRPC installation guides for language-specific details.

Hermetic Build Systems

Section titled “Hermetic Build Systems”

For hermetic builds that force compilation from source:

  1. Include build dependencies (gcc, g++, python3-dev or ruby-dev)
  2. Limit parallel compilation (see above) to avoid resource contention and timeouts
  3. Expect longer build times

See gRPC build documentation for language-specific details.

Troubleshooting

Section titled “Troubleshooting”

Build Errors

Section titled “Build Errors”

If you encounter build errors, they’re typically due to missing compiler tools. Package managers provide clear error messages. Common solutions:

  • Python missing compiler: Install build-essential (Linux) or xcode-select --install (macOS)
  • Architecture issues: Ensure your Python/Ruby version matches your system architecture (especially on Apple Silicon)
  • Long CI build times: Enable caching (see CI/CD section)

For detailed build requirements, refer to the official gRPC installation guides.

Summary

Section titled “Summary”

Key points about gRPC compilation:

  1. Pre-built binaries are available - Python and Ruby have pre-built wheels/gems for common platforms, avoiding compilation
  2. When forced to compile (hermetic builds, unusual platforms) - LIMIT parallel build threads to prevent CI timeouts (see compilation limits)
  3. Python and Ruby only - Node.js, Go, and Java don’t use native gRPC and never need external compilation
  4. Docker: Use glibc-based images - Red Hat UBI or Debian images work with pre-built binaries; Alpine (musl) may force compilation

Additional Resources

Section titled “Additional Resources”

Kessel SDK Repositories

Section titled “Kessel SDK Repositories”

Documentation

Section titled “Documentation”