ruby-macho 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 555d8c0f3cd81252ac1319053a95d643536387a2
-  data.tar.gz: 23a91b4980829b2b8d2133f226aeefbc4bd950b4
+  metadata.gz: 14255fd4c8aaab675981bcf982893a8be8b6ba0c
+  data.tar.gz: e89c2ff64ebe885089b1b3b3ffa3c80418070fdd
 SHA512:
-  metadata.gz: 37f23f18f8a4a4c07933978d7be6bcb65cc6655f778496a8b2b5e2932cfa199f3230bb82399f1f964c06469ec74cece3fd9fb2ef4c6d39c2ef933eaa185ae96c
-  data.tar.gz: 39bfb1a708519820a4afbbccb6a47da8c7ef3ad2641d7ad5c7969709f50f4ce7ffc3369918238848da2786f49fd9e10209d0e7e0b6bbba96a2a9620b6f6bdfc6
+  metadata.gz: f8796363fb1de467d352e6ed808865d83a84b8cbca747037c542f788feb316cc6e733d03817d01d4182d5049b90b557365e8c4bd9e24ef2f4eab15cca212c92a
+  data.tar.gz: efc4df8def9305d15edb6273ea72baf8d8da778151697bae975be45750da6f7eec6c541b9852875b8ce4f469ee05bf8b380816ea0fe79ea5e66e04a1e710565e

data/README.md

@@ -14,6 +14,9 @@ executables, dynamic libraries, and so forth.
 
 ### Documentation
 
