07ca7378c913385084729175f7afbda004ffab2c
[elfdbg/.git] / README.md
1 # elfdbg
2
3 [![Build Status](https://api.cirrus-ci.com/github/sbz/elfdbg.svg)](https://cirrus-ci.com/github/sbz/elfdbg)
4
5 ## About
6
7 This project _elfdbg_ is a utility program to quickly identify if an ELF binary
8 is built with [debug sections](https://en.wikipedia.org/wiki/Debug_symbol)
9
10 Debug sections in ELF binary usually are generated using the `-g` flag with the
11 compiler. The compiler adds the new `.debug_*` sections in the binary.
12
13 The program is looking for the existence of sections with name starting with
14 `.debug_` to determine if the binary has been built with debug information.
15
16 The [ELF][ELF] format is a well-known standard. ELF TIS reference specification
17 is available [here][spec] and as a FreeBSD [elf(5)][man] man page.
18
19 ## Usage
20
21 This is intented to be used in shell script in order to avoid using file(1) and
22 parsing the output like below:
23
24 ```shell
25 `file /path/to/binary | awk '/debug_info/{print $2}'` != 'ELF'
26 ```
27
28 To determine if binary has been built with debug, use the following:
29
30 ```shell
31 if elfdbg -q /path/to/binary; then
32         echo "No symbols"
33     else
34         echo "Binary with debug symbols"
35 fi
36 ```
37
38 On FreeBSD, you can easily identify the binary packages with missing debug
39 using similar one-liner:
40
41 ```shell
42 pkg info -a -l|grep local/bin/|while read a; do echo $a: `elfdbg $a`; done
43 ```
44
45 ## Build and install
46
47 The Makefile use the standard BSD Makefile to build the program.
48
49 ```
50 make && sudo make install
51 ```
52
53 If your on Linux, use `make -f GNUMakefile` to specify the GNU Makefile.
54
55 ## Test
56
57 The tests cases are implemented using the FreeBSD test suite framework with
58 [kyua](https://github.com/jmmv/kyua) and [Kyuafile](./tests/Kyuafile).
59
60 ```
61 make test
62 ```
63
64 ## History
65
66 * _2015_ I wrote this using libelf elf(3) and gelf(3) API
67   [f4b470b](https://github.com/sbz/elfdbg/commit/f4b470b)
68 * _2020_ I rewrote this without relying on libelf API
69   [1960d10](https://github.com/sbz/elfdbg/commit/1960d10)
70
71 [ELF]: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format
72 [spec]: http://refspecs.linuxbase.org/elf/elf.pdf
73 [man]: https://www.freebsd.org/cgi/man.cgi?query=elf&sektion=5