metacc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f277277e6c19c84a200cf69d21452da422980b3955c895bc148666b2e170d7c
+  data.tar.gz: e17a0627af2e670202be743c4e745a6aedaf10284ead45cd7c6740dd64dcf4b0
+SHA512:
+  metadata.gz: d889eff550e1f704c4e4264d750c1d03ddd7e040c1303eb6147501de5b0b2eec970c595cf183afe6fe7da91ee9465c0aa70f7596887018d3b9f4e979801e9f27
+  data.tar.gz: 9a0ae1d9c54d117d809dc236396ee0d4a69b321161a535287195474cdd6845a78dc0352bfe0b51f80487dbe25d9194a2afb98320ed2c90ff458f857d2be92f53

data/bin/metacc

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.join(__dir__, "..", "lib"))
+
+require "metacc/cli"
+
+MetaCC::CLI.new.run(ARGV)

data/lib/metacc/cli.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "driver"
+
+module MetaCC
+
+  # Command-line interface for the MetaCC Driver.
+  #
+  # Usage:
+  #   metacc <sources...> -o <output> [options]       – compile source file(s)
+  #
+  # General:
+  #   -Wall -Werror
+  #   --std=c11 --std=c17 --std=c23
+  #   --std=c++11 --std=c++14 --std=c++17 --std=c++20 --std=c++23 --std=c++26
+  #
+  # Linking:
+  #   --objects / -c     – compile only; don't link
+  #   -l, -L             - specify linker input
+  #   --shared           – produce a shared library
+  #   --static           – produce a static library
+  #   --lto              - enable link time optimization
+  #   --strip / -s       – strip unneeded symbols
+  #
+  # Code generation:
+  #   -O0, -O1, -O2, -O3                             - Set the optimization level
+  #   -msse4.2 -mavx -mavx2 -mavx512 --arch=native   - Compile for the given target
+  #   --no-rtti --no-exceptions
+  #   --pic
+  #
+  # Debugging:
+  #   --debug / -g
+  #   --asan --ubsan --msan
+  #
+  # Toolchain-specific flags (passed to Driver#compile via xflags:):
+  #   --xmsvc VALUE     – appended to xflags[MSVC]
+  #   --xgnu  VALUE     – appended to xflags[GNU]
+  #   --xclang VALUE    – appended to xflags[Clang]
+  #   --xclangcl VALUE  – appended to xflags[ClangCL]
+  class CLI
+
+    # Maps long-form CLI flag names to Driver::RECOGNIZED_FLAGS symbols.
+    # Optimization-level flags are handled separately via -O LEVEL.
+    LONG_FLAGS = {
+      "lto" =>                       :lto,
+      "asan" =>                      :asan,
+      "ubsan" =>                     :ubsan,
+      "msan" =>                      :msan,
+      "no-rtti" =>                   :no_rtti,
+      "no-exceptions" =>             :no_exceptions,
+      "pic" =>                       :pic,
+      "no-semantic-interposition" => :no_semantic_interposition,
+      "no-omit-frame-pointer" =>     :no_omit_frame_pointer,
+      "no-strict-aliasing" =>        :no_strict_aliasing
+    }.freeze
+
+    WARNING_CONFIGS = {
+      "all" =>   :warn_all,
+      "error" => :warn_error
+    }
+
+    TARGETS = {
+      "sse4.2" => :sse4_2,
+      "avx" =>    :avx,
+      "avx2" =>   :avx2,
+      "avx512" => :avx512,
+      "native" => :native
+    }.freeze
+
+    STANDARDS = {
+      "c11"   => :c11,
+      "c17"   => :c17,
+      "c23"   => :c23,
+      "c++11" => :cxx11,
+      "c++14" => :cxx14,
+      "c++17" => :cxx17,
+      "c++20" => :cxx20,
+      "c++23" => :cxx23,
+      "c++26" => :cxx26
+    }.freeze
+
+    # Maps --x<name> CLI option names to xflags toolchain-class keys.
+    XFLAGS = {
+      "xmsvc" =>    MSVC,
+      "xgnu" =>     GNU,
+      "xclang" =>   Clang,
+      "xclangcl" => ClangCL
+    }.freeze
+
+    def run(argv, driver: Driver.new)
+      options, input_paths = parse_compile_args(argv, driver:)
+      output_path = options.delete(:output_path)
+      run_flag = options.delete(:run)
+      validate_options!(options[:flags], output_path, run_flag)
+      invoke(driver, input_paths, output_path, options, run: run_flag)
+    end
+
+    # Parses compile arguments.
+    # Returns [options_hash, remaining_positional_args].
+    def parse_compile_args(argv, driver: nil)
+      options = {
+        include_paths: [],
+        defs: [],
+        linker_paths: [],
+        libs: [],
+        output_path: nil,
+        run: false,
+        flags: [],
+        xflags: {},
+      }
+      parser = OptionParser.new
+      setup_compile_options(parser, options, driver:)
+      sources = parser.permute(argv)
+      [options, sources]
+    end
+
+    private
+
+    def setup_compile_options(parser, options, driver: nil)
+      parser.on("-o FILEPATH", "Output file path") do |value|
+        options[:output_path] = value
+      end
+      parser.on("-I DIRPATH", "Add an include search directory") do |value|
+        options[:include_paths] << value
+      end
+      parser.on("-D DEF", "Add a preprocessor definition") do |value|
+        options[:defs] << value
+      end
+      parser.on("-O LEVEL", /\A[0-3]\z/, "Optimization level (0–3)") do |level|
+        options[:flags] << :"o#{l}"
+      end
+      parser.on("-Os", "Optimize for size") do
+        options[:flags] << :os
+      end
+      parser.on("-m", "--arch ARCH", "Target architecture") do |value|
+        options[:flags] << TARGETS[v]
+      end
+      parser.on("-g", "--debug", "Emit debugging symbols") do
+        options[:flags] << :debug
+      end
+      parser.on("--std STANDARD", "Specify the language standard") do |value|
+        options[:flags] << STANDARDS[v]
+      end
+      parser.on("-W OPTION", "Configure warnings") do |value|
+        options[:flags] << WARNING_CONFIGS[v]
+      end
+      parser.on("-c", "--objects", "Produce object files") do
+        options[:flags] << :objects
+      end
+      parser.on("-r", "--run", "Run the compiled executable after a successful build") do
+        options[:run] = true
+      end
+      parser.on("-l LIB", "Link against library LIB") do |value|
+        options[:libs] << value
+      end
+      parser.on("-L DIR", "Add linker library search path") do |value|
+        options[:linker_paths] << value
+      end
+      parser.on("--shared", "Produce a shared library") do
+        options[:flags] << :shared
+      end
+      parser.on("--static", "Produce a static library") do
+        options[:flags] << :static
+      end
+      parser.on("-s", "--strip", "Strip unneeded symbols") do
+        options[:flags] << :strip
+      end
+      LONG_FLAGS.each do |name, sym|
+        parser.on("--#{name}") do
+          options[:flags] << sym
+        end
+      end
+      XFLAGS.each do |name, tc_class|
+        parser.on("--#{name} VALUE", "Pass VALUE to the #{tc_class} toolchain") do |value|
+          options[:xflags][tc_class] ||= []
+          options[:xflags][tc_class] << value
+        end
+      end
+      parser.on_tail("--version", "Print the toolchain version and exit") do
+        puts driver&.toolchain&.version_banner
+        exit
+      end
+    end
+
+    def validate_options!(flags, output_path, run_flag)
+      objects = flags.include?(:objects)
+
+      if objects && output_path
+        warn "error: -o cannot be used with --objects"
+        exit 1
+      end
+
+      unless objects || output_path
+        warn "error: -o is required"
+        exit 1
+      end
+
+      if run_flag && (objects || flags.include?(:shared) || flags.include?(:static))
+        warn "error: --run cannot be used with --objects, --shared, or --static"
+        exit 1
+      end
+    end
+
+    def run_executable(path)
+      system(path)
+    end
+
+    def invoke(driver, input_paths, output_path, options, run: false)
+      result = driver.invoke(input_paths, output_path, **options)
+      exit 1 unless result
+      run_executable(result) if run
+    end
+
+  end
+
+end

