ruby-macho 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b104665e169f8988913d6032d3755032d814a2f
-  data.tar.gz: fc3f95ed644f84e913a78709227e178f33e9e995
+  metadata.gz: 119afdca4c1793c3bc3f8285c88a8126ab4e1e76
+  data.tar.gz: 26346fa156b237e2606e8b005c95330bc1b194ad
 SHA512:
-  metadata.gz: 986523ca44a54d65a2d1624b31cbd612f520bab44ffaf405971052174224e9fedde4aabf1aa5d91fe451ee58cde5d892d95030bf6dad8f4688389fe8fc3f18dd
-  data.tar.gz: b5e6ffe8212660e32ed089d7dba2294818257aeb523b8eac8a3d4d66b9a549a210b40037109c26ff2cd31e47c7921fbe3389153b86dff30816efab83a061cbd4
+  metadata.gz: 413afe10c917e3e7365711b821904f058d48a9c92a6fcf36d1fecd132b1bbd5971e2d6e547b1684fb46061a328cfaf71afc35788068a1480d33bbde24a0e6d1d
+  data.tar.gz: cf66bd02bac6b2956bbad64d2f0f82de46e339713ab9ddbfecea88902399f304a58fcb8588294025f647180077f4e054feb40ed85bbeaee941aa00aed26babca

data/lib/cstruct.rb

@@ -316,31 +316,3 @@ class CStruct
   # The last expression is returned, so return self instead of junk.
   self  
 end
-
-
-# a small test
-if $0 == __FILE__
-  class MachHeader < CStruct
-    uint :magic
-    int  :cputype
-    int  :cpusubtype
-    string :segname, 16
-  end
-  puts MachHeader::Members.inspect
-  puts MachHeader::MemberIndex.inspect
-  puts MachHeader::MemberSizes.inspect
-  puts "# of MachHeader members: " + MachHeader.size.to_s + ", size in bytes: " + MachHeader.bytesize.to_s
-  mh = MachHeader.new(0xfeedface, 7, 3, "foobar")
-  %w[magic cputype cpusubtype segname].each do |field|
-    puts "#{field}(#{MachHeader.sizeof(field.to_sym)}):      #{mh[field.to_sym].inspect}"
-  end
-  puts mh.pack_pattern.inspect
-  binstr = mh.serialize
-  puts "values: " + mh.values.inspect
-  newmh = MachHeader.new_from_bin(binstr)
-  puts "new values: " + newmh.values.inspect
-  newbinstr = newmh.serialize
-  puts "serialized:   " + binstr.inspect
-  puts "unserialized: " + newbinstr.inspect
-  puts "new == old ? " + (newbinstr == binstr).to_s
-end

data/lib/macho/fat_file.rb

@@ -1,7 +1,22 @@
 module MachO
+	# Represents a "Fat" file, which contains a header, a listing of available
+	# architectures, and one or more Mach-O binaries.
+	# @see https://en.wikipedia.org/wiki/Mach-O#Multi-architecture_binaries
+	# @see MachO::MachOFile
 	class FatFile
-		attr_reader :header, :fat_archs, :machos
+		# @return [MachO::FatHeader] the file's header
+		attr_reader :header
 
+		# @return [Array<MachO::FatArch>] an array of fat architectures
+		attr_reader :fat_archs
+
+		# @return [Array<MachO::MachOFile>] an array of Mach-O binaries
+		attr_reader :machos
+
+		# Creates a new FatFile from the given filename.
+		# @param filename [String] the fat file to load from
+		# @raise [MachO::MagicError] if the file does not have a Mach-O magic number.
+		# @raise [MachO::MachOBinaryError] if the file is not a fat binary.
 		def initialize(filename)
 			raise ArgumentError.new("filename must be a String") unless filename.is_a? String
 
@@ -12,10 +27,16 @@ module MachO
 			@machos = get_machos
 		end
 
+		# The file's raw fat data.
+		# @return [String] the raw fat data
 		def serialize
 			@raw_data
 		end
 
