TESTING.md (4545B)
1 # Testing 2 This file holds notes for testing purposes. 3 4 ## Compile with Debug Symbols 5 To make a build with debug symbols (for example, required to run 6 [Valgrind](#valgrind) below) use the `debug` target: 7 ```bash 8 make debug 9 ``` 10 11 ## Valgrind 12 Use Valgrind on a build with debug symbols to discover memory issues: 13 ```bash 14 mkdir -p tmp-journal 15 make debug 16 valgrind --leak-check=full ./diary tmp-journal/ 2>log.txt 17 ``` 18 19 https://developers.redhat.com/blog/2021/04/23/valgrind-memcheck-different-ways-to-lose-your-memory#generating_a_leak_summary 20 21 Don't use `--show-leak-kinds=all` with Ncurses: 22 https://invisible-island.net/ncurses/ncurses.faq.html#config_leaks 23 24 ## Compile with Clang Compiler 25 As pointed out in [#82](https://github.com/in0rdr/diary/issues/82) the clang 26 compiler is a lot more useful when it comes to debugging. 27 28 To compile the program with clang: 29 ``` 30 make CC=clang 31 ``` 32 33 ## Linux Trace Toolkit (LTTng) 34 > :information_source: For rapid debugging, use an LTTng live session, see 35 > [LTTng Live Tracing](#lttng-live-tracing). This section is especially useful 36 > for exporting the traces (in plain text) from a failed instance for support 37 > (e.g., attach to issue). 38 39 Logs from the debug build can be recorded in a [LTTng tracing 40 session](https://lttng.org/docs/v2.13/#doc-start-sessiond). 41 42 Start the daemon in the background: 43 ``` 44 lttng-sessiond -b 45 ``` 46 47 To start a new session use: 48 ```bash 49 lttng create 50 ``` 51 52 Create channel to capture the traces. The recording event rule below matches 53 all user space tracepoint events of which the name starts with `diary:*`: 54 ```bash 55 lttng enable-event --userspace 'diary:*' 56 ``` 57 58 To only show traces at least as severe as `--loglevel` or for a specific log 59 level only: 60 ```bash 61 lttng enable-event --userspace 'diary:*' --loglevel=WARNING 62 lttng enable-event --userspace 'diary:*' --loglevel-only=INFO 63 ``` 64 65 Build the debug diary with the [tracepoint provider package (tpp) shared 66 object](https://lttng.org/docs/v2.13/#doc-building-tracepoint-providers-and-user-application): 67 ```bash 68 make debug 69 ... 70 gcc -I src/ -fpic -c src/diary-tp.c 71 gcc -shared -o libtpp.so diary-tp.o -llttng-ust -ldl 72 ``` 73 74 Start recording session: 75 ```bash 76 lttng start 77 ``` 78 79 Preload the tpp shared object and start diary: 80 ```bash 81 LD_PRELOAD=./libtpp.so ./diary 82 ``` 83 84 Stop the session and observe traces: 85 ```bash 86 lttng stop # stop session 87 lttng view # observe traces 88 lttng clear # if needed, clear traces 89 ``` 90 91 Cleanup the session daemon once done: 92 ```bash 93 killall lttng-sessiond 94 ``` 95 96 An example (script) for viewing the traces is also given in 97 [./trace.sh](./trace.sh). 98 99 ## LTTng Live Tracing 100 [Live tracing](https://lttng.org/docs/v2.13/#doc-lttng-live) is more convenient 101 for rapid debugging. 102 103 There is no need to stop the sessions to observe the logs. 104 105 The setup is similar to the generic instructions above, but the session is 106 created with the `--live` flave. 107 108 ```bash 109 lttng-sessiond -b 110 lttng create --live 111 lttng enable-event --userspace 'diary:*' 112 lttng start 113 ``` 114 115 Then start the diary with the shared object file in a new terminal to view the 116 logs: 117 ```bash 118 LD_PRELOAD=./libtpp.so ./diary 119 ``` 120 121 ## Send stderr to File 122 > :information_source: For proper tracing and logging, start diary with the 123 > LTTng tracepoint provider package (tpp) shared object file, see 124 > [LTTng](#linux-trace-toolkit-lttng). 125 126 Send stderr to a file for debugging: 127 ```bash 128 diary 2>log.txt 129 ``` 130 131 Or to `/dev/null` to ignore the debug messages flickering on the screen: 132 ```bash 133 diary 2>/dev/null 134 ``` 135 136 ## Render Documentation / Man Page 137 ### Generate Runoff 138 Install [scdoc](https://git.sr.ht/~sircmpwn/scdoc). 139 140 Generate the "runoff" text with `scdoc` from the Markdown like `.scd` file: 141 ```bash 142 SOURCE_DATE_EPOCH=$(date +%s) scdoc < diary.1.scd > diary.1 143 ``` 144 145 ### View Manpage in Terminal 146 Generate plain text from "runoff" text: 147 ```bash 148 tbl diary.1 | nroff -man | less 149 ``` 150 151 ### `mandoc` HTML (Preferred) 152 Install [`mandoc`](https://en.wikipedia.org/wiki/Mandoc) >= [1.14.6 (helps to 153 format paragraphs with CSS)](https://mandoc.bsd.lv/NEWS): 154 ```bash 155 curl -sO https://mandoc.bsd.lv/snapshots/mandoc-1.14.6.tar.gz 156 tar -xf mandoc-1.14.6.tar.gz 157 cd mandoc-1.14.6 158 ./configure 159 make 160 ``` 161 162 Generate HTML page from runoff: 163 ```bash 164 ../../mandoc-1.14.6/mandoc -Thtml -O style=style.css diary.1 > diary.1.html 165 ``` 166 167 ### `groff` HTML (Alternative) 168 Limitation: `groff` produces unstyled output (no CSS). 169 170 Install [`groff`](https://www.gnu.org/software/groff): 171 ```bash 172 sudo apt-get install groff 173 ``` 174 175 Generate HTML file (`-t` for `tbl`): 176 ```bash 177 groff -t -mandoc -Thtml diary.1 > diary.1.html 178 ```