dwarves 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2366429fa46c2b680724383a3feacd28b1c242f39784ea1fd2e8c19ccddec915
-  data.tar.gz: e323ad5108096a98bb7ea077a06b01adc1dad48f1633572e5332e72a29f1563b
+  metadata.gz: 79492a5fd9500086eba68e2fe04ef72105f9e8cf72132cde00ce2cda180b30b5
+  data.tar.gz: 2bb7c214096e59f0cd83aecd0bca48b75970233b1691186bc4e5a1ebba378deb
 SHA512:
-  metadata.gz: 86f2e24147ebc367a44ce84713fa60c11f42ac8212f6f446efbe0b98b63a1a0e43d456745b5228bc75525c51b47b9648c3235ebd4dbd37b7aa94e19b6b82c0b9
-  data.tar.gz: fc49913262a9fc29b4521ee494c04fc9930d12e5b3707499d39140153476345359fbd247e7809e5af6778d071cb88e50f9264a9bc0af74ac3d608d41e8abd660
+  metadata.gz: 719c2e7c990ae149e8e945060dbd46f4440d917043b884b1b5818eee5b6d8a448fddd34f2922c0235d008d1a514cbaf35e53d013eec33b4ce01167eeaf25b3e5
+  data.tar.gz: e89dcc65262224f4b6cc3116bbe76d66c24bd08ddb4350262f104d9c3614381f39d6a3d82c126866f9ec0e66fc9c3c935f420377f4b50c7ccfbbeffa297eb481

data/.rubocop.yml

@@ -7,6 +7,10 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/dwarves/parser/**/*_spec.rb'
 
+Metrics/LineLength:
+  Exclude:
+    - 'spec/dwarves/parser/**/*_spec.rb'
+
 Metrics/AbcSize:
   Exclude:
     - 'lib/dwarves/parser/*.rb'

data/README.md

@@ -12,8 +12,16 @@ Source code is avaiable under MIT license at https://github.com/jethrodaniel/dwa
 
 ## What it do
 
+Parses DWARF format, as outputed by the following:
+
+- `readelf --debug-dump=info`
+- `objdump --dwarf=info`
+
 ```
-λ readelf --debug-dump=info spec/fixtures/c/build/example.so | dwarves | head -n 15
+λ ./bin/setup
+...
+λ readelf --debug-dump=info spec/fixtures/c/build/example.so > spec/fixtures/out.dwarves
+λ dwarves -T < spec/fixtures/out.dwarves | head
 
 {
   :compilation_unit_offset => "0x0"@66,
@@ -24,14 +32,28 @@ Source code is avaiable under MIT license at https://github.com/jethrodaniel/dwa
              :pointer_size => "8"@164,
                      :dies => [
     {
-         :nesting_level => "0"@168,
-               :address => "b"@171,
-      :dw_tag_base_type => "1"@190,
-                  :type => "DW_TAG_compile_unit"@193,
-            :attributes => [
+              :depth => "0"@168,
+...
+λ dwarves < spec/fixtures/out.dwarves | head
+
+Contents of the .debug_info section:
+
+  Compilation Unit @ offset 0x0:
+   Length:        0x112 (32-bit)
+   Version:       4
+   Abbrev Offset: 0x0
+   Pointer Size:  8
+ <0><b>: Abbrev Number: 1 (DW_TAG_compile_unit)
+    <c>   DW_AT_producer    : (indirect string, offset: 0x91): GNU C11 7.4.0 -mtune=generic -march=x86-64 -g -fPIC -fstack-protector-strong
+    <10>   DW_AT_language    : 12	(ANSI C99)
 ...
 ```
 
+## Future
+
+- more than just `.debug_info` section
+- parse object files with [rbelftools][2]
+
 ## Installation
 
 ```
@@ -51,10 +73,17 @@ rake doc              # Generates documentation
 rake install          # Build and install dwarves-0.1.0.gem into system gems
 rake install:local    # Build and install dwarves-0.1.0.gem into system gems without network access
 rake lint             # Runs the linter
-rake release[remote]  # Create tag v0.1.0 and build and push dwarves-0.1.0.gem to TODO: Set to 'https://rubygems.org'
+rake release[remote]  # Create tag v0.1.0 and build and push dwarves-0.1.0.gem to 'https://rubygems.org'
 rake test             # Run tests
 ```
 