+		# The file's dylib ID. If the file is not a dylib, returns `nil`.
+		# @example
+		#  file.dylib_id # => 'libBar.dylib'
+		# @return [String] the file's dylib ID
 		def dylib_id
 			if !machos.all?(&:dylib?)
 				return nil
@@ -31,6 +52,10 @@ module MachO
 			ids.first
 		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'
+		# @param new_id [String] the new dylib ID
 		def dylib_id=(new_id)
 			if !new_id.is_a?(String)
 				raise ArgumentError.new("argument must be a String")
@@ -47,6 +72,8 @@ module MachO
 			synchronize_raw_data
 		end
 
+		# All shared libraries linked to the file's Mach-Os.
+		# @return [Array<String>] an array of all shared libraries
 		def linked_dylibs
 			dylibs = machos.map(&:linked_dylibs).flatten
 
@@ -54,27 +81,40 @@ module MachO
 			dylibs.uniq!
 		end
 
-		# stub
-		def change_dylib(old_path, new_path)
+		# Changes all dependent shared library install names from `old_name` to `new_name`.
+		# In a fat file, this changes install names in all internal Mach-Os.
+		# @example
+		#  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_path, new_path)
+				macho.change_install_name(old_name, new_name)
 			end
 
 			synchronize_raw_data
 		end
 
-		alias :change_install_name :change_dylib
+		alias :change_dylib :change_install_name
 
+		# Write all (fat) data to the given filename.
+		# @param filename [String] the file to write to
 		def write(filename)
 			File.open(filename, "wb") { |f| f.write(@raw_data) }
 		end
 
+		# Write all (fat) data to the file used to initialize the instance.
+		# IMPORTANT: Overwrites all data in the file!
 		def write!
 			File.open(@filename, "wb") { |f| f.write(@raw_data) }
 		end
 
 		private
 
+		# Obtain the fat header from raw file data.
+		# @return [MachO::FatHeader] the fat header
+		# @private
 		def get_fat_header
 			magic, nfat_arch = @raw_data[0..7].unpack("N2")
 
@@ -89,6 +129,9 @@ module MachO
 			FatHeader.new(magic, nfat_arch)
 		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
 			archs = []
 
@@ -100,6 +143,9 @@ module MachO
 			archs
 		end
 
+		# Obtain an array of Mach-O blobs from raw file data.
+		# @return [Array<MachO::MachOFile>] an array of Mach-Os
+		# @private
 		def get_machos
 			machos = []
 
@@ -110,10 +156,8 @@ module MachO
 			machos
 		end
 
-		# when we create machos within FatFile, we initialize them with slices
-		# from @raw_data. this means creating new arrays that don't affect
-		# @raw_data directly, so we need to synchronize it after changing
-		# anything within the machos.
+		# @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.
 		def synchronize_raw_data
 			machos.each_with_index do |macho, i|
 				arch = fat_archs[i]

data/lib/macho/macho_file.rb

@@ -1,7 +1,19 @@
 module MachO
+	# Represents a Mach-O file, which contains a header and load commands
+	# as well as binary executable instructions. Mach-O binaries are
+	# architecture specific.
+	# @see https://en.wikipedia.org/wiki/Mach-O
 	class MachOFile
-		attr_reader :header, :load_commands
+		# @return [MachO::MachHeader] if the Mach-O is 32-bit
+		# @return [MachO::MachHeader64] if the Mach-O is 64-bit
+		attr_reader :header
 
+		# @return [Array<MachO::LoadCommand>] an array of the file's load commands
+		attr_reader :load_commands
+
+		# Creates a new MachOFile instance from a binary string.
+		# @param bin [String] a binary string containing raw Mach-O data
+		# @return [MachO::MachOFile] a new MachOFile
 		def self.new_from_bin(bin)
 			instance = allocate
 			instance.initialize_from_bin(bin)
@@ -9,6 +21,9 @@ module MachO
 			instance
 		end
 