data/lib/metacc/driver.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "toolchain"
+
+module MetaCC
+
+  # Raised when no supported C/C++ compiler can be found on the system.
+  class CompilerNotFoundError < StandardError; end
+
+  # Driver wraps C and C++ compile and link operations using the first
+  # available compiler found on the system (Clang, GCC, or MSVC).
+  class Driver
+
+    RECOGNIZED_FLAGS = Set.new(
+      %i[
+        o0 o1 o2 o3 os
+        sse4_2 avx avx2 avx512 native
+        debug lto
+        warn_all warn_error
+        c11 c17 c23
+        cxx11 cxx14 cxx17 cxx20 cxx23 cxx26
+        asan ubsan msan
+        no_rtti no_exceptions pic
+        no_semantic_interposition no_omit_frame_pointer no_strict_aliasing
+        objects shared static strip
+      ]
+    ).freeze
+
+    # The detected toolchain (a Toolchain subclass instance).
+    attr_reader :toolchain
+
+    # Detects the first available C/C++ compiler toolchain.
+    #
+    # @param prefer       [Array<Class>] toolchain classes to probe, in priority order.
+    #                                   Each element must be a Class derived from Toolchain.
+    #                                   Defaults to [Clang, GNU, MSVC].
+    # @param search_paths [Array<String>] directories to search for toolchain executables
+    #                                    before falling back to PATH. Defaults to [].
+    # @raise [CompilerNotFoundError] if no supported compiler is found.
+    def initialize(prefer: [Clang, GNU, MSVC],
+                   search_paths: [])
+      @toolchain = select_toolchain!(prefer, search_paths)
+    end
+
+    # Invokes the compiler driver for the given input files and output path.
+    # The kind of output (object files, executable, shared library, or static
+    # library) is determined by the flags: +:objects+, +:shared+, or +:static+.
+    # When none of these mode flags is present, an executable is produced.
+    #
+    # @param input_files    [String, Array<String>] paths to the input files
+    # @param output_path    [String] path for the resulting output file
+    # @param flags          [Array<Symbol>] compiler/linker flags
+    # @param xflags         [Hash{Class => String}] extra (native) compiler flags keyed by toolchain Class
+    # @param include_paths  [Array<String>] directories to add with -I
+    # @param defs           [Array<String>] preprocessor macros (e.g. "FOO" or "FOO=1")
+    # @param libs           [Array<String>] library names to link (e.g. "m", "pthread")
+    # @param linker_paths   [Array<String>] linker library search paths (-L / /LIBPATH:)
+    # @param env            [Hash] environment variables to set for the subprocess
+    # @param working_dir    [String] working directory for the subprocess (default: ".")
+    # @return [String, true, nil] the (possibly extension-augmented) output path on success,
+    #   true if output_path was nil and the command succeeded,
+    #   nil if the underlying toolchain executable returned a non-zero exit status
+    # @raise [ArgumentError] if output_path is nil and the :objects flag is not present
+    def invoke(
+      input_files,
+      output_path,
+      flags: [],
+      xflags: {},
+      include_paths: [],
+      defs: [],
+      libs: [],
+      linker_paths: [],
+      env: {},
+      working_dir: "."
+    )
+      output_type = output_type_from_flags(flags)
+      raise ArgumentError, "output_path must not be nil" if output_path.nil? && output_type != :objects
+
+      output_path = apply_default_extension(output_path, output_type) unless output_path.nil?
+
+      input_files = Array(input_files)
+      flags = translate_flags(flags)
+      flags.concat(xflags[@toolchain.class] || [])
+
+      cmd = @toolchain.command(input_files, output_path, flags, include_paths, defs, libs, linker_paths)
+      run_command(cmd, env:, working_dir:) ? (output_path || true) : nil
+    end
+
+    private
+
+    def select_toolchain!(candidates, search_paths)
+      candidates.each do |toolchain_class|
+        toolchain = toolchain_class.new(search_paths:)
+        return toolchain if toolchain.available?
+      end
+      raise CompilerNotFoundError, "No supported C/C++ compiler found (tried clang, gcc, cl)"
+    end
+
+    def output_type_from_flags(flags)
+      if flags.include?(:objects)    then :objects
+      elsif flags.include?(:shared)  then :shared
+      elsif flags.include?(:static)  then :static
+      else :executable
+      end
+    end
+
+    def apply_default_extension(path, output_type)
+      return path unless File.extname(path).empty?
+
+      ext = @toolchain.default_extension(output_type)
+      ext.empty? ? path : "#{path}#{ext}"
+    end
+
+    def translate_flags(flags)
+      unrecognized_flag = flags.find { |flag| !RECOGNIZED_FLAGS.include?(flag) }
+      if unrecognized_flag
+        raise "#{unrecognized_flag.inspect} is not a known flag"
+      end
+
+      flags.flat_map { |flag| @toolchain.flags[flag] }
+    end
+
+    def run_command(cmd, env: {}, working_dir: ".")
+      !!system(env, *cmd, chdir: working_dir, out: File::NULL, err: File::NULL)
+    end
+
+  end
+
+end

