ruby-yasm 0.2.1 → 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a2caa603f754d40e6ba2d6f10ff5e4e63829a28ee3e89a5c0eb76aee4e9b38c
+  data.tar.gz: df4c5fab51e3a804d7b4f16f515f05eef1e2295742a7e1f36743fddfe4b857e6
+SHA512:
+  metadata.gz: 79baa6465f54ff67bb4697aff6338d6566a1b59611b58af8e69f90f680819828747a2657699d579f1a8c50b1e67cdb00179e9872159b78fa59b7a2fd75ca7d38
+  data.tar.gz: 7df6abee2fe8b61463e2dff4c361c72c2566996658f99830e0bd2699e9229cec6dcf1556e109cddae3eb72dbbb175c2c1cb96bef0fa4f757b3847639ba5167b7

data/.github/workflows/ruby.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.6
+          - 2.7
+          - 3.0
+          - jruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install yasm
+        run: |
+          sudo apt update -y && \
+          sudo apt install -y --no-install-recommends --no-install-suggests yasm
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -1,6 +1,8 @@
-doc
-pkg
-.yardoc
+/Gemfile.lock
+/coverage
+/doc
+/pkg
+/.yardoc
 .DS_Store
 *.log
 *.swp

data/ChangeLog.md

@@ -1,6 +1,12 @@
+### 0.3.0 / 2022-01-07
+
+* Replace rprogram with [command_mapper].
+* Added {YASM::Command}.
+* Deprecated {YASM::Program} in favor of {YASM::Command}.
+
 ### 0.2.1 / 2012-05-27
 