+		# Creates a new FatFile from the given filename.
+		# @param filename [String] the Mach-O file to load from
+		# @todo document all the exceptions propagated here
 		def initialize(filename)
 			raise ArgumentError.new("filename must be a String") unless filename.is_a? String
 
@@ -18,6 +33,7 @@ module MachO
 			@load_commands = get_load_commands
 		end
 
+		# @private
 		def initialize_from_bin(bin)
 			@filename = nil
 			@raw_data = bin
@@ -25,80 +41,91 @@ module MachO
 			@load_commands = get_load_commands
 		end
 
+		# The file's raw Mach-O data.
+		# @return [String] the raw Mach-O data
 		def serialize
 			@raw_data
 		end
 
+		# @return [Boolean] true if the Mach-O has 32-bit magic, false otherwise
 		def magic32?
 			MachO.magic32?(header[:magic])
 		end
 
+		# @return [Boolean] true if the Mach-O has 64-bit magic, false otherwise
 		def magic64?
 			MachO.magic64?(header[:magic])
 		end
 
-		# is the file executable?
+		# @return [Boolean] true if the Mach-O is of type `MH_EXECUTE`, false otherwise
 		def executable?
 			header[:filetype] == MH_EXECUTE
 		end
 
-		# is the file a dynamically bound shared object?
+		# @return [Boolean] true if the Mach-O is of type `MH_DYLIB`, false otherwise
 		def dylib?
 			header[:filetype] == MH_DYLIB
 		end
 
-		# is the file a dynamically bound bundle?
+		# @return [Boolean] true if the Mach-O is of type `MH_BUNDLE`, false otherwise
 		def bundle?
 			header[:filetype] == MH_BUNDLE
 		end
 
+		# @return [Fixnum] the Mach-O's magic number
 		def magic
 			header[:magic]
 		end
 
-		# string representation of the header's magic bytes
+		# @return [String] a string representation of the Mach-O's magic number
 		def magic_string
 			MH_MAGICS[header[:magic]]
 		end
 
-		# string representation of the header's filetype field
+		# @return [String] a string representation of the Mach-O's filetype
 		def filetype
 			MH_FILETYPES[header[:filetype]]
 		end
 
-		# string representation of the header's cputype field
+		# @return [String] a string representation of the Mach-O's CPU type
 		def cputype
 			CPU_TYPES[header[:cputype]]
 		end
 
-		# string representation of the header's cpusubtype field
+		# @return [String] a string representation of the Mach-O's CPU subtype
 		def cpusubtype
 			CPU_SUBTYPES[header[:cpusubtype]]
 		end
 
-		# number of load commands in the header
+		# @return [Fixnum] the number of load commands in the Mach-O's header
 		def ncmds
 			header[:ncmds]
 		end
 
-		# size of all load commands
+		# @return [Fixnum] the size of all load commands, in bytes
 		def sizeofcmds
 			header[:sizeofcmds]
 		end
 
-		# various execution flags
+		# @return [Fixnum] execution flags set by the linker
 		def flags
 			header[:flags]
 		end
 
-		# get load commands by name
+		# All load commands of a given name.
+		# @example
+		#  file.command("LC_LOAD_DYLIB")
+		#  file["LC_LOAD_DYLIB"]
+		# @return [Array<MachO::LoadCommand>] an array of LoadCommands corresponding to `name`
 		def command(name)
 			load_commands.select { |lc| lc.to_s == name }
 		end
 
 		alias :[] :command
 
-		# get all segment commands
+		# All segment load commands in the Mach-O.
+		# @return [Array<MachO::SegmentCommand>] if the Mach-O is 32-bit
+		# @return [Array<MachO::SegmentCommand64>] if the Mach-O is 64-bit
 		def segments
 			if magic32?
 				command("LC_SEGMENT")
@@ -107,7 +134,10 @@ module MachO
 			end
 		end
 
-		# get the file's dylib id, if it is a dylib
+		# The Mach-O's dylib ID, or `nil` if not a dylib.
+		# @example
+		#  file.dylib_id # => 'libBar.dylib'
+		# @return [String] the Mach-O's dylib ID
 		def dylib_id
 			if !dylib?
 				return nil