+**Important**: ruby-macho does not have a stable API (yet). Use it with this
+in mind.
+
 Full documentation is available on [RubyDoc](http://www.rubydoc.info/gems/ruby-macho/).
 
 A quick example of what ruby-macho can do:
@@ -23,8 +26,8 @@ require 'macho'
 
 file = MachO::MachOFile.new("/path/to/my/binary")
 
-# get the file's type (MH_OBJECT, MH_DYLIB, MH_EXECUTE, etc)
-file.filetype # => "MH_EXECUTE"
+# get the file's type (object, dynamic lib, executable, etc)
+file.filetype # => :execute
 
 # get all load commands in the file and print their offsets:
 file.load_commands.each do |lc|
@@ -32,7 +35,7 @@ file.load_commands.each do |lc|
 end
 
 # access a specific load command
-lc_vers = file['LC_VERSION_MIN_MACOSX'].first
+lc_vers = file[:LC_VERSION_MIN_MACOSX].first
 puts lc_vers.version_string # => "10.10.0"
 ```
 
@@ -41,16 +44,12 @@ puts lc_vers.version_string # => "10.10.0"
 * Reading data from x86/x86_64/PPC Mach-O files
 * Changing the IDs of Mach-O and Fat dylibs
 * Changing install names in Mach-O and Fat files
-
-### What doesn't work yet?
-
-* Adding, deleting, or modifying rpaths.
+* Adding, deleting, and modifying rpaths.
 
 ### What needs to be done?
 
 * Documentation.
-* Rpath modification.
-* Many, many things.
+* Unit and performance testing.
 
 Attribution:
 

data/lib/macho.rb

@@ -1,4 +1,5 @@
 require "#{File.dirname(__FILE__)}/macho/structure"
+require "#{File.dirname(__FILE__)}/macho/view"
 require "#{File.dirname(__FILE__)}/macho/headers"
 require "#{File.dirname(__FILE__)}/macho/load_commands"
 require "#{File.dirname(__FILE__)}/macho/sections"
@@ -12,5 +13,5 @@ require "#{File.dirname(__FILE__)}/macho/tools"
 # The primary namespace for ruby-macho.
 module MachO
   # release version
-  VERSION = "0.2.4".freeze
+  VERSION = "0.2.5".freeze
 end

data/lib/macho/exceptions.rb

@@ -3,6 +3,26 @@ module MachO
   class MachOError < RuntimeError
   end
 
+  # Raised when a Mach-O file modification fails.
+  class ModificationError < MachOError
+  end
+
+  # Raised when a Mach-O file modification fails but can be recovered when
+  # operating on multiple Mach-O slices of a fat binary in non-strict mode.
+  class RecoverableModificationError < ModificationError
+    # @return [Fixnum, nil] The index of the Mach-O slice of a fat binary for
+    #   which modification failed or `nil` if not a fat binary. This is used to
+    #   make the error message more useful.
+    attr_accessor :macho_slice
+
+    # @return [String] The exception message.
+    def to_s
+      s = super.to_s
+      s = "While modifying Mach-O slice #{@macho_slice}: #{s}" if @macho_slice
+      s
+    end
+  end
+
   # Raised when a file is not a Mach-O.
   class NotAMachOError < MachOError
     # @param error [String] the error in question
@@ -80,32 +100,89 @@ module MachO
     end
   end
 
+  # Raised when a load command can't be created manually.
+  class LoadCommandNotCreatableError < MachOError
+    # @param cmd_sym [Symbol] the uncreatable load command's symbol
+    def initialize(cmd_sym)
+      super "Load commands of type #{cmd_sym} cannot be created manually"
+    end
+  end
+
+  # Raised when the number of arguments used to create a load command manually is wrong.
+  class LoadCommandCreationArityError < MachOError
+    # @param cmd_sym [Symbol] the load command's symbol
+    # @param expected_arity [Fixnum] the number of arguments expected
+    # @param actual_arity [Fixnum] the number of arguments received
+    def initialize(cmd_sym, expected_arity, actual_arity)
+      super "Expected #{expected_arity} arguments for #{cmd_sym} creation, got #{actual_arity}"
+    end
+  end
+
+  # Raised when a load command can't be serialized.
+  class LoadCommandNotSerializableError < MachOError
+    # @param cmd_sym [Symbol] the load command's symbol
+    def initialize(cmd_sym)
+      super "Load commands of type #{cmd_sym} cannot be serialized"
+    end
+  end
+
+  # Raised when a load command string is malformed in some way.
+  class LCStrMalformedError < MachOError
+    # @param lc [MachO::LoadCommand] the load command containing the string
+    def initialize(lc)
+      super "Load command #{lc.type} at offset #{lc.view.offset} contains a malformed string"
+    end
+  end
+
+  # Raised when a change at an offset is not valid.
+  class OffsetInsertionError < ModificationError
+    # @param offset [Fixnum] the invalid offset
+    def initialize(offset)
+      super "Insertion at offset #{offset} is not valid"
+    end
+  end
+
   # Raised when load commands are too large to fit in the current file.
-  class HeaderPadError < MachOError
+  class HeaderPadError < ModificationError
     # @param filename [String] the filename
     def initialize(filename)
-      super "Updated load commands do not fit in the header of " +
-      "#{filename}. #{filename} needs to be relinked, possibly with " +
-      "-headerpad or -headerpad_max_install_names"
+      super "Updated load commands do not fit in the header of " \
+        "#{filename}. #{filename} needs to be relinked, possibly with " \
+        "-headerpad or -headerpad_max_install_names"
     end
   end
 
   # Raised when attempting to change a dylib name that doesn't exist.
-  class DylibUnknownError < MachOError
+  class DylibUnknownError < RecoverableModificationError
     # @param dylib [String] the unknown shared library name
     def initialize(dylib)
       super "No such dylib name: #{dylib}"
     end
   end
 
+  # Raised when a dylib is missing an ID
+  class DylibIdMissingError < RecoverableModificationError
+    def initialize
+      super "Dylib is missing a dylib ID"
+    end
+  end
+
   # Raised when attempting to change an rpath that doesn't exist.
-  class RpathUnknownError < MachOError
+  class RpathUnknownError < RecoverableModificationError
     # @param path [String] the unknown runtime path
     def initialize(path)
       super "No such runtime path: #{path}"
     end
   end
 
+  # Raised when attempting to add an rpath that already exists.
+  class RpathExistsError < RecoverableModificationError
+    # @param path [String] the extant path
+    def initialize(path)
+      super "#{path} already exists"
+    end
+  end
+
   # Raised whenever unfinished code is called.
   class UnimplementedError < MachOError
     # @param thing [String] the thing that is unimplemented

data/lib/macho/fat_file.rb

@@ -30,22 +30,24 @@ module MachO
     # @param filename [String] the fat file to load from
     # @raise [ArgumentError] if the given file does not exist
     def initialize(filename)
-      raise ArgumentError.new("#{filename}: no such file") unless File.file?(filename)
+      raise ArgumentError, "#{filename}: no such file" unless File.file?(filename)
 
       @filename = filename
-      @raw_data = File.open(@filename, "rb") { |f| f.read }
-      @header = get_fat_header
-      @fat_archs = get_fat_archs
-      @machos = get_machos
+      @raw_data = File.open(@filename, "rb", &:read)
+      @header = populate_fat_header
+      @fat_archs = populate_fat_archs
+      @machos = populate_machos
     end
 
+    # Initializes a new FatFile instance from a binary string.
+    # @see MachO::FatFile.new_from_bin
     # @api private
     def initialize_from_bin(bin)
       @filename = nil
       @raw_data = bin
-      @header = get_fat_header
-      @fat_archs = get_fat_archs
-      @machos = get_machos
+      @header = populate_fat_header
+      @fat_archs = populate_fat_archs
+      @machos = populate_machos
     end
 
     # The file's raw fat data.
@@ -115,7 +117,7 @@ module MachO
     end
 
     # The file's type. Assumed to be the same for every Mach-O within.
-    # @return [String] the filetype
+    # @return [Symbol] the filetype
     def filetype
       machos.first.filetype
     end
@@ -124,34 +126,37 @@ module MachO
     # @example
     #  file.dylib_id # => 'libBar.dylib'
     # @return [String, nil] the file's dylib ID
+    # @see MachO::MachOFile#linked_dylibs
     def dylib_id
       machos.first.dylib_id
     end
 
     # Changes the file's dylib ID to `new_id`. If the file is not a dylib, does nothing.
     # @example
-    #  file.dylib_id = 'libFoo.dylib'
+    #  file.change_dylib_id('libFoo.dylib')
     # @param new_id [String] the new dylib ID
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) if true, fail if one slice fails.
+    #  if false, fail only if all slices fail.
     # @return [void]
     # @raise [ArgumentError] if `new_id` is not a String
-    def dylib_id=(new_id)
-      if !new_id.is_a?(String)
-        raise ArgumentError.new("argument must be a String")
-      end
-
-      if !machos.all?(&:dylib?)
-        return nil
-      end
+    # @see MachO::MachOFile#linked_dylibs
+    def change_dylib_id(new_id, options = {})
+      raise ArgumentError, "argument must be a String" unless new_id.is_a?(String)
+      return unless machos.all?(&:dylib?)
 
-      machos.each do |macho|
-        macho.dylib_id = new_id
+      each_macho(options) do |macho|
+        macho.change_dylib_id(new_id, options)
       end
 
       synchronize_raw_data
     end
 
+    alias dylib_id= change_dylib_id
+
     # All shared libraries linked to the file's Mach-Os.
     # @return [Array<String>] an array of all shared libraries
+    # @see MachO::MachOFile#linked_dylibs
     def linked_dylibs
       # Individual architectures in a fat binary can link to different subsets
       # of libraries, but at this point we want to have the full picture, i.e.
@@ -165,16 +170,74 @@ module MachO
     #  file.change_install_name('/usr/lib/libFoo.dylib', '/usr/lib/libBar.dylib')
     # @param old_name [String] the shared library name being changed
     # @param new_name [String] the new name
-    # @todo incomplete
-    def change_install_name(old_name, new_name)
-      machos.each do |macho|
-        macho.change_install_name(old_name, new_name)
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) if true, fail if one slice fails.
+    #  if false, fail only if all slices fail.
+    # @return [void]
+    # @see MachO::MachOFile#change_install_name
+    def change_install_name(old_name, new_name, options = {})
+      each_macho(options) do |macho|
+        macho.change_install_name(old_name, new_name, options)
+      end
+
+      synchronize_raw_data
+    end
+
+    alias change_dylib change_install_name
+
+    # All runtime paths associated with the file's Mach-Os.
+    # @return [Array<String>] an array of all runtime paths
+    # @see MachO::MachOFile#rpaths
+    def rpaths
+      # Can individual architectures have different runtime paths?
+      machos.map(&:rpaths).flatten.uniq
+    end
+
+    # Change the runtime path `old_path` to `new_path` in the file's Mach-Os.
+    # @param old_path [String] the old runtime path
+    # @param new_path [String] the new runtime path
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) if true, fail if one slice fails.
+    #  if false, fail only if all slices fail.
+    # @return [void]
+    # @see MachO::MachOFile#change_rpath
+    def change_rpath(old_path, new_path, options = {})
+      each_macho(options) do |macho|
+        macho.change_rpath(old_path, new_path, options)
+      end
+
+      synchronize_raw_data
+    end
+
+    # Add the given runtime path to the file's Mach-Os.
+    # @param path [String] the new runtime path
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) if true, fail if one slice fails.
+    #  if false, fail only if all slices fail.
+    # @return [void]
+    # @see MachO::MachOFile#add_rpath
+    def add_rpath(path, options = {})
+      each_macho(options) do |macho|
+        macho.add_rpath(path, options)
       end
 
       synchronize_raw_data
     end
 
-    alias :change_dylib :change_install_name
+    # Delete the given runtime path from the file's Mach-Os.
+    # @param path [String] the runtime path to delete
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) if true, fail if one slice fails.
+    #  if false, fail only if all slices fail.
+    # @return void
+    # @see MachO::MachOFile#delete_rpath
+    def delete_rpath(path, options = {})
+      each_macho(options) do |macho|
+        macho.delete_rpath(path, options)
+      end
+
+      synchronize_raw_data
+    end
 
     # Extract a Mach-O with the given CPU type from the file.
     # @example
@@ -197,7 +260,7 @@ module MachO
     # @note Overwrites all data in the file!
     def write!
       if filename.nil?
-        raise MachOError.new("cannot write to a default file when initialized from a binary string")
+        raise MachOError, "cannot write to a default file when initialized from a binary string"
       else
         File.open(@filename, "wb") { |f| f.write(@raw_data) }
       end
@@ -211,15 +274,15 @@ module MachO
     # @raise [MachO::MagicError] if the magic is not valid Mach-O magic
     # @raise [MachO::MachOBinaryError] if the magic is for a non-fat Mach-O file
     # @raise [MachO::JavaClassFileError] if the file is a Java classfile
-    # @private
-    def get_fat_header
+    # @api private
+    def populate_fat_header
       # the smallest fat Mach-O header is 8 bytes
-      raise TruncatedFileError.new if @raw_data.size < 8
+      raise TruncatedFileError if @raw_data.size < 8
 
       fh = FatHeader.new_from_bin(:big, @raw_data[0, FatHeader.bytesize])
 
-      raise MagicError.new(fh.magic) unless MachO.magic?(fh.magic)
-      raise MachOBinaryError.new unless MachO.fat_magic?(fh.magic)
+      raise MagicError, fh.magic unless Utils.magic?(fh.magic)
+      raise MachOBinaryError unless Utils.fat_magic?(fh.magic)
 
       # Rationale: Java classfiles have the same magic as big-endian fat
       # Mach-Os. Classfiles encode their version at the same offset as
@@ -228,15 +291,15 @@ module MachO
       # technically possible for a fat Mach-O to have over 30 architectures,
       # but this is extremely unlikely and in practice distinguishes the two
       # formats.
-      raise JavaClassFileError.new if fh.nfat_arch > 30
+      raise JavaClassFileError if fh.nfat_arch > 30
 
       fh
     end
 
     # Obtain an array of fat architectures from raw file data.
     # @return [Array<MachO::FatArch>] an array of fat architectures
-    # @private
-    def get_fat_archs
+    # @api private
+    def populate_fat_archs
       archs = []
 
       fa_off = FatHeader.bytesize
@@ -250,8 +313,8 @@ module MachO
 
     # Obtain an array of Mach-O blobs from raw file data.
     # @return [Array<MachO::MachOFile>] an array of Mach-Os
-    # @private
-    def get_machos
+    # @api private
+    def populate_machos
       machos = []
 
       fat_archs.each do |arch|
@@ -261,9 +324,37 @@ module MachO
       machos
     end
 
-    # @todo this needs to be redesigned. arch[:offset] and arch[:size] are
-    # already out-of-date, and the header needs to be synchronized as well.
-    # @private
+    # Yield each Mach-O object in the file, rescuing and accumulating errors.
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if at least one Mach-O raises an exception. If false,
+    #  only raises an exception if *all* Mach-Os raise exceptions.
+    # @raise [MachO::RecoverableModificationError] under the conditions of
+    #  the `:strict` option above.
+    # @api private
+    def each_macho(options = {})
+      strict = options.fetch(:strict, true)
+      errors = []
+
+      machos.each_with_index do |macho, index|
+        begin
+          yield macho
+        rescue RecoverableModificationError => error
+          error.macho_slice = index
+
+          # Strict mode: Immediately re-raise. Otherwise: Retain, check later.
+          raise error if strict
+          errors << error
+        end
+      end
+
+      # Non-strict mode: Raise first error if *all* Mach-O slices failed.
+      raise errors.first if errors.size == machos.size
+    end
+
+    # Synchronize the raw file data with each internal Mach-O object.
+    # @return [void]
+    # @api private
     def synchronize_raw_data
       machos.each_with_index do |macho, i|
         arch = fat_archs[i]