Fossil SCM
Update the fuzz-testing documentation.
Commit
16d98b94bb58555bee7949f653dde63347c5ac9fb9fcf2efe3aa269a5ea64dd3
Parent
8ccedde4c6b4bdd…
1 file changed
+7
-19
+7
-19
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -340,48 +340,36 @@ | ||
| 340 | 340 | found in the help text for the [/help?cmd=test-fuzz|test-fuzz |
| 341 | 341 | command]. |
| 342 | 342 | |
| 343 | 343 | Fuzzing requires: |
| 344 | 344 | |
| 345 | - * Customizing the build of fossil a small bit. | |
| 346 | 345 | * The clang C compiler. |
| 347 | 346 | * libfuzzer. On Ubuntu-derived systems, it can be installed with |
| 348 | 347 | <tt>apt install libfuzzer-XYZ</tt>, where XYZ is a version number |
| 349 | 348 | (several versions may be available on any given system) |
| 350 | 349 | |
| 351 | 350 | |
| 352 | -First, modify the top-level <tt>Makefile.in</tt>: | |
| 353 | - | |
| 354 | - * Extend the <tt>TCCFLAGS</tt> variable with: <tt>-fsanitize=fuzzer | |
| 355 | - -DFOSSIL_FUZZ</tt> (and see [/finfo/src/fuzz.c | src/fuzz.c] for | |
| 356 | - more options). | |
| 357 | - * Rename <tt>APPNAME</tt> from <tt>fossil</tt> to <tt>fossil-fuzz</tt>. | |
| 358 | - | |
| 359 | -Then rebuild: | |
| 360 | - | |
| 361 | -<pre></code>$ make clean | |
| 362 | -$ ./configure CC=/path/to/clang | |
| 363 | -$ make | |
| 351 | +Compile as follows: | |
| 352 | + | |
| 353 | +<pre><code>make clean | |
| 354 | +make TCCFLAGS='-DFOSSIL_FUZZ -fsanitize=fuzzer,address,undefined -O0 -g' CC=clang | |
| 364 | 355 | </code></pre> |
| 365 | 356 | |
| 366 | -If clang is your default compiler, the <tt>CC</tt> configure option is | |
| 367 | -not required. | |
| 368 | - | |
| 369 | -The resulting <tt>fossil-fuzz</tt> binary differs from the standard | |
| 357 | +The resulting <tt>fossil</tt> binary differs from the standard | |
| 370 | 358 | one primarily in that it runs the <tt>test-fuzz</tt> command by |
| 371 | 359 | default. It needs to be told what to fuzz and needs to be given a |
| 372 | 360 | directory of input files to seed the fuzzer with: |
| 373 | 361 | |
| 374 | 362 | |
| 375 | -<pre></code>$ mkdir cases | |
| 363 | +<pre><code>$ mkdir cases | |
| 376 | 364 | # Copy input files into ./cases. e.g. when fuzzing the markdown |
| 377 | 365 | # processor, copy any to-be-tested .md files into that directory. |
| 378 | 366 | # Then start the fuzzer: |
| 379 | 367 | $ ./fossil-fuzz --fuzztype markdown cases |
| 380 | 368 | </code></pre> |
| 381 | 369 | |
| 382 | -As it works, it writes its mutated test files into the test-input | |
| 370 | +As it works, it writes its mutated test files into the "cases" | |
| 383 | 371 | directory, each one named in the form of a hash. When it finds a |
| 384 | 372 | problem it will produce a stack trace for the offending code, will |
| 385 | 373 | output the name of the file which triggered the crash (named |
| 386 | 374 | <tt>cases/SOME_HASH</tt>) and may, depending on the nature of the |
| 387 | 375 | problem, produce a file named <tt>crash-SOMETHING</tt>. In theory the |
| 388 | 376 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -340,48 +340,36 @@ | |
| 340 | found in the help text for the [/help?cmd=test-fuzz|test-fuzz |
| 341 | command]. |
| 342 | |
| 343 | Fuzzing requires: |
| 344 | |
| 345 | * Customizing the build of fossil a small bit. |
| 346 | * The clang C compiler. |
| 347 | * libfuzzer. On Ubuntu-derived systems, it can be installed with |
| 348 | <tt>apt install libfuzzer-XYZ</tt>, where XYZ is a version number |
| 349 | (several versions may be available on any given system) |
| 350 | |
| 351 | |
| 352 | First, modify the top-level <tt>Makefile.in</tt>: |
| 353 | |
| 354 | * Extend the <tt>TCCFLAGS</tt> variable with: <tt>-fsanitize=fuzzer |
| 355 | -DFOSSIL_FUZZ</tt> (and see [/finfo/src/fuzz.c | src/fuzz.c] for |
| 356 | more options). |
| 357 | * Rename <tt>APPNAME</tt> from <tt>fossil</tt> to <tt>fossil-fuzz</tt>. |
| 358 | |
| 359 | Then rebuild: |
| 360 | |
| 361 | <pre></code>$ make clean |
| 362 | $ ./configure CC=/path/to/clang |
| 363 | $ make |
| 364 | </code></pre> |
| 365 | |
| 366 | If clang is your default compiler, the <tt>CC</tt> configure option is |
| 367 | not required. |
| 368 | |
| 369 | The resulting <tt>fossil-fuzz</tt> binary differs from the standard |
| 370 | one primarily in that it runs the <tt>test-fuzz</tt> command by |
| 371 | default. It needs to be told what to fuzz and needs to be given a |
| 372 | directory of input files to seed the fuzzer with: |
| 373 | |
| 374 | |
| 375 | <pre></code>$ mkdir cases |
| 376 | # Copy input files into ./cases. e.g. when fuzzing the markdown |
| 377 | # processor, copy any to-be-tested .md files into that directory. |
| 378 | # Then start the fuzzer: |
| 379 | $ ./fossil-fuzz --fuzztype markdown cases |
| 380 | </code></pre> |
| 381 | |
| 382 | As it works, it writes its mutated test files into the test-input |
| 383 | directory, each one named in the form of a hash. When it finds a |
| 384 | problem it will produce a stack trace for the offending code, will |
| 385 | output the name of the file which triggered the crash (named |
| 386 | <tt>cases/SOME_HASH</tt>) and may, depending on the nature of the |
| 387 | problem, produce a file named <tt>crash-SOMETHING</tt>. In theory the |
| 388 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -340,48 +340,36 @@ | |
| 340 | found in the help text for the [/help?cmd=test-fuzz|test-fuzz |
| 341 | command]. |
| 342 | |
| 343 | Fuzzing requires: |
| 344 | |
| 345 | * The clang C compiler. |
| 346 | * libfuzzer. On Ubuntu-derived systems, it can be installed with |
| 347 | <tt>apt install libfuzzer-XYZ</tt>, where XYZ is a version number |
| 348 | (several versions may be available on any given system) |
| 349 | |
| 350 | |
| 351 | Compile as follows: |
| 352 | |
| 353 | <pre><code>make clean |
| 354 | make TCCFLAGS='-DFOSSIL_FUZZ -fsanitize=fuzzer,address,undefined -O0 -g' CC=clang |
| 355 | </code></pre> |
| 356 | |
| 357 | The resulting <tt>fossil</tt> binary differs from the standard |
| 358 | one primarily in that it runs the <tt>test-fuzz</tt> command by |
| 359 | default. It needs to be told what to fuzz and needs to be given a |
| 360 | directory of input files to seed the fuzzer with: |
| 361 | |
| 362 | |
| 363 | <pre><code>$ mkdir cases |
| 364 | # Copy input files into ./cases. e.g. when fuzzing the markdown |
| 365 | # processor, copy any to-be-tested .md files into that directory. |
| 366 | # Then start the fuzzer: |
| 367 | $ ./fossil-fuzz --fuzztype markdown cases |
| 368 | </code></pre> |
| 369 | |
| 370 | As it works, it writes its mutated test files into the "cases" |
| 371 | directory, each one named in the form of a hash. When it finds a |
| 372 | problem it will produce a stack trace for the offending code, will |
| 373 | output the name of the file which triggered the crash (named |
| 374 | <tt>cases/SOME_HASH</tt>) and may, depending on the nature of the |
| 375 | problem, produce a file named <tt>crash-SOMETHING</tt>. In theory the |
| 376 |