@@ -124,6 +154,11 @@ module MachO
 			dylib_id.delete("\x00")
 		end
 
+		# Changes the Mach-O's dylib ID to `new_id`. Does nothing if not a dylib.
+		# @example
+		#  file.dylib_id = "libFoo.dylib"
+		# @return [void]
+		# @todo refactor
 		def dylib_id=(new_id)
 			if !new_id.is_a?(String)
 				raise ArgumentError.new("argument must be a String")
@@ -199,7 +234,8 @@ module MachO
 			load_commands = get_load_commands
 		end
 
-		# get a list of dylib paths linked to this file
+		# All shared libraries linked to the Mach-O.
+		# @return [Array<String>] an array of all shared libraries
 		def linked_dylibs
 			dylibs = []
 			dylib_cmds = command('LC_LOAD_DYLIB')
@@ -217,10 +253,11 @@ module MachO
 			dylibs
 		end
 
-		# TODO: genericize change_dylib and dylib_id= for DRYness
-		def change_dylib(old_path, new_path)
-			idx = linked_dylibs.index(old_path)
-			raise DylibUnknownError.new(old_path) if idx.nil?
+		# @return [void]
+		# @todo refactor
+		def change_install_name(old_name, new_name)
+			idx = linked_dylibs.index(old_name)
+			raise DylibUnknownError.new(old_name) if idx.nil?
 
 			# this is a bit of a hack - since there is a 1-1 ordered association
 			# between linked_dylibs and command('LC_LOAD_DYLIB'), we can use
@@ -234,8 +271,8 @@ module MachO
 			end
 
 			new_sizeofcmds = header[:sizeofcmds]
-			old_install_name = old_path.dup
-			new_install_name = new_path.dup
+			old_install_name = old_name.dup
+			new_install_name = new_name.dup
 
 			old_pad = MachO.round(old_install_name.size, cmd_round) - old_install_name.size
 			new_pad = MachO.round(new_install_name.size, cmd_round) - new_install_name.size
@@ -283,9 +320,11 @@ module MachO
 			load_commands = get_load_commands
 		end
 
-		alias :change_install_name :change_dylib
+		alias :change_dylib :change_install_name
 
-		# get all sections in a segment by name
+		# All sections of the segment `segment`.
+		# @return [Array<MachO::Section>] if the Mach-O is 32-bit
+		# @return [Array<MachO::Section64>] if the Mach-O is 64-bit
 		def sections(segment)
 			sections = []
 
@@ -312,10 +351,16 @@ module MachO
 			sections
 		end
 
+		# Write all Mach-O data to the given filename.
+		# @param filename [String] the file to write to
+		# @return [void]
 		def write(filename)
 			File.open(filename, "wb") { |f| f.write(@raw_data) }
 		end
 
+		# Write all Mach-O data to the file used to initialize the instance.
+		# @raise [MachOError] if the instance was created from a binary string
+		# @return [void]
 		def write!
 			if @filename.nil?
 				raise MachOError.new("cannot write to a default file when initialized from a binary string")

data/lib/macho.rb

@@ -10,6 +10,10 @@ require "#{File.dirname(__FILE__)}/macho/utils"
 require "#{File.dirname(__FILE__)}/macho/tools"
 
 module MachO
+	# Opens the given filename as a MachOFile or FatFile, depending on its magic.
+	# @param filename [String] the file being opened
+	# @return [MachO::MachOFile] if the file is a Mach-O
+	# @return [MachO::FatFile] if the file is a Fat file
 	def self.open(filename)
 		# open file and test magic instead of using exceptions for control?
 		begin

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-macho
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - William Woodruff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-21 00:00:00.000000000 Z
+date: 2015-10-23 00:00:00.000000000 Z
 dependencies: []
 description: A library for viewing and manipulating Mach-O files in Ruby.
 email: william@tuffbizz.com