data/lib/metacc/toolchain.rb

@@ -0,0 +1,446 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module MetaCC
+
+  # Base class for compiler toolchains.
+  # Subclasses set their own command attributes in +initialize+ by calling
+  # +command_available?+ to probe the system, then implement the
+  # toolchain-specific flag and command building methods.
+  #   c    – command used to compile source files
+  class Toolchain
+
+    attr_reader :c
+
+    def initialize(search_paths: [])
+      @search_paths = search_paths
+    end
+
+    # Returns true if this toolchain's primary compiler is present in PATH.
+    def available?
+      command_available?(c)
+    end
+
+    # Returns the languages supported by this toolchain as an array of symbols.
+    # The default implementation returns [:c, :cxx].  Subclasses that only
+    # support a subset of languages should override this method.
+    def languages
+      [:c, :cxx]
+    end
+
+    # Returns true if +command+ is present in PATH, false otherwise.
+    # Intentionally ignores the exit status – only ENOENT (not found) matters.
+    def command_available?(command)
+      return false if command.nil?
+
+      !system(command, "--version", out: File::NULL, err: File::NULL).nil?
+    end
+
+    # Returns the output of running the compiler with --version.
+    def version_banner
+      IO.popen([c, "--version", { err: :out }], &:read)
+    end
+
+    # Returns a Hash mapping universal flags to native flags for this toolchain.
+    def flags
+      raise RuntimeError, "#{self.class}#flags not implemented"
+    end
+
+    # Returns the full command array for the given inputs, output, and flags.
+    # The output mode (object files, shared library, static library, or
+    # executable) is determined by the translated flags.
+    def command(input_files, output, flags, include_paths, definitions, libs, linker_include_dirs)
+      raise RuntimeError, "#{self.class}#command not implemented"
+    end
+
+    # Returns the default file extension (with leading dot, e.g. ".o") for the
+    # given output type on this toolchain/OS combination.  Returns an empty
+    # string when no extension is conventional (e.g. executables on Unix).
+    #
+    # @param output_type [:objects, :shared, :static, :executable]
+    # @return [String]
+    def default_extension(output_type)
+      host_os = RbConfig::CONFIG["host_os"]
+      case output_type
+      when :objects    then ".o"
+      when :static     then ".a"
+      when :shared
+        if host_os.match?(/mswin|mingw|cygwin/)
+          ".dll"
+        elsif host_os.match?(/darwin/)
+          ".dylib"
+        else
+          ".so"
+        end
+      when :executable
+        host_os.match?(/mswin|mingw|cygwin/) ? ".exe" : ""
+      else
+        raise ArgumentError, "unknown output_type: #{output_type.inspect}"
+      end
+    end
+
+    private
+
+    def c_file?(path)
+      File.extname(path).downcase == ".c"
+    end
+
+    # Returns the full path to +name+ if it is found (and executable) in one of
+    # the configured search paths, otherwise returns +name+ unchanged so that
+    # the shell's PATH is used at execution time.
+    def resolve_command(name)
+      @search_paths.each do |dir|
+        full_path = File.join(dir, name)
+        return full_path if File.executable?(full_path)
+      end
+      name
+    end
+
+  end
+
+  # GNU-compatible toolchain (gcc).
+  class GNU < Toolchain
+
+    def initialize(search_paths: [])
+      super
+      @c    = resolve_command("gcc")
+    end
+
+    def command(input_files, output, flags, include_paths, definitions, libs, linker_include_dirs)
+      inc_flags = include_paths.map { |p| "-I#{p}" }
+      def_flags = definitions.map { |d| "-D#{d}" }
+      link_mode = !flags.include?("-c")
+      lib_path_flags = link_mode ? linker_include_dirs.map { |p| "-L#{p}" } : []
+      lib_flags      = link_mode ? libs.map { |l| "-l#{l}" } : []
+      cmd = [c, *flags, *inc_flags, *def_flags, *input_files, *lib_path_flags, *lib_flags]
+      output.nil? ? cmd : [*cmd, "-o", output]
+    end
+
+    GNU_FLAGS = {
+      o0:            ["-O0"],
+      o1:            ["-O1"],
+      o2:            ["-O2"],
+      o3:            ["-O3"],
+      os:            ["-Os"],
+      sse4_2:        ["-march=x86-64-v2"], # This is a better match for /arch:SSE4.2 than -msse4_2 is
+      avx:           ["-march=x86-64-v2", "-mavx"],
+      avx2:          ["-march=x86-64-v3"], # This is a better match for /arch:AVX2 than -mavx2 is
+      avx512:        ["-march=x86-64-v4"],
+      native:        ["-march=native", "-mtune=native"],
+      debug:         ["-g3"],
+      lto:           ["-flto"],
+      warn_all:      ["-Wall", "-Wextra", "-pedantic"],
+      warn_error:    ["-Werror"],
+      c11:           ["-std=c11"],
+      c17:           ["-std=c17"],
+      c23:           ["-std=c23"],
+      cxx11:         ["-std=c++11"],
+      cxx14:         ["-std=c++14"],
+      cxx17:         ["-std=c++17"],
+      cxx20:         ["-std=c++20"],
+      cxx23:         ["-std=c++23"],
+      cxx26:         ["-std=c++2c"],
+      asan:          ["-fsanitize=address"],
+      ubsan:         ["-fsanitize=undefined"],
+      msan:          ["-fsanitize=memory"],
+      no_rtti:                   ["-fno-rtti"],
+      no_exceptions:             ["-fno-exceptions", "-fno-unwind-tables"],
+      pic:                       ["-fPIC"],
+      no_semantic_interposition: ["-fno-semantic-interposition"],
+      no_omit_frame_pointer:     ["-fno-omit-frame-pointer"],
+      no_strict_aliasing:        ["-fno-strict-aliasing"],
+      objects:                   ["-c"],
+      shared:                    ["-shared"],
+      static:                    ["-r", "-nostdlib"],
+      strip:                     ["-Wl,--strip-unneeded"]
+    }.freeze
+
+    def flags
+      GNU_FLAGS
+    end
+
+  end
+
+  # Clang toolchain – identical command structure to GNU.
+  class Clang < GNU
+
+    def initialize(search_paths: [])
+      super
+      @c    = resolve_command("clang")
+    end
+
+    CLANG_FLAGS = GNU_FLAGS.merge(lto: ["-flto=thin"]).freeze
+
+    def flags
+      CLANG_FLAGS
+    end
+
+  end
+
+  # Microsoft Visual C++ toolchain.
+  class MSVC < Toolchain
+
+    # Default location of the Visual Studio Installer's vswhere utility.
+    VSWHERE_PATH = File.join(
+      ENV.fetch("ProgramFiles(x86)", "C:\\Program Files (x86)"),
+      "Microsoft Visual Studio", "Installer", "vswhere.exe"
+    ).freeze
+
+    def initialize(cl_command = "cl", search_paths: [])
+      super(search_paths:)
+      resolved_cmd = resolve_command(cl_command)
+      @c    = resolved_cmd
+      setup_msvc_environment(resolved_cmd)
+    end
+
+    def command(input_files, output, flags, include_paths, definitions, libs, linker_include_dirs)
+      inc_flags = include_paths.map { |p| "/I#{p}" }
+      def_flags = definitions.map { |d| "/D#{d}" }
+
+      if flags.include?("/c")
+        cmd = [c, *flags, *inc_flags, *def_flags, *input_files]
+        output.nil? ? cmd : [*cmd, "/Fo#{output}"]
+      else
+        lib_flags      = libs.map { |l| "#{l}.lib" }
+        lib_path_flags = linker_include_dirs.map { |p| "/LIBPATH:#{p}" }
+        cmd = [c, *flags, *inc_flags, *def_flags, *input_files, *lib_flags, "/Fe#{output}"]
+        cmd += ["/link", *lib_path_flags] unless lib_path_flags.empty?
+        cmd
+      end
+    end
+
+    MSVC_FLAGS = {
+      o0:                        ["/Od"],
+      o1:                        ["/O1"],
+      o2:                        ["/O2"],
+      o3:                        ["/O2", "/Ob3"],
+      os:                        ["/O1"],
+      sse4_2:                    ["/arch:SSE4.2"],
+      avx:                       ["/arch:AVX"],
+      avx2:                      ["/arch:AVX2"],
+      avx512:                    ["/arch:AVX512"],
+      native:                    [],
+      debug:                     ["/Zi"],
+      lto:                       ["/GL"],
+      warn_all:                  ["/W4"],
+      warn_error:                ["/WX"],
+      c11:                       ["/std:c11"],
+      c17:                       ["/std:c17"],
+      c23:                       ["/std:clatest"],
+      cxx11:                     [],
+      cxx14:                     ["/std:c++14"],
+      cxx17:                     ["/std:c++17"],
+      cxx20:                     ["/std:c++20"],
+      cxx23:                     ["/std:c++23preview"],
+      cxx26:                     ["/std:c++latest"],
+      asan:                      ["/fsanitize=address"],
+      ubsan:                     [],
+      msan:                      [],
+      no_rtti:                   ["/GR-"],
+      no_exceptions:             ["/EHs-", "/EHc-"],
+      pic:                       [],
+      no_semantic_interposition: [],
+      no_omit_frame_pointer:     ["/Oy-"],
+      no_strict_aliasing:        [],
+      objects:                   ["/c"],
+      shared:                    ["/LD"],
+      static:                    ["/c"],
+      strip:                     []
+    }.freeze
+
+    def flags
+      MSVC_FLAGS
+    end
+
+    # MSVC and clang-cl always target Windows, so extensions are Windows-specific
+    # regardless of the host OS.
+    def default_extension(output_type)
+      case output_type
+      when :objects    then ".obj"
+      when :static     then ".lib"
+      when :shared     then ".dll"
+      when :executable then ".exe"
+      else
+        raise ArgumentError, "unknown output_type: #{output_type.inspect}"
+      end
+    end
+
+    # MSVC prints its version banner to stderr when invoked with no arguments.
+    def show_version
+      IO.popen([c, { err: :out }], &:read)
+    end
+
+    private
+
+    # Attempts to configure the MSVC environment using vswhere.exe when cl.exe
+    # is not already available on PATH.  Tries two vswhere strategies in order:
+    #
+    # 1. Query vswhere for VS instances whose tools are already on PATH (-path).
+    # 2. Query vswhere for the latest VS instance, including prereleases.
+    #
+    # When a VS instance is found, locates vcvarsall.bat relative to the
+    # returned devenv.exe path and runs it so that cl.exe and related tools
+    # become available on PATH.
+    def setup_msvc_environment(cl_command)
+      return if command_available?(cl_command)
+
+      devenv_path = run_vswhere("-path", "-property", "productPath") ||
+                    run_vswhere("-latest", "-prerelease", "-property", "productPath")
+      return unless devenv_path
+
+      vcvarsall = find_vcvarsall(devenv_path)
+      return unless vcvarsall
+
+      run_vcvarsall(vcvarsall)
+    end
+
+    # Runs vswhere.exe with the given arguments and returns the trimmed stdout,
+    # or nil if vswhere.exe is absent, the command fails, or produces no output.
+    def run_vswhere(*args)
+      return nil unless File.exist?(VSWHERE_PATH)
+
+      stdout = IO.popen([VSWHERE_PATH, *args], &:read)
+      status = $?
+      return nil unless status.success?
+
+      path = stdout.strip
+      path.empty? ? nil : path
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Returns the path to vcvarsall.bat for the given devenv.exe path, or nil
+    # if it cannot be located.  devenv.exe lives at:
+    #   <root>\Common7\IDE\devenv.exe
+    # vcvarsall.bat lives at:
+    #   <root>\VC\Auxiliary\Build\vcvarsall.bat
+    def find_vcvarsall(devenv_path)
+      install_root = File.expand_path("../../..", devenv_path)
+      vcvarsall = File.join(install_root, "VC", "Auxiliary", "Build", "vcvarsall.bat")
+      File.exist?(vcvarsall) ? vcvarsall : nil
+    end
+
+    # Runs vcvarsall.bat for the x64 architecture and merges the resulting
+    # environment variables into the current process's ENV so that cl.exe
+    # and related tools become available on PATH.
+    def run_vcvarsall(vcvarsall)
+      stdout = IO.popen(["cmd.exe", "/c", vcvarsall_command(vcvarsall)], &:read)
+      status = $?
+      return unless status.success?
+
+      load_vcvarsall(stdout)
+    end
+
+    # Builds the cmd.exe command string for calling vcvarsall.bat and capturing
+    # the resulting environment variables.  The path is double-quoted to handle
+    # spaces; any embedded double quotes are escaped by doubling them, which is
+    # the cmd.exe convention inside a double-quoted string.  Shellwords is not
+    # used here because it produces POSIX sh escaping, which is incompatible
+    # with cmd.exe syntax.
+    def vcvarsall_command(vcvarsall)
+      quoted = '"' + vcvarsall.gsub('"', '""') + '"'
+      "#{quoted} x64 && set"
+    end
+
+    # Parses the output of `vcvarsall.bat … && set` and merges the resulting
+    # environment variables into the current process's ENV.
+    def load_vcvarsall(output)
+      output.each_line do |line|
+        key, sep, value = line.chomp.partition("=")
+        next if sep.empty?
+
+        ENV[key] = value
+      end
+    end
+
+  end
+
+  # clang-cl toolchain – uses clang-cl compiler with MSVC-compatible flags and
+  # environment setup.
+  class ClangCL < MSVC
+
+    def initialize(search_paths: [])
+      super("clang-cl", search_paths:)
+    end
+
+    CLANG_CL_FLAGS = MSVC_FLAGS.merge(
+      o3:  ["/Ot"],       # Clang-CL treats /Ot as -O3
+      lto: ["-flto=thin"]
+    ).freeze
+
+    def flags
+      CLANG_CL_FLAGS
+    end
+
+  end
+
+  # TinyCC toolchain (tcc).  TinyCC only supports C, not C++.
+  class TinyCC < Toolchain
+
+    def initialize(search_paths: [])
+      super
+      @c   = resolve_command("tcc")
+    end
+
+    # TinyCC does not support C++.
+    def languages
+      [:c]
+    end
+
+    def command(input_files, output, flags, include_paths, definitions, libs, linker_include_dirs)
+      inc_flags = include_paths.map { |p| "-I#{p}" }
+      def_flags = definitions.map { |d| "-D#{d}" }
+      link_mode = !flags.include?("-c")
+      lib_path_flags = link_mode ? linker_include_dirs.map { |p| "-L#{p}" } : []
+      lib_flags      = link_mode ? libs.map { |l| "-l#{l}" } : []
+      cmd = [c, *flags, *inc_flags, *def_flags, *input_files, *lib_path_flags, *lib_flags]
+      output.nil? ? cmd : [*cmd, "-o", output]
+    end
+
+    TINYCC_FLAGS = {
+      o0:                        [],
+      o1:                        ["-O1"],
+      o2:                        ["-O2"],
+      o3:                        ["-O2"],
+      os:                        [],
+      sse4_2:                    [],
+      avx:                       [],
+      avx2:                      [],
+      avx512:                    [],
+      native:                    [],
+      debug:                     ["-g"],
+      lto:                       [],
+      warn_all:                  ["-Wall"],
+      warn_error:                ["-Werror"],
+      c11:                       [],
+      c17:                       [],
+      c23:                       [],
+      cxx11:                     [],
+      cxx14:                     [],
+      cxx17:                     [],
+      cxx20:                     [],
+      cxx23:                     [],
+      cxx26:                     [],
+      asan:                      [],
+      ubsan:                     [],
+      msan:                      [],
+      no_rtti:                   [],
+      no_exceptions:             [],
+      pic:                       [],
+      no_semantic_interposition: [],
+      no_omit_frame_pointer:     [],
+      no_strict_aliasing:        [],
+      objects:                   ["-c"],
+      shared:                    ["-shared"],
+      static:                    ["-c"],
+      strip:                     []
+    }.freeze
+
+    def flags
+      TINYCC_FLAGS
+    end
+
+  end
+
+end

data/lib/metacc.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "metacc/driver"
+
+module MetaCC
+
+  VERSION = "0.1.0"
+
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: metacc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Praneeth Sadda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  metacc provides a small set of classes for invoking C/C++ build tools, abstracting
+  away differences between compilers.
+email: psadda@gmail.com
+executables:
+- metacc
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/metacc
+- lib/metacc.rb
+- lib/metacc/cli.rb
+- lib/metacc/driver.rb
+- lib/metacc/toolchain.rb
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: A small Ruby scripting system for building C and C++ applications
+test_files: []