ruby-macho

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

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.

ruby-macho can be installed via RubyGems:

$ gem install ruby-macho

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"

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")

• 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.

• Unit and performance testing.

In order to keep the repo, docs and data tidy, we use a tool called overcommit to connect up the git hooks to a set of quality checks. The fastest way to get setup is to run the following to make sure you have all the tools:

gem install overcommit bundler
bundle install
overcommit --install

• 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).

ruby-macho is licensed under the MIT License.

For the exact terms, see the license file.