+A good test for the parser is to parse its own input, since we reconstruct the
+output when printing.
+
+```
+./bin/readelf | bundle exec ./exe/dwarves | bundle exec ./exe/dwarves
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/jethrodaniel/dwarves.
@@ -71,3 +100,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 - http://dwarfstd.org/doc/DWARF5.pdf
 
 [1]: https://github.com/kschiess/parslet
+[2]: https://github.com/david942j/rbelftools

data/bin/readelf

@@ -2,4 +2,4 @@
 
 set -x
 
-readelf --debug-dump=info "$1"
+readelf --debug-dump=info spec/fixtures/c/build/example.so

data/dwarves.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["jethrodaniel@gmail.com"]
 
   spec.summary       = <<~MSG
-    DWARF parser (only the `.debug_info` section for now).
+    DWARF parser (only the .debug_info section for now).
   MSG
   spec.homepage      = "https://github.com/jethrodaniel/dwarves"
   spec.license       = "MIT"

data/exe/dwarves

@@ -8,13 +8,15 @@ require "awesome_print"
 require_relative "../lib/dwarves"
 
 options = {
-  json: false,
-  transform: false
+  transform: true
 }
 
 OptionParser.new do |opts|
+  # @todo support filenames instead of just stdin
   opts.banner = <<~MSG
     Usage: dwarves [options]... [file]...
+
+    Works the same as `readelf --debug-dump=info`
   MSG
 
   opts.on "-h", "--help", "print this help" do
@@ -27,20 +29,18 @@ OptionParser.new do |opts|
     exit
   end
 
-  opts.on "-j", "--json", "output results in JSON" do
-    options[:transform] = true
-    options[:json] = true
-  end
-
-  opts.on "-t", "--transform", "transform the parser output" do
-    options[:transform] = true
+  opts.on "-T", "--no-transform", "don't transform the parser output" do
+    options[:transform] = false
   end
 end.parse!
 
 begin
   tree = Dwarves::Parser[4].new.parse ARGF.read
 
-  tree = Dwarves::Parser[4].new.apply tree if options[:transform]
+  if options[:transform]
+    puts Dwarves::Parser[4].new.apply(tree)
+    exit
+  end
 
   ap tree, indent: 2, index: false
 rescue Parslet::ParseFailed => e

data/lib/dwarves/parser/4/ast.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Dwarves
+  module Parser
+    class AST; end
+
+    # The basic DWARF descriptive unit, the Debugging Information Entry (DIE).
+    #
+    # This is a node in the parse tree that DWARF generates.
+    #
+    # These represent types, variables, and functions.
+    #
+    class DIE < AST
+      attr_reader *%i[
+        tag
+        children
+        siblings
+        attributes
+        address
+        depth
+      ]
+
+      def initialize opts = {}
+        @tag = opts[:tag]
+        @children = opts[:children] || []
+        @siblings = opts[:siblings] || []
+        @attributes = opts[:attributes] || []
+        @address = opts[:address]
+        @depth = opts[:depth]
+        @abbrev_number = opts[:abbrev_number]
+      end
+
+      def to_s
+        attrs = if @attributes.empty?
+                  ""
+                else
+                  %(\n#{@attributes.map(&:to_s).join("\n")})
+                end
+        depth_addr =
+          "<#{@depth}><#{@address}>: Abbrev Number: #{@abbrev_number}"
+
+        if @tag
+          " #{depth_addr} (#{@tag})#{attrs}"
+        else
+          " #{depth_addr}#{attrs}"
+        end
+      end
+    end
+
+    # Compilation Unit
+    #
+    # @todo clean this up
+    class CU < AST
+      attr_reader *%i[
+        compilation_unit_offset
+        length
+        architecture
+        version
+        abbrev_offset
+        pointer_size
+        dies
+      ]
+
+      def initialize opts = {}
+        @compilation_unit_offset = opts[:compilation_unit_offset]
+        @length = opts[:length]
+        @architecture = opts[:architecture]
+        @version = opts[:version]
+        @abbrev_offset = opts[:abbrev_offset]
+        @pointer_size = opts[:pointer_size]
+        @dies = opts[:dies] || []
+      end
+
+      def to_s
+        "Contents of the .debug_info section:\n" \
+        "\n" \
+        "  Compilation Unit @ offset #{@compilation_unit_offset}:\n" \
+        "   Length:        #{@length} (#{@architecture})\n" \
+        "   Version:       #{@version}\n" \
+        "   Abbrev Offset: #{@abbrev_offset}\n" \
+        "   Pointer Size:  #{@pointer_size}\n" \
+        "#{@dies.map(&:to_s).join("\n")}\n\n"
+      end
+    end
+
+    class Attribute < AST
+      attr_reader :name, :value, :address
+
+      def initialize opts = {}
+        @name = opts[:name]
+        @value = opts[:value]
+        @address = opts[:address]
+      end
+
+      def to_s
+        formatted_address = "<#{@address}>".ljust(3, " ")
+        formatted_name = name.to_s.ljust(18, " ") + ":"
+        "    #{formatted_address}   #{formatted_name} #{@value}"
+      end
+    end
+  end
+end

data/lib/dwarves/parser/4/parser.rb

@@ -103,13 +103,13 @@ module Dwarves
       rule :die_header do
         _ >>
           str("<") >>
-          integer.as(:nesting_level) >>
+          integer.as(:depth) >>
           str(">") >>
           str("<") >>
           word.as(:address) >>
           str(">") >>
           str(": Abbrev Number: ") >>
-          integer.as(:dw_tag_base_type) >>
+          integer.as(:abbrev_number) >>
           (
             _ >>
             str("(") >>
@@ -122,7 +122,7 @@ module Dwarves
       # @!method die_body
       #
       # @example
-      #   <1><2d>: Abbrev Number: 2 (DW_TAG_base_type)
+      #   <1><2d>: Abbrev Number: 2 (abbrev_number)
       #      <2e>   DW_AT_byte_size   : 4
       #      <2f>   DW_AT_encoding    : 5  (signed)
       #      <30>   DW_AT_name        : int
@@ -137,7 +137,7 @@ module Dwarves
       rule :attribute do
         _ >>
           str("<") >>
-          word.as(:order) >>
+          word.as(:address) >>
           str(">") >>
           _ >>
           word.as(:name) >>

data/lib/dwarves/parser/4/transformer.rb

@@ -2,11 +2,65 @@
 
 require "parslet"
 
+require "dwarves/parser/4/ast"
+
 module Dwarves
   module Parser
     # Transformer to turn the parser output into meaningful classes
     #
     class V4Transformer < Parslet::Transform
+      rule(
+        compilation_unit_offset: simple(:c),
+        length: simple(:l),
+        architecture: simple(:arch),
+        version: simple(:v),
+        abbrev_offset: simple(:ab),
+        pointer_size: simple(:p),
+        dies: subtree(:d)
+      ) do
+        Dwarves::Parser::CU.new \
+          compilation_unit_offset: c,
+          length: l,
+          architecture: arch,
+          version: v,
+          abbrev_offset: ab,
+          pointer_size: p,
+          dies: d
+      end
+
+      rule(
+        depth: simple(:d),
+        address: simple(:a),
+        abbrev_number: simple(:an),
+        attributes: subtree(:attrs)
+      ) do
+        Dwarves::Parser::DIE.new \
+          attributes: attrs,
+          address: a,
+          abbrev_number: an,
+          depth: d
+      end
+
+      rule(
+        depth: simple(:d),
+        address: simple(:a),
+        abbrev_number: simple(:an),
+        type: simple(:t),
+        attributes: subtree(:attrs)
+      ) do
+        Dwarves::Parser::DIE.new \
+          tag: t,
+          children: [],
+          siblings: [],
+          attributes: attrs,
+          address: a,
+          abbrev_number: an,
+          depth: d
+      end
+
+      rule address: simple(:a), name: simple(:n), description: simple(:d) do
+        Dwarves::Parser::Attribute.new name: n, value: d, address: a
+      end
     end
   end
 end

data/lib/dwarves/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dwarves
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dwarves
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mark Delk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-10 00:00:00.000000000 Z
+date: 2019-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -176,6 +176,7 @@ files:
 - lib/dwarves.rb
 - lib/dwarves/parser.rb
 - lib/dwarves/parser/4.rb
+- lib/dwarves/parser/4/ast.rb
 - lib/dwarves/parser/4/parser.rb
 - lib/dwarves/parser/4/transformer.rb
 - lib/dwarves/parser/basic_rules.rb
@@ -206,5 +207,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: DWARF parser (only the `.debug_info` section for now).
+summary: DWARF parser (only the .debug_info section for now).
 test_files: []