diff --git a/README.org b/README.org index 2347279..733b065 100644 --- a/README.org +++ b/README.org @@ -66,6 +66,8 @@ There are four key observations enabling this approach to bitcode collection: We wrap our generated bitcode in singleton tar files and allow the linker to accumulate them for us. When we want to collect aggregated bitcode for executable artifacts, we simply extract the tar file from their special LLVM bitcode ELF sections, extract the collected bitcode, and link it together with ~llvm-link~. +[[./doc/build_bom_seq.svg]] + Observe as well that the ~build-bom~ process useful for selective rebuilds: rebuilding only a portion of the sources will still have access to llvm-bitcode ELF sections in object from previous builds. The use of ~build-bom~ also has graceful degradation properties: object files which do not have llvm bitcode sections in their ELF (i.e. built separately without using ~build-bom~) will simply not contributed to the ELF section/tarfile accumulation of bitcode; the final extraction ~llvm-link~ does not need to be total and is tolerant of unresolved symbols. The bitcode extracted will be representative of the binary code contained in the specified file. It will not necessarily be identical to that code due to strictness flags, differences between clang and the native build compiler, and a different linking step. diff --git a/doc/build_bom_seq.d2 b/doc/build_bom_seq.d2 new file mode 100644 index 0000000..5f82150 --- /dev/null +++ b/doc/build_bom_seq.d2 @@ -0,0 +1,21 @@ +shape: sequence_diagram +build-bom +build tool +"Project's build tool": { + build tool."make,\ncmake,\nmeson,\nother ..." +} +build-bom.run -> build tool.all : fork + ptrace +build tool.all -> compile.run +compile.run -> build-bom.run.start : ptrace: "starting" +build-bom.run.start -> compile.run : ptrace: "ok, continue" +compile.run -> build-bom.run.end : ptrace: "finishing" +build-bom.run.end -> clang.run : -emit-llvm +clang.run -> build-bom.run.end : llvm bitcode +build-bom."Insert llvm bitcode in compile's ELF obj file" +build-bom.run.end -> compile.run { + style.stroke-dash: 5 +} +build-bom.run.end -> compile.run : ptrace: "ok, continue" +compile.run -> build tool.all +build tool."Repeats above as needed for build" +build tool.all -> build-bom.run diff --git a/doc/build_bom_seq.svg b/doc/build_bom_seq.svg new file mode 100644 index 0000000..d525ca8 --- /dev/null +++ b/doc/build_bom_seq.svg @@ -0,0 +1,116 @@ +build-bombuild toolcompileclangProject's build tool fork + ptraceptrace: "starting"ptrace: "ok, continue"ptrace: "finishing"-emit-llvmllvm bitcode ptrace: "ok, continue"make,cmake,meson,other ...Insert llvm bitcode in compile's ELF obj fileRepeats above as needed for build + + + + + + + + + + + + + + + + + diff --git a/doc/gen.sh b/doc/gen.sh new file mode 100644 index 0000000..fe4ce44 --- /dev/null +++ b/doc/gen.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +for X in build_bom_seq ; do + nix run nixpkgs#d2 -- -t 104 -l elk $X.d2 + nix shell nixpkgs#imagemagick -c convert -size 2048x2048 $X.svg $X.png +done