Source gem support

Author: cretz

.github/workflows/build-gems.yml

@@ -7,7 +7,7 @@ on:
       - "releases/*"
 
 jobs:
-  build-gems:
+  build-platform-gems:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -31,23 +31,49 @@ jobs:
           working-directory: ./temporalio
           cache-version: v1-${{ matrix.rubyPlatform }}
 
-      - name: Cross compile gems
+      - name: Cross compile gem
         uses: oxidize-rb/actions/cross-gem@v1
         id: cross-gem
         with:
           platform: ${{ matrix.rubyPlatform }}
           ruby-versions: "3.1,3.2,3.3"
           working-directory: ./temporalio
 
-      - name: Upload gems
+      - name: Upload gem
         uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.rubyPlatform }}-gem
           path: ${{ steps.cross-gem.outputs.gem-path }}
 
+  build-source-gem:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Ruby and Rust
+        uses: oxidize-rb/actions/setup-ruby-and-rust@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          cargo-cache: true
+          cache-version: v1-source
+
+      - name: Build
+        working-directory: ./temporalio
+        run: bundle exec rake build
+
+      - name: Upload gem
+        uses: actions/upload-artifact@v4
+        with:
+          name: source-gem
+          path: temporalio/pkg/*.gem
+
   smoke-test-gems:
     needs:
-      - build-gems
+      - build-platform-gems
     strategy:
       fail-fast: false
       matrix:

README.md

@@ -54,6 +54,7 @@ Notably missing from this SDK:
   - [Platform Support](#platform-support)
 - [Development](#development)
   - [Build](#build)
+    - [Build Platform-specific Gem](#build-platform-specific-gem)
   - [Testing](#testing)
   - [Code Formatting and Type Checking](#code-formatting-and-type-checking)
   - [Proto Generation](#proto-generation)
@@ -76,12 +77,14 @@ Or via `gem install` like:
 gem install temporalio
 ```
 
+**NOTE**: Only macOS ARM/x64 and Linux ARM/x64 are supported, and the platform-specific gem chosen is based on when the
+gem/bundle install is performed. A source gem is published but cannot be used directly and will fail to build if tried.
+MinGW-based Windows and Linux MUSL do not have gems. See the [Platform Support](#platform-support) section for more
+information.
+
 **NOTE**: Due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and `async` gem) are only
 supported on Ruby versions 3.3 and newer.
 
-**NOTE**: MinGW-based Windows, Linux MUSL, and pure source based gems are not currently published. See the
-[Platform Support](#platform-support) section for more information.
-
 ### Implementing an Activity
 
 Implementing workflows is not yet supported in the Ruby SDK, but implementing activities is.
@@ -465,9 +468,9 @@ This means Linux and macOS for ARM and x64 have published gems. Currently, a gem
 Due to [an issue](https://github.com/temporalio/sdk-ruby/issues/172) with Windows and multi-threaded Rust, MinGW-based
 Windows (i.e. `x64-mingw-ucrt`) is not supported. But WSL is supported using the normal Linux gem.
 
-At this time a pure source gem is not published, which means that when trying to install the gem on an unsupported
-platform, you may get an error that it is not available. Building from source requires many files across submodules and
-requires Rust to be installed. See the [Build](#build) section for how to build a gem from the repository.
+At this time a pure source gem is published for documentation reasons, but it cannot be built and will fail if tried.
+Building from source requires many files across submodules and requires Rust to be installed. See the [Build](#build)
+section for how to build a the repository.
 
 The SDK works on Ruby 3.1+, but due to [an issue](https://github.com/temporalio/sdk-ruby/issues/162), fibers (and
 `async` gem) are only supported on Ruby versions 3.3 and newer.
@@ -491,13 +494,32 @@ To build shared library for development use:
 
     bundle exec rake compile
 
-Note, this is not `compile:dev` because debug-mode in Rust has
+**NOTE**: This will make the current directory usable for the current Ruby version by putting the shared library
+`lib/temporalio/internal/bridge/temporalio_bridge.<ext>` in the proper place. But this development shared library may
+not work for other Ruby versions or other OS/arch combinations. For that, see "Build Platform-specific Gem" below.
+
+**NOTE**: This is not `compile:dev` because debug-mode in Rust has
 [an issue](https://github.com/rust-lang/rust/issues/34283) that causes runtime stack size problems.
 
-To lint, build, and test release:
+To lint, build, and test:
 
     bundle exec rake
 
+#### Build Platform-specific Gem
+
+The standard `bundle exec rake build` will produce a gem in the `pkg` directory, but that gem will not be usable because
+the shared library is not present (neither the Rust code nor the compiled form). To create a platform-specific gem that
+can be used, `rb-sys-dock` must be run. See the
+[Cross-Compilation documentation](https://oxidize-rb.github.io/rb-sys/tutorial/publishing/cross-compilation.html) in the
+`rb-sys` repository. For example, running:
+
+    bundle exec rb-sys-dock --platform x86_64-linux --ruby-versions 3.2,3.3 --build
+
+Will create a `pkg/temporalio-<version>-x86_64-linux.gem` file that can be used in x64 Linux environments on both Ruby
+3.2 and Ruby 3.3 because it contains the shared libraries. For this specific example, the shared libraries are inside
+the gem at `lib/temporalio/internal/bridge/3.2/temporalio_bridge.<ext>` and
+`lib/temporalio/internal/bridge/3.3/temporalio_bridge.<ext>`.
+
 ### Testing
 
 This project uses `minitest`. To test:

temporalio/Rakefile

@@ -10,8 +10,12 @@ task build: :compile
 
 GEMSPEC = Gem::Specification.load('temporalio.gemspec')
 
-RbSys::ExtensionTask.new('temporalio_bridge', GEMSPEC) do |ext|
-  ext.lib_dir = 'lib/temporalio/internal/bridge'
+begin
+  RbSys::ExtensionTask.new('temporalio_bridge', GEMSPEC) do |ext|
+    ext.lib_dir = 'lib/temporalio/internal/bridge'
+  end
+rescue RbSys::CargoMetadataError
+  raise 'Source gem cannot be installed directly, must be a supported platform'
 end
 
 require 'rake/testtask'

temporalio/temporalio.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/temporalio/sdk-ruby'
 
-  spec.files = Dir['lib/**/*.rb', 'LICENSE', 'README.md', 'Cargo.*', 'temporalio.gemspec']
+  spec.files = Dir['lib/**/*.rb', 'LICENSE', 'README.md', 'Cargo.*', 'temporalio.gemspec', 'Gemfile', 'Rakefile']
 
   spec.bindir = 'exe'
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }