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