Revamp documentation - #6
ammaraskar wants to merge 1 commit into
Conversation
e331ead to
5d0c7ea
Compare
|
Thanks for catching those László, I'm sure there's more missing references that can be changed to links. We'll get them all eventually :) |
Is this where you intend the docs to be published? Would it be possible to host it on https://google.github.io/AFL, like https://google.github.io/clusterfuzz/ ? |
|
The trouble with hosting on GitHub pages is then you either need to manually push updates to the gh-pages branch or set up some infrastructure to do it for you automatically. Readthedocs just does that for us automatically, it automatically pulls changes pushed to master and other branches and builds them. If you're concerned about the domain name it's always possible to set up a CNAME from any domain to afl.readthedocs.io I really like the latter approach but there's nothing stopping us from doing the former. |
As of current trunk LLVM, the instrumentation no longer functions correctly because the IR may have already been simplified to remove explicit branches. For example, on this snippet of the sample test-instr.c file: > if (buf[0] == '0') Clang 10.0.0 (trunk 370425) (llvm/trunk 370432) produces the following IR: %cmp2 = icmp eq i8 %19, 48, !dbg !36 %.sink = select i1 %cmp2, i8* getelementptr inbounds ([26 x i8], [26 x i8]* @.str.1, i64 0, i64 0), i8* getelementptr inbounds ([31 x i8], [31 x i8]* @.str.2, i64 0, i64 0), !dbg !37 %call6 = tail call i32 (i32, i8*, ...) @__printf_chk(i32 1, i8* %.sink) google#6, !dbg !38 Previously, Clang 8.0.0-3~ubuntu18.04.1 (tags/RELEASE_800/final) produced the following IR: %29 = icmp eq i8 %28, 48, !dbg !37 br i1 %29, label %30, label %38, !dbg !38 As a workaround, run the instrumentation earlier, likely before e.g. the 'simplifycfg' pass removes explicit branches.
As of current trunk LLVM, the instrumentation no longer functions correctly because the IR may have already been simplified to remove explicit branches. For example, on this snippet of the sample test-instr.c file: > if (buf[0] == '0') Clang 10.0.0 (trunk 370425) (llvm/trunk 370432) produces the following IR: %cmp2 = icmp eq i8 %19, 48, !dbg !36 %.sink = select i1 %cmp2, i8* getelementptr inbounds ([26 x i8], [26 x i8]* @.str.1, i64 0, i64 0), i8* getelementptr inbounds ([31 x i8], [31 x i8]* @.str.2, i64 0, i64 0), !dbg !37 %call6 = tail call i32 (i32, i8*, ...) @__printf_chk(i32 1, i8* %.sink) google#6, !dbg !38 Previously, Clang 8.0.0-3~ubuntu18.04.1 (tags/RELEASE_800/final) produced the following IR: %29 = icmp eq i8 %28, 48, !dbg !37 br i1 %29, label %30, label %38, !dbg !38 As a workaround, run the instrumentation earlier, likely before e.g. the 'simplifycfg' pass removes explicit branches.
As of current trunk LLVM, the instrumentation no longer functions correctly because the IR may have already been simplified to remove explicit branches. For example, on this snippet of the sample test-instr.c file: > if (buf[0] == '0') Clang 10.0.0 (trunk 370425) (llvm/trunk 370432) produces the following IR: %cmp2 = icmp eq i8 %19, 48, !dbg !36 %.sink = select i1 %cmp2, i8* getelementptr inbounds ([26 x i8], [26 x i8]* @.str.1, i64 0, i64 0), i8* getelementptr inbounds ([31 x i8], [31 x i8]* @.str.2, i64 0, i64 0), !dbg !37 %call6 = tail call i32 (i32, i8*, ...) @__printf_chk(i32 1, i8* %.sink) google#6, !dbg !38 Previously, Clang 8.0.0-3~ubuntu18.04.1 (tags/RELEASE_800/final) produced the following IR: %29 = icmp eq i8 %28, 48, !dbg !37 br i1 %29, label %30, label %38, !dbg !38 This change causes the input-dependent branch of test-instr.c to be invisible to the instrumentation, resulting in an error when testing the instrumentation after compilation. As a workaround, run the instrumentation earlier, likely before the 'simplifycfg' pass simplifies out the branch.
As of current trunk LLVM, the instrumentation no longer functions correctly because the IR may have already been simplified to remove explicit branches. For example, on this snippet of the sample test-instr.c file: > if (buf[0] == '0') Clang 10.0.0 (trunk 370425) (llvm/trunk 370432) produces the following IR: %cmp2 = icmp eq i8 %19, 48, !dbg !36 %.sink = select i1 %cmp2, i8* getelementptr inbounds ([26 x i8], [26 x i8]* @.str.1, i64 0, i64 0), i8* getelementptr inbounds ([31 x i8], [31 x i8]* @.str.2, i64 0, i64 0), !dbg !37 %call6 = tail call i32 (i32, i8*, ...) @__printf_chk(i32 1, i8* %.sink) #6, !dbg !38 Previously, Clang 8.0.0-3~ubuntu18.04.1 (tags/RELEASE_800/final) produced the following IR: %29 = icmp eq i8 %28, 48, !dbg !37 br i1 %29, label %30, label %38, !dbg !38 This change causes the input-dependent branch of test-instr.c to be invisible to the instrumentation, resulting in an error when testing the instrumentation after compilation. As a workaround, run the instrumentation earlier, likely before the 'simplifycfg' pass simplifies out the branch.
@Dor1s Pushing the docs to the |
Thanks @jaylinski! I think it'd be great to set up auto deploy to https://google.github.io/AFL ! Wdyt @ammaraskar @Dor1s? |
Dor1s
left a comment
Dor1s
left a comment
There was a problem hiding this comment.
Before anyone else invested too much effort into this, at this point we do not intent to migrate the docs from dead simple .txt format. //cc @jonathanmetzman
|
Let me close this for the time being. |
4 participants
You can preview the newly built docs here: https://afl-1.readthedocs.io/en/latest/
Let's have some more modern documentation rather than just dozens of
.txtfiles. I've kept Michael's original philosophy though and made sure the plaintext files are easy to read as well.I've chosen Sphinx because it's a popular choice (used by other Google projects as well: kmsan, python-fire) and lets us use readthedocs to keep our docs automatically updated and publicly available.
This also greatly reduces the cruft in the README, we should add some more stuff there separately.