-* {YASM::Task#target!} now raises an `ArgumentError` when given an unknown
+* `YASM::Task#target!` now raises an `ArgumentError` when given an unknown
   target.
 * Replaced ore-tasks with
   [rubygems-tasks](https://github.com/postmodern/rubygems-tasks#readme).
@@ -22,3 +28,4 @@
 
 * Initial release.
 
+[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+# gem 'command_mapper', '~> 0.1', github: 'postmodern/command_mapper.rb'
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+  gem 'simplecov',      '~> 0.7'
+
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck'
+end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2012 Postmodern
+Copyright (c) 2009-2022 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,19 +2,17 @@
 
 * [Source](https://github.com/sophsec/ruby-yasm/)
 * [Issues](https://github.com/sophsec/ruby-yasm/issues)
-* [Email](mailto:postmodern.mod3 at gmail.com)
-* [www.tortall.net/projects/yasm](http://www.tortall.net/projects/yasm/)
-* [www.sophsec.com](http://www.sophsec.com/)
+* [Documentation](https://rubydoc.info/gems/ruby-yasm)
 
 ## Description
 
-A Ruby interface to YASM.
+A Ruby interface to [YASM][yasm].
 
-YASM is a complete rewrite of the NASM assembler, YASM currently supports
-the x86 and AMD64 instruction sets, accepts NASM and GAS assembler syntaxes,
-outputs binary, ELF32, ELF64, 32 and 64-bit Mach-O, RDOFF2, COFF, Win32,
-and Win64 object formats, and generates source debugging information in
-STABS, DWARF 2, and CodeView 8 formats.
+> YASM is a complete rewrite of the NASM assembler, YASM currently supports
+> the x86 and AMD64 instruction sets, accepts NASM and GAS assembler syntaxes,
+> outputs binary, ELF32, ELF64, 32 and 64-bit Mach-O, RDOFF2, COFF, Win32,
+> and Win64 object formats, and generates source debugging information in
+> STABS, DWARF 2, and CodeView 8 formats.
 
 ## Features
 
@@ -24,37 +22,62 @@ STABS, DWARF 2, and CodeView 8 formats.
 
 Assemble a binary file:
 
-    YASM::Program.assemble do |yasm|
-      yasm.syntax = :gas
-      yasm.file   = 'hello_world.S'
-      yasm.output = 'hello_world.o'
-    end
+```ruby
+YASM::Command.run(syntax: :gas, file: 'hello_world.S', output: 'hello_world.o')
+```
 
 Assemble amd64 assembly, in GAS syntax, into an ELF64 file with
 debugging information:
 
-    YASM::Program.assemble do |yasm|
-      yasm.target! :amd64
+```ruby
+YASM::Command.run do |yasm|
+  yasm.target = :amd64
 
-      yasm.syntax = :gas
-      yasm.file   = 'hello_world.S'
+  yasm.syntax = :gas
+  yasm.file   = 'hello_world.S'
 
-      yasm.output        = 'hello_world.o'
-      yasm.output_format = :elf64
-      yasm.debug_format  = :stabs
-    end
+  yasm.output        = 'hello_world.o'
+  yasm.output_format = :elf64
+  yasm.debug_format  = :stabs
+end
+```
 
 ## Requirements
 
-* [yasm](http://www.tortall.net/projects/yasm/) >= 0.8.0
-* [rprogram](http://rprogram.rubyforge.org/) ~> 0.3
+* [yasm] >= 0.8.0
+* [command_mapper] ~> 0.1
 
 ## Install
 
-    $ sudo gem install ruby-yasm
+```shell
+$ gem install ruby-yasm
+```
+
+### yasm
+
+* Debian / Ubuntu:
+
+```shell
+$ sudo apt install yasm
+```
+
+* RedHat / Fedora:
+
+```shell
+$ sudo dnf install yasm
+```
+
+* Homebrew:
+
+```shell
+$ brew install yasm
+```
 
 ## License
 
-Copyright (c) 2009-2017 Postmodern
+Copyright (c) 2009-2022 Hal Brodigan
 
 See {file:LICENSE.txt} for license information.
+
+[yasm]: https://www.tortall.net/projects/yasm/
+[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme

data/Rakefile

@@ -1,36 +1,10 @@
-require 'rubygems'
-require 'rake'
+require 'rubygems/tasks'
+Gem::Tasks.new
 
-begin
-  gem 'rubygems-tasks', '~> 0.1'
-  require 'rubygems/tasks'
-
-  Gem::Tasks.new
-rescue LoadError => e
-  warn e.message
-  warn "Run `gem install rubygems-tasks` to install 'rubygems/tasks'."
-end
-
-begin
-  gem 'rspec', '~> 2.4'
-  require 'rspec/core/rake_task'
-
-  RSpec::Core::RakeTask.new
-rescue LoadError => e
-  task :spec do
-    abort "Please run `gem install rspec` to install RSpec."
-  end
-end
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
 task :test => :spec
 task :default => :spec
 
-begin
-  gem 'yard', '~> 0.7'
-  require 'yard'
-
-  YARD::Rake::YardocTask.new  
-rescue LoadError => e
-  task :yard do
-    abort "Please run `gem install yard` to install YARD."
-  end
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/gemspec.yml

@@ -6,15 +6,13 @@ description:
 license: MIT
 authors: Postmodern
 email: postmodern.mod3@gmail.com
-homepage: https://github.com/sophsec/ruby-yasm#readme
+homepage: https://github.com/postmodern/ruby-yasm#readme
 has_yard: true
 
 requirements: yasm >= 0.6.0
 
 dependencies:
-  rprogram: ~> 0.3
+  command_mapper: ~> 0.1
 
 development_dependencies:
-  rubygems-tasks: ~> 0.1
-  rspec: ~> 2.4
-  yard: ~> 0.7
+  bundler: ~> 2.0

data/lib/yasm/command.rb

@@ -0,0 +1,272 @@
+require 'command_mapper/command'
+
+module YASM
+  #
+  # Provides an interface for invoking the `yasm` utility.
+  #
+  # ## Examples
+  #
+  # Assemble a binary file:
+  #
+  #     YASM::Command.run(syntax: :gas, file: 'hello_world.S', output: 'hello_world.o')
+  #
+  # Assemble amd64 assembly, in GAS syntax, into an ELF64 file with
+  # debugging information:
+  #
+  #     YASM::Command.run do |yasm|
+  #       yasm.target = :amd64
+  #     
+  #       yasm.syntax = :gas
+  #       yasm.file   = 'hello_world.S'
+  #
+  #       yasm.output        = 'hello_world.o'
+  #       yasm.output_format = :elf64
+  #       yasm.debug_format  = :stabs
+  #     end
+  #
+  # ## `yasm` options:
+  #
+  # * `--version` -  `yasm.version`
+  # * `--license` -  `yasm.license`
+  # * `--help` -  `yasm.help`
+  # * `--arch` -  `yasm.arch`
+  #   * `x86` - x86 (IA-32 and derivatives), AMD64
+  #   * `lc3b` - LC-3b
+  # * `--parser` -  `yasm.parser`
+  #   * `gas` - GNU AS (GAS)-compatible parser
+  #   * `gnu` - GNU AS (GAS)-compatible parser
+  #   * `nasm` - NASM-compatible parser
+  #   * `tasm` - TASM-compatible parser
+  # * `--preproc` -  `yasm.preprocessor`
+  #   * `nasm` - Real NASM Preprocessor
+  #   * `tasm` - Real TASM Preprocessor
+  #   * `raw` - Disable preprocessing
+  #   * `cpp` - Run input through external C preprocessor
+  #   * `gas` - GNU AS (GAS)-compatible preprocessor
+  # * `--oformat` -  `yasm.output_format`
+  #   * `dbg` - Trace of all info passed to object format module
+  #   * `bin` - Flat format binary
+  #   * `dosexe` - DOS .EXE format binary
+  #   * `elf` - ELF
+  #   * `elf32` - ELF (32-bit)
+  #   * `elf64` - ELF (64-bit)
+  #   * `elfx32` - ELF (x32)
+  #   * `coff` - COFF (DJGPP)
+  #   * `macho` - Mac OS X ABI Mach-O File Format
+  #   * `macho32` - Mac OS X ABI Mach-O File Format (32-bit)
+  #   * `macho64` - Mac OS X ABI Mach-O File Format (64-bit)
+  #   * `rdf` - Relocatable Dynamic Object File Format (RDOFF) v2.0
+  #   * `win32` - Win32
+  #   * `win64` - Win64
+  #   * `x64` - Win64
+  #   * `xdf` - Extended Dynamic Object
+  # * `--dformat` -  `yasm.debug_format`
+  #   * `cv8` - CodeView debugging format for VC8
+  #   * `dwarf2` - DWARF2 debugging format
+  #   * `null` - No debugging info
+  #   * `stabs` - Stabs debugging format
+  # * `--lformat` -  `yasm.list_format`
+  #   * `nasm` -NASM-style list format 
+  # * `--list` -  `yasm.list_file`
+  # * `--objfile` -  `yasm.output`
+  # * `--mapfile` -  `yasm.map_file`
+  # * `--machine` -  `yasm.machine`
+  #   * `x86` - IA-32 and derivatives
+  #   * `amd64` - AMD64
+  #   * `x32` - X32
+  # * `--force-strict` -  `yasm.force_strict`
+  # * `-w` -  `yasm.inhibit_warnings`
+  # * `-W` -  `yasm.toggle_warnings`
+  # * `-M` -  `yasm.gen_makefile_deps`
+  # * `-E` -  `yasm.redirect_errors_to`
+  # * `-e` -  `yasm.redirect_errors`
+  # * `--preproc-only` -  `yasm.preprocessor_only`
+  # * `-I` -  `yasm.include`
+  # * `-P` -  `yasm.pre_include`
+  # * `-D` -  `yasm.define`
+  # * `-U` -  `yasm.undefine`
+  # * `-X` -  `yasm.message_style`
+  #   * `gnu`
+  #   * `vc`
+  # * `--prefix` -  `yasm.prefix`
+  # * `--suffix` -  `yasm.suffix`
+  # * `file` -  `yasm.file`
+  #
+  # @since 0.3.0
+  #
+  # @api public
+  #
+  class Command < CommandMapper::Command
+
+    command 'yasm' do
+      option '--version'
+      option '--license'
+      option '--help'
+
+      option '--arch', equals: true,
+                       value: {
+                         type: Enum[
+                                 :x86, # x86 (IA-32 and derivatives), AMD64
+                                 :lc3b # LC-3b
+                               ]
+                       }
+
+      option '--parser', equals: true,
+                         value: {
+                           type: Enum[
+                                   :gas,  # GNU AS (GAS)-compatible parser
+                                   :gnu,  # GNU AS (GAS)-compatible parser
+                                   :nasm, # NASM-compatible parser
+                                   :tasm  # TASM-compatible parser
+                                 ]
+                         }
+
+      option '--preproc', equals: true,
+                          value: {
+                            type: Enum[
+                                    :nasm, # Real NASM Preprocessor
+                                    :tasm, # Real TASM Preprocessor
+                                    :raw,  # Disable preprocessing
+                                    :cpp,  # Run input through external C preprocessor
+                                    :gas   # GNU AS (GAS)-compatible preprocessor
+                                  ]
+                          },
+                          name: :preprocessor
+      option '--oformat', equals: true,
+                          value: {
+                            type: Enum[
+                                    :dbg,     # Trace of all info passed to object format module
+                                    :bin,     # Flat format binary
+                                    :dosexe,  # DOS .EXE format binary
+                                    :elf,     # ELF
+                                    :elf32,   # ELF (32-bit)
+                                    :elf64,   # ELF (64-bit)
+                                    :elfx32,  # ELF (x32)
+                                    :coff,    # COFF (DJGPP)
+                                    :macho,   # Mac OS X ABI Mach-O File Format
+                                    :macho32, # Mac OS X ABI Mach-O File Format (32-bit)
+                                    :macho64, # Mac OS X ABI Mach-O File Format (64-bit)
+                                    :rdf,     # Relocatable Dynamic Object File Format (RDOFF) v2.0
+                                    :win32,   # Win32
+                                    :win64,   # Win64
+                                    :x64,     # Win64
+                                    :xdf      # Extended Dynamic Object
+                                  ]
+                          },
+                          name: :output_format
+      option '--dformat', equals: true,
+                          value: {
+                            type: Enum[
+                                    :cv8,    # CodeView debugging format for VC8
+                                    :dwarf2, # DWARF2 debugging format
+                                    :null,   # No debugging info
+                                    :stabs   # Stabs debugging format
+                                  ]
+                          },
+                          name: :debug_format
+      option '--lformat', equals: true,
+                          value: {
+                            type: Enum[
+                                    :nasm # NASM-style list format
+                                  ]
+                          },
+                          name: :list_format
+
+      option '--list', equals: true,
+                       value:  true,
+                       name:   :list_file
+
+      option '--objfile', equals: true,
+                          value:  true,
+                          name:   :output
+
+      option '--mapfile', equals: true,
+                          value:  true,
+                          name:   :map_file
+
+      option  '--machine', equals: true,
+                           value: {
+                             type: Enum[
+                                     :x86,   # IA-32 and derivatives
+                                     :amd64, # AMD64
+                                     :x32    # X32
+                                   ]
+                           }
+
+      option  '--force-strict'
+      option '-w', name: :inhibit_warnings
+      option '-W', name: :toggle_warnings
+      option '-M', name: :gen_makefile_deps
+      option '-E', value: true, name: :redirect_errors_to
+      option '-s', name: :redirect_errors
+      option  '--preproc-only', name: :preprocessor_only
+
+      option '-I', value:   {type: InputDir.new},
+                   repeats: true,
+                   name:    :include
+
+      option '-P', value: {type: InputFile.new},
+                   repeats: true,
+                   name: :pre_include
+
+      option '-D', name: :define, repeats: true
+
+      option '-U', value: true,
+                   repeats: true,
+                   name: :undefine
+
+      option '-X', value: {type: Enum[:gnu, :vc]},
+                   name:  :message_style
+
+      option  '--prefix'
+      option  '--suffix'
+
+      argument :file, type: InputFile.new
+    end
+
+    # The known YASM targets
+    TARGETS = {
+      x86:   {arch: :x86,  machine: :x86},
+      amd64: {arch: :x86,  machine: :amd64},
+      lc3b:  {arch: :lc3b, machine: :lc3b}
+    }
+
+    #
+    # Determines which target was set.
+    #
+    # @return [:x86, :amd64, :lc3b, nil]
+    #   The target name or `nil` if no target has been set.
+    #
+    def target
+      if arch && machine
+        TARGETS.key(arch: arch.to_sym, machine: machine.to_sym)
+      end
+    end
+
+    #
+    # Sets that target.
+    #
+    # @param [:x86, :amd64, :lc3b] name
+    #   The target name.
+    #
+    # @return [Symbol]
+    #   The set target.
+    #
+    # @raise [ArgumentError]
+    #   An unknown target name was given.
+    #
+    def target=(name)
+      target = TARGETS.fetch(name.to_sym) do
+        raise(ArgumentError,"unknown YASM target: #{name.inspect}")
+      end
+
+      self.arch    = target[:arch]
+      self.machine = target[:machine]
+      return name
+    end
+
+    alias syntax parser
+    alias syntax= parser=
+
+  end
+end

data/lib/yasm/program.rb

@@ -1,11 +1,10 @@
-require 'yasm/task'
-
-require 'rprogram'
+require 'yasm/command'
 
 module YASM
-  class Program < RProgram::Program
-
-    name_program 'yasm'
+  #
+  # @deprecated Please use {Command} instead.
+  #
+  class Program < Command
 
     #
     # Finds the `yasm` program and assembles a file.
@@ -13,15 +12,12 @@ module YASM
     # @param [Hash{Symbol => Object}] options
     #   Additional options for yasm.
     #
-    # @param [Hash{Symbol => Object}] exec_options
-    #   Additional exec-options.
-    #
-    # @yield [task]
-    #   If a block is given, it will be passed a task object used to
+    # @yield [program]
+    #   If a block is given, it will be passed a program object used to
     #   specify options for yasm.
     #
-    # @yieldparam [Task] task
-    #   The yasm task object.
+    # @yieldparam [Program] program
+    #   The yasm program object.
     #
     # @return [Boolean]
     #   Specifies whether the command exited normally.
@@ -44,8 +40,8 @@ module YASM
     #
     # @see #assemble
     #
-    def self.assemble(options={},exec_options={},&block)
-      find.assemble(options,exec_options,&block)
+    def self.assemble(options={},&block)
+      new(options,&block).assemble()
     end
 
     #
@@ -54,15 +50,12 @@ module YASM
     # @param [Hash{Symbol => Object}] options
     #   Additional options for yasm.
     #
-    # @param [Hash{Symbol => Object}] exec_options
-    #   Additional exec-options.
-    #
-    # @yield [task]
-    #   If a block is given, it will be passed a task object used to
+    # @yield [program]
+    #   If a block is given, it will be passed a program object used to
     #   specify options for yasm.
     #
-    # @yieldparam [Task] task
-    #   The yasm task object.
+    # @yieldparam [Program] program
+    #   The yasm program object.
     #
     # @return [Boolean]
     #   Specifies whether the command exited normally.
@@ -83,11 +76,22 @@ module YASM
     #     yasm.output = 'code.o'
     #   end
     #
-    # @see http://rubydoc.info/gems/rprogram/0.3.0/RProgram/Program#run-instance_method
-    #   For additional exec-options.
+    def assemble(options={})
+      options.each do |name,value|
+        self[name] = value
+      end
+
+      yield self if block_given?
+
+      run_command()
+    end
+
+    #
+    # @deprecated Please use {#target=} instead.
     #
-    def assemble(options={},exec_options={},&block)
-      run_task(Task.new(options,&block),exec_options)
+    def target!(name)
+      self.target = name
+      return true
     end
 
   end

data/lib/yasm/version.rb

@@ -1,4 +1,4 @@
 module YASM
   # ruby-yasm VERSION
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/yasm.rb

@@ -1,2 +1,3 @@
+require 'yasm/command'
 require 'yasm/program'
 require 'yasm/version'