README.md

   1 ruby-macho
   2 ================
   3
   4 [![Gem Version](https://badge.fury.io/rb/ruby-macho.svg)](http://badge.fury.io/rb/ruby-macho)
   5 [![CI](https://github.com/Homebrew/ruby-macho/actions/workflows/tests.yml/badge.svg)](https://github.com/Homebrew/ruby-macho/actions/workflows/tests.yml)
   6 [![Coverage Status](https://codecov.io/gh/Homebrew/ruby-macho/branch/master/graph/badge.svg)](https://codecov.io/gh/Homebrew/ruby-macho)
   7
   8 A Ruby library for examining and modifying Mach-O files.
   9
  10 ### What is a Mach-O file?
  11
  12 The [Mach-O file format](https://en.wikipedia.org/wiki/Mach-O) is used by macOS
  13 and iOS (among others) as a general purpose binary format for object files,
  14 executables, dynamic libraries, and so forth.
  15
  16 ### Installation
  17
  18 ruby-macho can be installed via RubyGems:
  19
  20 ```bash
  21 $ gem install ruby-macho
  22 ```
  23
  24 ### Documentation
  25
  26 Full documentation is available on [RubyDoc](http://www.rubydoc.info/gems/ruby-macho/).
  27
  28 A quick example of what ruby-macho can do:
  29
  30 ```ruby
  31 require 'macho'
  32
  33 file = MachO::MachOFile.new("/path/to/my/binary")
  34
  35 # get the file's type (object, dynamic lib, executable, etc)
  36 file.filetype # => :execute
  37
  38 # get all load commands in the file and print their offsets:
  39 file.load_commands.each do |lc|
  40   puts "#{lc.type}: offset #{lc.offset}, size: #{lc.cmdsize}"
  41 end
  42
  43 # access a specific load command
  44 lc_vers = file[:LC_VERSION_MIN_MACOSX].first
  45 puts lc_vers.version_string # => "10.10.0"
  46 ```
  47
  48 ### What works?
  49
  50 * Reading data from x86/x86_64/PPC Mach-O files
  51 * Changing the IDs of Mach-O and Fat dylibs
  52 * Changing install names in Mach-O and Fat files
  53 * Adding, deleting, and modifying rpaths.
  54
  55 ### What needs to be done?
  56
  57 * Unit and performance testing.
  58
  59 ### Contributing, setting up `overcommit` and the linters
  60
  61 In order to keep the repo, docs and data tidy, we use a tool called [`overcommit`](https://github.com/sds/overcommit)
  62 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
  63 sure you have all the tools:
  64
  65 ```shell
  66 gem install overcommit bundler
  67 bundle install
  68 overcommit --install
  69 ```
  70
  71 ### Attribution
  72
  73 * Constants were taken from Apple, Inc's
  74 [`loader.h` in `cctools/include/mach-o`](https://opensource.apple.com/source/cctools/cctools-973.0.1/include/mach-o/loader.h.auto.html).
  75 (Apple Public Source License 2.0).
  76 * Binary files used for testing were taken from The LLVM Project. ([Apache License v2.0 with LLVM Exceptions](test/bin/llvm/LICENSE.txt)).
  77
  78 ### License
  79
  80 `ruby-macho` is licensed under the MIT License.
  81
  82 For the exact terms, see the [license](LICENSE) file.