README.md
1# libgoblin [![Build status][travis-badge]][travis-url] [![crates.io version][crates-goblin-badge]][crates-goblin]
2
3<!-- Badges' links -->
4
5[travis-badge]: https://travis-ci.org/m4b/goblin.svg?branch=master
6[travis-url]: https://travis-ci.org/m4b/goblin
7[crates-goblin-badge]: https://img.shields.io/crates/v/goblin.svg
8[crates-goblin]: https://crates.io/crates/goblin
9
10
11
12### Documentation
13
14https://docs.rs/goblin/
15
16[changelog](CHANGELOG.md)
17
18### Usage
19
20Goblin requires `rustc` 1.36.0.
21
22Add to your `Cargo.toml`
23
24```toml
25[dependencies]
26goblin = "0.1"
27```
28
29### Features
30
31* awesome crate name
32* zero-copy, cross-platform, endian-aware, ELF64/32 implementation - wow!
33* zero-copy, cross-platform, endian-aware, 32/64 bit Mach-o parser - zoiks!
34* PE 32/64-bit parser - bing!
35* a Unix _and_ BSD style archive parser (latter courtesy of [@willglynn]) - huzzah!
36* many cfg options - it will make your head spin, and make you angry when reading the source!
37* fuzzed - "I am happy to report that goblin withstood 100 million fuzzing runs, 1 million runs
38 each for seed 1\~100." - [@sanxiyn]
39* tests
40
41`libgoblin` aims to be your one-stop shop for binary parsing, loading, and analysis.
42
43### Use-cases
44
45Goblin primarily supports the following important use cases:
46
471. Core, std-free `#[repr(C)]` structs, tiny compile time, 32/64 (or both) at your leisure.
48
491. Type punning. Define a function once on a type, but have it work on 32 or 64-bit variants -
50 without really changing anything, and no macros! See `examples/automagic.rs` for a basic example.
51
521. `std` mode. This throws in read and write impls via `Pread` and `Pwrite`, reading from file,
53 convenience allocations, extra methods, etc. This is for clients who can allocate and want to
54 read binaries off disk.
55
561. `Endian_fd`. A truly terrible name :laughing: this is for binary analysis like in [panopticon]
57 or [falcon] which needs to read binaries of foreign endianness, _or_ as a basis for
58 constructing cross platform foreign architecture binutils, e.g. [cargo-sym] and [bingrep] are
59 simple examples of this, but the sky is the limit.
60
61Here are some things you could do with this crate (or help to implement so they could be done):
62
631. Write a compiler and use it to [generate binaries][faerie] (all the raw C structs have
64 [`Pwrite`][scroll] derived).
651. Write a binary analysis tool which loads, parses, and analyzes various binary formats, e.g.,
66 [panopticon] or [falcon].
671. Write a [semi-functioning dynamic linker][dryad].
681. Write a [kernel][redox-os] and load binaries using `no_std` cfg. I.e., it is essentially just
69 struct and const defs (like a C header) - no fd, no output, no std.
701. Write a [bin2json] tool, because why shouldn't binary formats be in JSON?
71
72<!-- Related projects -->
73
74[cargo-sym]: https://github.com/m4b/cargo-sym
75[bingrep]: https://github.com/m4b/bingrep
76[faerie]: https://github.com/m4b/faerie
77[dryad]: https://github.com/m4b/dryad
78[scroll]: https://github.com/m4b/scroll
79[redox-os]: https://github.com/redox-os/redox
80[bin2json]: https://github.com/m4b/bin2json
81[panopticon]: https://github.com/das-labor/panopticon
82[falcon]: https://github.com/endeav0r/falcon
83
84### Cfgs
85
86`libgoblin` is designed to be massively configurable. The current flags are:
87
88* elf64 - 64-bit elf binaries, `repr(C)` struct defs
89* elf32 - 32-bit elf binaries, `repr(C)` struct defs
90* mach64 - 64-bit mach-o `repr(C)` struct defs
91* mach32 - 32-bit mach-o `repr(C)` struct defs
92* pe32 - 32-bit PE `repr(C)` struct defs
93* pe64 - 64-bit PE `repr(C)` struct defs
94* archive - a Unix Archive parser
95* endian_fd - parses according to the endianness in the binary
96* std - to allow `no_std` environments
97
98# Contributors
99
100Thank you all :heart: !
101
102In lexicographic order:
103
104- [@amanieu]
105- [@burjui]
106- [@flanfly]
107- [@ibabushkin]
108- [@jan-auer]
109- [@jdub]
110- [@jrmuizel]
111- [@jsgf]
112- [@kjempelodott]
113- [@le-jzr]
114- [@lion128]
115- [@llogiq]
116- [@lzutao]
117- [@lzybkr]
118- [@m4b]
119- [@mitsuhiko]
120- [@mre]
121- [@pchickey]
122- [@philipc]
123- [@Pzixel]
124- [@raindev]
125- [@rocallahan]
126- [@sanxiyn]
127- [@tathanhdinh]
128- [@Techno-coder]
129- [@ticki]
130- [@wickerwacka]
131- [@willglynn]
132- [@wyxloading]
133- [@xcoldhandsx]
134
135<!-- Contributors -->
136
137[@amanieu]: https://github.com/amanieu
138[@burjui]: https://github.com/burjui
139[@flanfly]: https://github.com/flanfly
140[@ibabushkin]: https://github.com/ibabushkin
141[@jan-auer]: https://github.com/jan-auer
142[@jdub]: https://github.com/jdub
143[@jrmuizel]: https://github.com/jrmuizel
144[@jsgf]: https://github.com/jsgf
145[@kjempelodott]: https://github.com/kjempelodott
146[@le-jzr]: https://github.com/le-jzr
147[@lion128]: https://github.com/lion128
148[@llogiq]: https://github.com/llogiq
149[@lzutao]: https://github.com/lzutao
150[@lzybkr]: https://github.com/lzybkr
151[@m4b]: https://github.com/m4b
152[@mitsuhiko]: https://github.com/mitsuhiko
153[@mre]: https://github.com/mre
154[@pchickey]: https://github.com/pchickey
155[@philipc]: https://github.com/philipc
156[@Pzixel]: https://github.com/Pzixel
157[@raindev]: https://github.com/raindev
158[@rocallahan]: https://github.com/rocallahan
159[@sanxiyn]: https://github.com/sanxiyn
160[@tathanhdinh]: https://github.com/tathanhdinh
161[@Techno-coder]: https://github.com/Techno-coder
162[@ticki]: https://github.com/ticki
163[@wickerwacka]: https://github.com/wickerwaka
164[@willglynn]: https://github.com/willglynn
165[@wyxloading]: https://github.com/wyxloading
166[@xcoldhandsx]: https://github.com/xcoldhandsx
167
168## Contributing
169
1701. Please prefix commits with the affected binary component; the more specific the better, e.g.,
171 if you only modify relocations in the elf module, then do "elf.reloc: added new constants for Z80"
1721. Commit messages must explain their change, no generic "changed", or "fix"; if you push commits
173 like this on a PR, be aware [@m4b] or someone will most likely squash them.
1741. If you are making a large change to a module, please raise an issue first and lets discuss;
175 I don't want to waste your time if its not a good technical direction, or etc.
1761. If your PR is not getting attention, please respond to all relevant comments raised on the PR,
177 and if still no response, ping [@m4b], [@philipc], or [@willglynn] in github and also feel free
178 to email [@m4b].
1791. Please add tests if you are adding a new feature. Feel free to add tests even if you are not,
180 tests are awesome and easy in rust.
1811. Once cargo format is officially released, please format your _patch_ using the default settings.
182
){kind=link}