ruby-macho

A Ruby library for examining and modifying Mach-O files.

What is a Mach-O file?

The Mach-O file format is used by macOS and iOS (among others) as a general purpose binary format for object files, executables, dynamic libraries, and so forth.

Installation

ruby-macho can be installed via RubyGems:

$ gem install ruby-macho

Documentation

Full documentation is available on RubyDoc.

A quick example of what ruby-macho can do:

require 'macho'

file = MachO::MachOFile.new("/path/to/my/binary")

# 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|
  puts "#{lc.type}: offset #{lc.offset}, size: #{lc.cmdsize}"
end

# access a specific load command
lc_vers = file[:LC_VERSION_MIN_MACOSX].first
puts lc_vers.version_string # => "10.10.0"

Ad-hoc code signing

Changing a Mach-O load command invalidates any existing code signature. This is especially important when Homebrew pours bottles on Apple Silicon, where native code must remain signed after its paths are rewritten. MachO.codesign! creates the required ad-hoc signature in Ruby instead of invoking /usr/bin/codesign:

MachO.codesign!("/path/to/my/binary")

What works?

• Reading data from x86/x86_64/arm64/PPC Mach-O files (other architectures are unsupported, but may work)
• Changing the IDs of Mach-O and Fat dylibs
• Changing install names in Mach-O and Fat files
• Adding, deleting, and modifying rpaths.
• Parsing embedded code signatures and applying ad-hoc signatures in pure Ruby.

Contributing

See CONTRIBUTING.md for repository setup, checks, fixture guidance, and the contribution process.

Attribution

• Constants were taken from Apple, Inc's loader.h in cctools/include/mach-o. (Apple Public Source License 2.0).
• Code-signing constants and structures follow Apple, Inc's cs_blobs.h in XNU.
• Binary files used for testing were taken from The LLVM Project. (Apache License v2.0 with LLVM Exceptions).

License

ruby-macho is licensed under the MIT License.

For the exact terms, see the license file.