{"id":34656202,"url":"https://github.com/marcoroth/rake-cross-compiler","last_synced_at":"2025-12-26T21:24:09.182Z","repository":{"id":329587688,"uuid":"1120147435","full_name":"marcoroth/rake-cross-compiler","owner":"marcoroth","description":"Cross-compile Ruby native extensions using Zig as a drop-in cross-compiler.","archived":false,"fork":false,"pushed_at":"2025-12-20T20:11:32.000Z","size":66,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T17:44:18.098Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcoroth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"marcoroth"}},"created_at":"2025-12-20T15:33:19.000Z","updated_at":"2025-12-21T20:55:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcoroth/rake-cross-compiler","commit_stats":null,"previous_names":["marcoroth/rake-cross-compiler"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/marcoroth/rake-cross-compiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoroth%2Frake-cross-compiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoroth%2Frake-cross-compiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoroth%2Frake-cross-compiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoroth%2Frake-cross-compiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcoroth","download_url":"https://codeload.github.com/marcoroth/rake-cross-compiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcoroth%2Frake-cross-compiler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28005977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T18:02:49.067Z","updated_at":"2025-12-24T18:05:34.113Z","avatar_url":"https://github.com/marcoroth.png","language":"Ruby","funding_links":["https://github.com/sponsors/marcoroth"],"categories":[],"sub_categories":[],"readme":"# rake-cross-compiler\n\nCross-compile Ruby native extensions using [Zig](https://ziglang.org/) as a drop-in C/C++ cross-compiler.\n\nA lightweight alternative to [rake-compiler-dock](https://github.com/rake-compiler/rake-compiler-dock) that doesn't require Docker.\n\n## Why?\n\nBuilding native Ruby gems for multiple platforms traditionally requires:\n- Docker containers with pre-configured cross-compilation toolchains\n- Heavy disk usage and slow container startup times\n- Complex setup for each target platform\n\n**rake-cross-compiler** uses Zig's built-in cross-compilation capabilities instead:\n- No Docker required\n- Single `zig` binary handles all targets\n- Cross-compile from any OS to Linux, macOS, and Windows\n- Vendored Ruby headers for all supported platforms and Ruby versions\n\n## Installation\n\nInstall the gem:\n\n```bash\ngem install rake-cross-compiler\n```\n\nOr add to your Gemfile:\n\n```ruby\ngem \"rake-cross-compiler\"\n```\n\nYou'll also need [Zig](https://ziglang.org/download/) installed (version 0.13.0 or later). If Zig is not installed, rake-cross-compiler can auto-download it.\n\n## Usage\n\n### Basic Usage\n\n```ruby\nrequire \"rake_cross_compiler\"\n```\n\n**Cross-compile for Linux x86_64**\n```ruby\nRake::Cross::Compiler.sh(\"bundle \u0026\u0026 rake compile\", platform: \"x86_64-linux\")\n```\n\n**Or use the convenience alias**\n```ruby\nRakeCrossCompiler.sh(\"bundle \u0026\u0026 rake compile\", platform: \"aarch64-linux\")\n```\n\n### Multiple Platforms\n\n```ruby\nRakeCrossCompiler.sh(\"rake native gem\", platform: \"x86_64-linux aarch64-linux arm64-darwin\")\n```\n\n### In a Rakefile (Recommended)\n\nThe easiest integration with rake-compiler in `Rakefile`:\n\n```ruby\nrequire \"rake/extensiontask\"\nrequire \"rake_cross_compiler\"\n\nPLATFORMS = %w[\n  x86_64-linux-gnu\n  aarch64-linux-gnu\n  x86_64-linux-musl\n  aarch64-linux-musl\n  arm64-darwin\n  x86_64-darwin\n].freeze\n\nRake::ExtensionTask.new(\"my_extension\") do |ext|\n  ext.cross_compile = true\n  ext.cross_platform = PLATFORMS\nend\n\nnamespace :gem do\n  task :prepare do\n    spec = Gem::Specification.load(\"my_gem.gemspec\")\n\n    # Set RUBY_CC_VERSION based on gemspec and available platforms\n    Rake::Cross::Compiler.set_ruby_cc_version(spec.required_ruby_version, platforms: PLATFORMS)\n\n    # Set up cross-Ruby configurations for rake-compiler\n    Rake::Cross::Compiler.setup_cross_ruby(platforms: PLATFORMS)\n  end\n\n  PLATFORMS.each do |platform|\n    desc \"Build native gem for #{platform}\"\n    task platform =\u003e :prepare do\n      Rake::Cross::Compiler.sh(\n        \"bundle --local \u0026\u0026 rake native:#{platform} gem\",\n        platform: platform\n      )\n    end\n  end\n\n  desc \"Build all native gems\"\n  task :native =\u003e PLATFORMS\nend\n```\n\nThen build gems:\n\n```bash\nbundle exec rake gem:prepare           # Set up cross-ruby configs\nbundle exec rake gem:x86_64-linux-gnu  # Build for one platform\nbundle exec rake gem:native            # Build for all platforms\n```\n\n### Error Handling\n\n```ruby\nRakeCrossCompiler.sh(\"rake compile\", platform: \"x86_64-linux\") do |ok, status|\n  if ok\n    puts \"Build succeeded!\"\n  else\n    puts \"Build failed with status: #{status.exitstatus}\"\n  end\nend\n```\n\n### Getting Environment Variables\n\nFor manual integration or debugging:\n\n```ruby\nenv = RakeCrossCompiler.env_for(\"x86_64-linux\")\n# =\u003e {\n#      \"CC\" =\u003e \"zig cc -target x86_64-linux-gnu\",\n#      \"CXX\" =\u003e \"zig c++ -target x86_64-linux-gnu\",\n#      \"AR\" =\u003e \"zig ar\",\n#      \"RANLIB\" =\u003e \"zig ranlib\",\n#      ...\n#    }\n```\n\n### With Extra Compiler Flags\n\n```ruby\nRakeCrossCompiler.sh(\n  \"rake compile\",\n  platform: \"x86_64-linux\",\n  cflags: [\"-O2\", \"-Wall\"],\n  ldflags: [\"-lm\"]\n)\n```\n\n## Supported Platforms\n\n| Ruby Platform | Zig Target |\n|---------------|------------|\n| `x86_64-linux` | `x86_64-linux-gnu` |\n| `x86_64-linux-gnu` | `x86_64-linux-gnu` |\n| `x86_64-linux-musl` | `x86_64-linux-musl` |\n| `aarch64-linux` | `aarch64-linux-gnu` |\n| `aarch64-linux-gnu` | `aarch64-linux-gnu` |\n| `aarch64-linux-musl` | `aarch64-linux-musl` |\n| `x86-linux` | `x86-linux-gnu` |\n| `x86-linux-gnu` | `x86-linux-gnu` |\n| `x86-linux-musl` | `x86-linux-musl` |\n| `arm-linux` | `arm-linux-gnueabihf` |\n| `arm-linux-gnu` | `arm-linux-gnueabihf` |\n| `arm-linux-musl` | `arm-linux-musleabihf` |\n| `x86_64-darwin` | `x86_64-macos` |\n| `arm64-darwin` | `aarch64-macos` |\n| `x64-mingw32` | `x86_64-windows-gnu` |\n| `x64-mingw-ucrt` | `x86_64-windows-gnu` |\n| `x86-mingw32` | `x86-windows-gnu` |\n\n### Supported Ruby Versions\n\nVendored headers are available for:\n- Ruby 3.0.0, 3.1.0, 3.2.0, 3.3.0, 3.4.0, 4.0.0\n\nNote: Not all Ruby versions are available for all platforms. For example, `arm64-darwin` only has Ruby 3.1.0+. The gem automatically detects which versions are available for your target platforms.\n\n## API Reference\n\n### `Rake::Cross::Compiler.sh(cmd, **options)`\n\nRun a shell command with cross-compilation environment.\n\n```ruby\nRake::Cross::Compiler.sh(\n  \"rake compile\",\n  platform: \"x86_64-linux\",\n  verbose: true,\n  cflags: [\"-O2\"],\n  ldflags: [\"-lm\"],\n  env: { \"DEBUG\" =\u003e \"1\" },\n  ruby_cc_version: \"3.3.0:3.4.0\",\n  check_zig: true\n)\n```\n\nOptions:\n- `platform:` - Target platform(s), space-separated (default: `\"x86_64-linux\"`)\n- `verbose:` - Print command info (default: follows Rake's verbose flag)\n- `cflags:` - Additional CFLAGS as array\n- `ldflags:` - Additional LDFLAGS as array\n- `env:` - Additional environment variables as hash\n- `ruby_cc_version:` - RUBY_CC_VERSION value\n- `check_zig:` - Verify Zig installation (default: `true`)\n\n### `Rake::Cross::Compiler.exec(*args, **options)`\n\nRun a command directly (without shell) with cross-compilation environment. Same options as `sh`.\n\n### `Rake::Cross::Compiler.env_for(platform, cflags: [], ldflags: [])`\n\nGet environment variables hash for a platform.\n\n### `Rake::Cross::Compiler.setup_cross_ruby(platforms:, ruby_versions: nil)`\n\nSet up cross-Ruby configurations for rake-compiler. Creates `rbconfig.rb` stubs in `~/.rake-compiler`.\n\n```ruby\nRake::Cross::Compiler.setup_cross_ruby(\n  platforms: %w[x86_64-linux-gnu arm64-darwin],\n  ruby_versions: %w[3.3.0 3.4.0]  # optional, auto-detected if nil\n)\n```\n\n### `Rake::Cross::Compiler.ruby_cc_version(*requirements, platforms: nil)`\n\nGet a RUBY_CC_VERSION string matching the given requirements.\n\n```ruby\nRake::Cross::Compiler.ruby_cc_version(\"\u003e= 3.1.0\")\n# =\u003e \"4.0.0:3.4.0:3.3.0:3.2.0:3.1.0\"\n\nspec = Gem::Specification.load(\"my.gemspec\")\nRake::Cross::Compiler.ruby_cc_version(spec.required_ruby_version, platforms: PLATFORMS)\n# =\u003e \"4.0.0:3.4.0:3.3.0:3.2.0:3.1.0\"\n```\n\n### `Rake::Cross::Compiler.set_ruby_cc_version(*requirements, platforms: nil)`\n\nSet the `RUBY_CC_VERSION` environment variable.\n\n```ruby\nRake::Cross::Compiler.set_ruby_cc_version(\"\u003e= 3.1.0\", platforms: PLATFORMS)\n```\n\n### `Rake::Cross::Compiler.available_ruby_versions(platforms: nil, common_only: false)`\n\nGet available Ruby versions from vendored headers.\n\n```ruby\nRake::Cross::Compiler.available_ruby_versions\n# =\u003e [\"3.0.0\", \"3.1.0\", \"3.2.0\", \"3.3.0\", \"3.4.0\", \"4.0.0\"]\n\n# Only versions available on ALL platforms\nRake::Cross::Compiler.available_ruby_versions(platforms: PLATFORMS, common_only: true)\n# =\u003e [\"3.1.0\", \"3.2.0\", \"3.3.0\", \"3.4.0\", \"4.0.0\"]\n```\n\n### `Rake::Cross::Compiler.supported_platforms`\n\nList all supported Ruby platforms.\n\n### `Rake::Cross::Compiler.zig_target_for(ruby_platform)`\n\nGet the Zig target triple for a Ruby platform name.\n\n### `Rake::Cross::Compiler.zig_available?`\n\nCheck if Zig is installed.\n\n### `Rake::Cross::Compiler.zig_version`\n\nGet the installed Zig version.\n\n## GitHub Actions\n\nExample workflow for building native gems:\n\n```yaml\nname: Build Gems\n\non:\n  release:\n    types: [published]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: ruby/setup-ruby@v1\n        with:\n          ruby-version: '3.4'\n          bundler-cache: true\n\n      - uses: mlugg/setup-zig@v1\n        with:\n          version: 0.13.0\n\n      - name: Setup Cross-Ruby Configs\n        run: bundle exec rake gem:prepare\n\n      - name: Build source gem\n        run: bundle exec rake build\n\n      - name: Build native gems\n        run: bundle exec rake gem:native\n\n      - uses: actions/upload-artifact@v4\n        with:\n          name: gems\n          path: pkg/*.gem\n```\n\n## Environment Variables\n\n- `ZIG` - Path to Zig executable (default: `zig`)\n- `RAKE_CROSS_COMPILER_PLATFORM` - Default target platform\n- `RUBY_CC_VERSION` - Ruby versions for cross-compilation (e.g., `3.3.0:3.4.0`)\n\n## Limitations\n\n1. **Platform-specific code** - Extensions with platform-specific assembly or intrinsics may need additional work.\n\n2. **Windows targets** - Windows cross-compilation is supported but less tested than Linux/macOS.\n\n## Development\n\n```bash\nbundle install\nbundle exec rake test\nbundle exec steep check\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/rake-cross-compiler.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## See Also\n\n- [Zig](https://ziglang.org/) - The compiler powering cross-compilation\n- [rake-compiler](https://github.com/rake-compiler/rake-compiler) - Build native extensions\n- [rake-compiler-dock](https://github.com/rake-compiler/rake-compiler-dock) - Docker-based cross-compilation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoroth%2Frake-cross-compiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcoroth%2Frake-cross-compiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcoroth%2Frake-cross-compiler/lists"}