Fossil SCM
Added a section to build.wiki about building for fuzz testing.
Commit
a42f5af812aaabf73d65eb7b3e7b7fc6cc01bfbc3b1088b79322571712027e13
Parent
8d4c4792080ad0e…
1 file changed
+75
+75
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -379,5 +379,80 @@ | ||
| 379 | 379 | |
| 380 | 380 | The source of such warnings is not 100% certain. |
| 381 | 381 | Some information about these (reportedly harmless) warnings can |
| 382 | 382 | be found |
| 383 | 383 | [https://stackoverflow.com/a/41900551 | on this StackOverflow post]. |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | +<a id='fuzzer'></a> | |
| 388 | +<h2>Building for Fuzz Testing</h2> | |
| 389 | + | |
| 390 | +This feature is primarily intended for fossil's developers and may | |
| 391 | +change at any time. It is only known to work on x86/64 Linux systems. | |
| 392 | + | |
| 393 | +Fossil has builtin support for processing specific features using | |
| 394 | +<tt>libfuzzer</tt>. The specific features which can be tested this way | |
| 395 | +are found in the help text for the [/help?cmd=test-fuzz|test-fuzz | |
| 396 | +command]. | |
| 397 | + | |
| 398 | +Fuzzing requires: | |
| 399 | + | |
| 400 | + * Customizing the build of fossil a small bit. | |
| 401 | + * The clang compiler. | |
| 402 | + * libfuzzer. On Ubuntu-derived systems, it can be installed with | |
| 403 | + <tt>apt install libfuzzer-XYZ</tt>, where XYZ is a version number | |
| 404 | + (several versions may be available on any given system) | |
| 405 | + | |
| 406 | + | |
| 407 | +First, modify the top-level <tt>Makefile.in</tt>: | |
| 408 | + | |
| 409 | + * Extend the <tt>TCCFLAGS</tt> variable with: <tt>-fsanitize=fuzzer | |
| 410 | + -DFOSSIL_FUZZ</tt> (and see [/finfo/src/fuzz.c | src/fuzz.c] for | |
| 411 | + more options). | |
| 412 | + * Rename <tt>APPNAME</tt> from <tt>fossil</tt> to <tt>fossil-fuzz</tt>. | |
| 413 | + | |
| 414 | +Then rebuild: | |
| 415 | + | |
| 416 | +<pre></code>$ make clean | |
| 417 | +$ ./configure CC=/path/to/clang | |
| 418 | +$ make | |
| 419 | +</code></pre> | |
| 420 | + | |
| 421 | +If clang is your default compiler, the <tt>CC</tt> configure option is | |
| 422 | +not required. | |
| 423 | + | |
| 424 | +The resulting <tt>fossil-fuzz</tt> binary differs from the standard | |
| 425 | +one primarily in that it runs the <tt>test-fuzz</tt> command by | |
| 426 | +default. It needs to be told what to fuzz and needs to be given a | |
| 427 | +directory of input files to seed the fuzzer with: | |
| 428 | + | |
| 429 | + | |
| 430 | +<pre></code>$ mkdir cases | |
| 431 | + # Copy input files into ./cases. e.g. when fuzzing the markdown | |
| 432 | + # processor, copy any to-be-tested .md files into that directory. | |
| 433 | + # Then start the fuzzer: | |
| 434 | +$ ./fossil-fuzz --fuzztype markdown cases | |
| 435 | +</code></pre> | |
| 436 | + | |
| 437 | +As it works, it writes its test files into the test-input directory, | |
| 438 | +each one named in the form of a hash. When it finds a problem it will | |
| 439 | +produce a stack trace for the offending code, will output the | |
| 440 | +name of the file which triggered the crash (named | |
| 441 | +<tt>cases/SOME_HASH</tt>) and may, depending on the nature of the | |
| 442 | +problem, produce a file named <tt>crash-SOMETHING</tt>. In theory the | |
| 443 | +crash file can be fed directly back into the fuzzer to reproduce the | |
| 444 | +problem: | |
| 445 | + | |
| 446 | +<pre></code>$ ./fossil-fuzz --fuzztype markdown crash-SOMETHING | |
| 447 | +</code></pre> | |
| 448 | + | |
| 449 | +But whether or not it will genuinely crash may depend on static | |
| 450 | +app-level state which might not trigger the crash when running an | |
| 451 | +individual test. | |
| 452 | + | |
| 453 | +For a detailed tutorial of the fuzzer's flags and features, see: | |
| 454 | + | |
| 455 | + * [https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md] | |
| 456 | + | |
| 457 | +Flags for the fuzzer can be passed directly to fossil, e.g. <tt>-jobs=4</tt> | |
| 458 | +to start four fuzzer jobs in parallel. | |
| 384 | 459 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -379,5 +379,80 @@ | |
| 379 | |
| 380 | The source of such warnings is not 100% certain. |
| 381 | Some information about these (reportedly harmless) warnings can |
| 382 | be found |
| 383 | [https://stackoverflow.com/a/41900551 | on this StackOverflow post]. |
| 384 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -379,5 +379,80 @@ | |
| 379 | |
| 380 | The source of such warnings is not 100% certain. |
| 381 | Some information about these (reportedly harmless) warnings can |
| 382 | be found |
| 383 | [https://stackoverflow.com/a/41900551 | on this StackOverflow post]. |
| 384 | |
| 385 | |
| 386 | |
| 387 | <a id='fuzzer'></a> |
| 388 | <h2>Building for Fuzz Testing</h2> |
| 389 | |
| 390 | This feature is primarily intended for fossil's developers and may |
| 391 | change at any time. It is only known to work on x86/64 Linux systems. |
| 392 | |
| 393 | Fossil has builtin support for processing specific features using |
| 394 | <tt>libfuzzer</tt>. The specific features which can be tested this way |
| 395 | are found in the help text for the [/help?cmd=test-fuzz|test-fuzz |
| 396 | command]. |
| 397 | |
| 398 | Fuzzing requires: |
| 399 | |
| 400 | * Customizing the build of fossil a small bit. |
| 401 | * The clang compiler. |
| 402 | * libfuzzer. On Ubuntu-derived systems, it can be installed with |
| 403 | <tt>apt install libfuzzer-XYZ</tt>, where XYZ is a version number |
| 404 | (several versions may be available on any given system) |
| 405 | |
| 406 | |
| 407 | First, modify the top-level <tt>Makefile.in</tt>: |
| 408 | |
| 409 | * Extend the <tt>TCCFLAGS</tt> variable with: <tt>-fsanitize=fuzzer |
| 410 | -DFOSSIL_FUZZ</tt> (and see [/finfo/src/fuzz.c | src/fuzz.c] for |
| 411 | more options). |
| 412 | * Rename <tt>APPNAME</tt> from <tt>fossil</tt> to <tt>fossil-fuzz</tt>. |
| 413 | |
| 414 | Then rebuild: |
| 415 | |
| 416 | <pre></code>$ make clean |
| 417 | $ ./configure CC=/path/to/clang |
| 418 | $ make |
| 419 | </code></pre> |
| 420 | |
| 421 | If clang is your default compiler, the <tt>CC</tt> configure option is |
| 422 | not required. |
| 423 | |
| 424 | The resulting <tt>fossil-fuzz</tt> binary differs from the standard |
| 425 | one primarily in that it runs the <tt>test-fuzz</tt> command by |
| 426 | default. It needs to be told what to fuzz and needs to be given a |
| 427 | directory of input files to seed the fuzzer with: |
| 428 | |
| 429 | |
| 430 | <pre></code>$ mkdir cases |
| 431 | # Copy input files into ./cases. e.g. when fuzzing the markdown |
| 432 | # processor, copy any to-be-tested .md files into that directory. |
| 433 | # Then start the fuzzer: |
| 434 | $ ./fossil-fuzz --fuzztype markdown cases |
| 435 | </code></pre> |
| 436 | |
| 437 | As it works, it writes its test files into the test-input directory, |
| 438 | each one named in the form of a hash. When it finds a problem it will |
| 439 | produce a stack trace for the offending code, will output the |
| 440 | name of the file which triggered the crash (named |
| 441 | <tt>cases/SOME_HASH</tt>) and may, depending on the nature of the |
| 442 | problem, produce a file named <tt>crash-SOMETHING</tt>. In theory the |
| 443 | crash file can be fed directly back into the fuzzer to reproduce the |
| 444 | problem: |
| 445 | |
| 446 | <pre></code>$ ./fossil-fuzz --fuzztype markdown crash-SOMETHING |
| 447 | </code></pre> |
| 448 | |
| 449 | But whether or not it will genuinely crash may depend on static |
| 450 | app-level state which might not trigger the crash when running an |
| 451 | individual test. |
| 452 | |
| 453 | For a detailed tutorial of the fuzzer's flags and features, see: |
| 454 | |
| 455 | * [https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md] |
| 456 | |
| 457 | Flags for the fuzzer can be passed directly to fossil, e.g. <tt>-jobs=4</tt> |
| 458 | to start four fuzzer jobs in parallel. |
| 459 |