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