class Gem::Ext::CargoBuilder - RDoc Documentation

# class Gem::Ext::CargoBuilder

This class is used by rubygems to build Rust extensions. It is a thin-wrapper over the ‘cargo rustc` command which takes care of building Rust code in a way that Ruby can use.

### Attributes

profile[RW]
runner[RW]
spec[RW]

### Public Class Methods

new(spec) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 9
    def initialize(spec)
      require_relative "../command"
      require_relative "cargo_builder/link_flag_converter"

      @spec = spec
      @runner = self.class.method(:run)
      @profile = :release
    end

### Public Instance Methods

build(_extension, dest_path, results, args = [], lib_dir = nil, cargo_dir = Dir.pwd) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 18
    def build(_extension, dest_path, results, args = [], lib_dir = nil, cargo_dir = Dir.pwd)
      require "fileutils"
      require "shellwords"

      build_crate(dest_path, results, args, cargo_dir)
      validate_cargo_build!(dest_path)
      rename_cdylib_for_ruby_compatibility(dest_path)
      finalize_directory(dest_path, lib_dir, cargo_dir)
      results
    end

build_crate(dest_path, results, args, cargo_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 29
    def build_crate(dest_path, results, args, cargo_dir)
      env = build_env
      cmd = cargo_command(cargo_dir, dest_path, args)
      runner.call cmd, results, "cargo", cargo_dir, env

      results
    end

build_env() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 37
    def build_env
      build_env = rb_config_env
      build_env["RUBY_STATIC"] = "true" if ruby_static? && ENV.key?("RUBY_STATIC")
      build_env["RUSTFLAGS"] = "#{ENV["RUSTFLAGS"]} --cfg=rb_sys_gem".strip
      build_env
    end

cargo_command(cargo_dir, dest_path, args = []) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 44
    def cargo_command(cargo_dir, dest_path, args = [])
      manifest = File.join(cargo_dir, "Cargo.toml")
      cargo = ENV.fetch("CARGO", "cargo")

      cmd = []
      cmd += [cargo, "rustc"]
      cmd += ["--target", ENV["CARGO_BUILD_TARGET"]] if ENV["CARGO_BUILD_TARGET"]
      cmd += ["--target-dir", dest_path]
      cmd += ["--manifest-path", manifest]
      cmd += ["--lib"]
      cmd += ["--profile", profile.to_s]
      cmd += ["--locked"] if profile == :release
      cmd += Gem::Command.build_args
      cmd += args
      cmd += ["--"]
      cmd += [*cargo_rustc_args(dest_path)]
      cmd
    end

### Private Instance Methods

cargo_crate_name() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 156
    def cargo_crate_name
      spec.metadata.fetch("cargo_crate_name", spec.name).tr("-", "_")
    end

cargo_dylib_path(dest_path) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 148
    def cargo_dylib_path(dest_path)
      prefix = so_ext == "dll" ? "" : "lib"
      path_parts = [dest_path]
      path_parts << ENV["CARGO_BUILD_TARGET"] if ENV["CARGO_BUILD_TARGET"]
      path_parts += [profile_target_directory, "#{prefix}#{cargo_crate_name}.#{so_ext}"]
      File.join(*path_parts)
    end

cargo_rustc_args(dest_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 71
    def cargo_rustc_args(dest_dir)
      [
        *linker_args,
        *mkmf_libpath,
        *rustc_dynamic_linker_flags(dest_dir),
        *rustc_lib_flags(dest_dir),
        *platform_specific_rustc_args(dest_dir),
        *debug_flags,
      ]
    end

darwin_target?() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 183
    def darwin_target?
      makefile_config("target_os").include?("darwin")
    end

debug_flags() click to toggle source

Good balance between binary size and debugability

    # File lib/rubygems/ext/cargo_builder.rb, line 258
    def debug_flags
      return [] if profile == :dev

      ["-C", "debuginfo=1"]
    end

final_extension_path(dest_path) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 142
    def final_extension_path(dest_path)
      dylib_path = cargo_dylib_path(dest_path)
      dlext_name = "#{spec.name}.#{makefile_config("DLEXT")}"
      dylib_path.gsub(File.basename(dylib_path), dlext_name)
    end

finalize_directory(dest_path, lib_dir, extension_dir) click to toggle source

Copied from ExtConfBuilder

    # File lib/rubygems/ext/cargo_builder.rb, line 265
    def finalize_directory(dest_path, lib_dir, extension_dir)
      require "fileutils"
      require "tempfile"

      ext_path = final_extension_path(dest_path)

      begin
        tmp_dest = Dir.mktmpdir(".gem.", extension_dir)

        # Some versions of `mktmpdir` return absolute paths, which will break make
        # if the paths contain spaces.
        #
        # As such, we convert to a relative path.
        tmp_dest_relative = get_relative_path(tmp_dest.clone, extension_dir)

        full_tmp_dest = File.join(extension_dir, tmp_dest_relative)

        # TODO: remove in RubyGems 4
        if Gem.install_extension_in_lib && lib_dir
          FileUtils.mkdir_p lib_dir
          FileUtils.cp_r ext_path, lib_dir, remove_destination: true
        end

        FileUtils::Entry_.new(full_tmp_dest).traverse do |ent|
          destent = ent.class.new(dest_path, ent.rel)
          destent.exist? || FileUtils.mv(ent.path, destent.path)
        end
      ensure
        FileUtils.rm_rf tmp_dest if tmp_dest
      end
    end

get_relative_path(path, base) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 297
    def get_relative_path(path, base)
      path[0..base.length - 1] = "." if path.start_with?(base)
      path
    end

ldflag_to_link_modifier(arg) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 175
    def ldflag_to_link_modifier(arg)
      LinkFlagConverter.convert(arg)
    end

libruby_args(dest_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 115
    def libruby_args(dest_dir)
      libs = makefile_config(ruby_static? ? "LIBRUBYARG_STATIC" : "LIBRUBYARG_SHARED")
      raw_libs = Shellwords.split(libs)
      raw_libs.flat_map {|l| ldflag_to_link_modifier(l) }
    end

linker_args() click to toggle source

We want to use the same linker that Ruby uses, so that the linker flags from mkmf work properly.

    # File lib/rubygems/ext/cargo_builder.rb, line 106
    def linker_args
      # Have to handle CC="cl /nologo" on mswin
      cc_flag = Shellwords.split(makefile_config("CC"))
      linker = cc_flag.shift
      link_args = cc_flag.flat_map {|a| ["-C", "link-arg=#{a}"] }

      ["-C", "linker=#{linker}", *link_args]
    end

makefile_config(var_name) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 249
    def makefile_config(var_name)
      val = RbConfig::MAKEFILE_CONFIG[var_name]

      return unless val

      RbConfig.expand(val.dup)
    end

maybe_resolve_ldflag_variable(input_arg, dest_dir) click to toggle source

Interpolate substition vars in the arg (i.e. $(DEFFILE))

    # File lib/rubygems/ext/cargo_builder.rb, line 197
    def maybe_resolve_ldflag_variable(input_arg, dest_dir)
      var_matches = input_arg.match(/\$\((\w+)\)/)

      return input_arg unless var_matches

      var_name = var_matches[1]

      return input_arg if var_name.nil? || var_name.chomp.empty?

      case var_name
      # On windows, it is assumed that mkmf has setup an exports file for the
      # extension, so we have to to create one ourselves.
      when "DEFFILE"
        write_deffile(dest_dir)
      else
        RbConfig::CONFIG[var_name]
      end
    end

mingw_target?() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 187
    def mingw_target?
      makefile_config("target_os").include?("mingw")
    end

mkmf_libpath() click to toggle source

Corresponds to $(LIBPATH) in mkmf

    # File lib/rubygems/ext/cargo_builder.rb, line 245
    def mkmf_libpath
      ["-L", "native=#{makefile_config("libdir")}"]
    end

msvc_target?() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 179
    def msvc_target?
      makefile_config("target_os").include?("msvc")
    end

platform_specific_rustc_args(dest_dir, flags = []) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 82
    def platform_specific_rustc_args(dest_dir, flags = [])
      if mingw_target?
        # On mingw platforms, mkmf adds libruby to the linker flags
        flags += libruby_args(dest_dir)

        # Make sure ALSR is used on mingw
        # see https://github.com/rust-lang/rust/pull/75406/files
        flags += ["-C", "link-arg=-Wl,--dynamicbase"]
        flags += ["-C", "link-arg=-Wl,--disable-auto-image-base"]

        # If the gem is installed on a host with build tools installed, but is
        # run on one that isn't the missing libraries will cause the extension
        # to fail on start.
        flags += ["-C", "link-arg=-static-libgcc"]
      elsif darwin_target?
        # Ventura does not always have this flag enabled
        flags += ["-C", "link-arg=-Wl,-undefined,dynamic_lookup"]
      end

      flags
    end

profile_target_directory() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 302
    def profile_target_directory
      case profile
      when :release then "release"
      when :dev     then "debug"
      else          raise "unknown target directory for profile: #{profile}"
      end
    end

rb_config_env() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 65
    def rb_config_env
      result = {}
      RbConfig::CONFIG.each {|k, v| result["RBCONFIG_#{k}"] = v }
      result
    end

rename_cdylib_for_ruby_compatibility(dest_path) click to toggle source

Ruby expects the dylib to follow a file name convention for loading

    # File lib/rubygems/ext/cargo_builder.rb, line 128
    def rename_cdylib_for_ruby_compatibility(dest_path)
      new_path = final_extension_path(dest_path)
      FileUtils.cp(cargo_dylib_path(dest_path), new_path)
      new_path
    end

ruby_static?() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 121
    def ruby_static?
      return true if %w[1 true].include?(ENV["RUBY_STATIC"])

      makefile_config("ENABLE_SHARED") == "no"
    end

rustc_dynamic_linker_flags(dest_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 160
    def rustc_dynamic_linker_flags(dest_dir)
      split_flags("DLDFLAGS")
        .map {|arg| maybe_resolve_ldflag_variable(arg, dest_dir) }
        .compact
        .flat_map {|arg| ldflag_to_link_modifier(arg) }
    end

rustc_lib_flags(dest_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 167
    def rustc_lib_flags(dest_dir)
      split_flags("LIBS").flat_map {|arg| ldflag_to_link_modifier(arg) }
    end

so_ext() click to toggle source

We have to basically reimplement RbConfig::CONFIG here to support Ruby < 2.5

@see github.com/ruby/ruby/blob/c87c027f18c005460746a74c07cd80ee355b16e4/configure.ac#L3185

    # File lib/rubygems/ext/cargo_builder.rb, line 232
    def so_ext
      return RbConfig::CONFIG["SOEXT"] if RbConfig::CONFIG.key?("SOEXT")

      if win_target?
        "dll"
      elsif darwin_target?
        "dylib"
      else
        "so"
      end
    end

split_flags(var) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 171
    def split_flags(var)
      Shellwords.split(RbConfig::CONFIG.fetch(var, ""))
    end

validate_cargo_build!(dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 134
    def validate_cargo_build!(dir)
      dylib_path = cargo_dylib_path(dir)

      raise DylibNotFoundError, dir unless File.exist?(dylib_path)

      dylib_path
    end

win_target?() click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 191
    def win_target?
      target_platform = RbConfig::CONFIG["target_os"]
      !!Gem::WIN_PATTERNS.find {|r| target_platform =~ r }
    end

write_deffile(dest_dir) click to toggle source

    # File lib/rubygems/ext/cargo_builder.rb, line 216
    def write_deffile(dest_dir)
      deffile_path = File.join(dest_dir, "#{spec.name}-#{RbConfig::CONFIG["arch"]}.def")
      export_prefix = makefile_config("EXPORT_PREFIX") || ""

      File.open(deffile_path, "w") do |f|
        f.puts "EXPORTS"
        f.puts "#{export_prefix.strip}Init_#{spec.name}"
      end

      deffile_path
    end