Build dot files with docs

dyninst · Apr 3, 2024 · 5398428 · 5398428
1 parent bf68ff1
commit 5398428
Show file tree

Hide file tree

Showing 17 changed files with 26 additions and 46 deletions.
diff --git a/.gitignore b/.gitignore
@@ -43,17 +43,6 @@ autom4te.cache/*
 testsuite/*/binaries/*
 parseThat/*/Makefile
 parseThat/*/parseThat
-instructionAPI/doc/latex/annotated.tex
-instructionAPI/doc/latex/doxygen.sty
-instructionAPI/doc/latex/hierarchy.tex
-instructionAPI/doc/latex/index.tex
-instructionAPI/doc/latex/modules.tex
-instructionAPI/doc/html
-instructionAPI/doc/.gitignore
-patchAPI/doc/patchapi.aux
-patchAPI/doc/patchapi.log
-patchAPI/doc/patchapi.out
-patchAPI/doc/patchapi.toc
 test.sh
 autodyninst/configure
 config.log
@@ -103,17 +92,11 @@ install_manifest.txt
 binutils
 libelf
 libdwarf
-*.aux
-*.dvi
-*.toc
-*.out
 CHANGELOG
 *.bak
 massif.out.*
 DyninstAPI*.tgz
 common/h/dyninstversion.h
-Doxyfile
-doxyfiles/*
 *.dir/
 */Debug/
 */Release/
@@ -128,3 +111,4 @@ cmake-build-*/
 *__pycache__*
 docs/env
 docs/_build
+*.png
diff --git a/docs/.gitignore b/docs/.gitignore
diff --git a/docs/README.md b/docs/README.md
@@ -7,6 +7,7 @@ $ python -m venv env
 $ source env/bin/activate
 $ pip install -r requirements.txt
 $ `cd $(find env/lib -type d -name sphinxcontrib) && wget https://raw.githubusercontent.com/wpilibsuite/sphinxext-remoteliteralinclude/main/sphinxext/remoteliteralinclude.py`
+$ for file in $(find . -name "*.dot"); do dot -Tpng "$file" -o "${file%.*}.png"; done
 ```
 
 Then build the thing you want:

diff --git a/instructionAPI/src/ast_ownership.dot → docs/instructionAPI/fig/ast_ownership.dot b/instructionAPI/src/ast_ownership.dot → docs/instructionAPI/fig/ast_ownership.dot
diff --git a/docs/instructionAPI/fig/ast_ownership.pdf b/docs/instructionAPI/fig/ast_ownership.pdf
diff --git a/instructionAPI/src/decoder_use.dot → docs/instructionAPI/fig/decoder_use.dot b/instructionAPI/src/decoder_use.dot → docs/instructionAPI/fig/decoder_use.dot
diff --git a/docs/instructionAPI/fig/decoder_use.pdf b/docs/instructionAPI/fig/decoder_use.pdf
diff --git a/instructionAPI/src/deref-eval.dot → docs/instructionAPI/fig/deref-eval.dot b/instructionAPI/src/deref-eval.dot → docs/instructionAPI/fig/deref-eval.dot
@@ -17,4 +17,4 @@ digraph eval_example
   SIBexpr [label = "{u32:+ | {<arg1> u32:0xB000|<arg2>u32:0x80} }"];
   deref [label = "{{u16:deref}|u32:0xB080}"];
   result [label="u16:UNKNOWN"];
-};
+}
diff --git a/docs/instructionAPI/fig/deref-eval.png b/docs/instructionAPI/fig/deref-eval.png
diff --git a/...ructionAPI/src/full_inheritance_graph.dot → ...ructionAPI/fig/full_inheritance_graph.dot b/...ructionAPI/src/full_inheritance_graph.dot → ...ructionAPI/fig/full_inheritance_graph.dot
diff --git a/docs/instructionAPI/fig/full_inheritance_graph.pdf b/docs/instructionAPI/fig/full_inheritance_graph.pdf
diff --git a/...ionAPI/src/instruction_representation.dot → ...ionAPI/fig/instruction_representation.dot b/...ionAPI/src/instruction_representation.dot → ...ionAPI/fig/instruction_representation.dot
diff --git a/docs/instructionAPI/fig/instruction_representation.pdf b/docs/instructionAPI/fig/instruction_representation.pdf
diff --git a/instructionAPI/src/ownership_graph.dot → docs/instructionAPI/fig/ownership_graph.dot b/instructionAPI/src/ownership_graph.dot → docs/instructionAPI/fig/ownership_graph.dot
diff --git a/docs/instructionAPI/fig/ownership_graph.pdf b/docs/instructionAPI/fig/ownership_graph.pdf
diff --git a/docs/instructionAPI/fig/refman.pdf b/docs/instructionAPI/fig/refman.pdf
diff --git a/docs/instructionAPI/overview.rst b/docs/instructionAPI/overview.rst
@@ -1,31 +1,27 @@
 .. _`sec:instruction-intro`:
 
-==============
 InstructionAPI
-==============
+##############
 
 When analyzing and modifying binary code, it is necessary to translate
 between raw binary instructions and an abstract form that describes the
-semantics of the instructions. As a part of the Dyninst project, we have
-developed the Instruction API, an API and library for decoding and
-representing machine instructions in a platform-independent manner. The
-Instruction API includes methods for decoding machine language,
-convenient abstractions for its analysis, and methods to produce
-disassembly from those abstractions. The current implementation supports
-the x86, x86-64, ARMv8-64, PowerPC-32, and PowerPC-64 instruction sets.
+semantics of the instructions. The Instruction API includes methods for
+decoding machine language, convenient abstractions for its analysis, and
+methods to produce disassembly from those abstractions.
+
 The Instruction API has the following basic capabilities:
 
--  Decoding: interpreting a sequence of bytes as a machine instruction
-   in a given machine language.
+  -  Decoding: interpreting a sequence of bytes as a machine instruction
+     in a given machine language.
 
--  Abstract representation: representing the behavior of that
-   instruction as an abstract syntax tree.
+  -  Abstract representation: representing the behavior of that
+     instruction as an abstract syntax tree.
 
--  Disassembly: translating an abstract representation of a machine
-   instruction into a string representation of the corresponding
-   assembly language instruction.
+  -  Disassembly: translating an abstract representation of a machine
+     instruction into a string representation of the corresponding
+     assembly language instruction.
 
-Our goal in designing the Instruction API is to provide a representation
+The goal of the Instruction API is to provide a representation
 of machine instructions that can be manipulated by higher-level
 algorithms with minimal knowledge of platform-specific details. In
 addition, users who need platform-specific information should be able to
@@ -42,7 +38,7 @@ computation.
 .. _`sec:instruction-abstractions`:
 
 Abstractions
-============
+************
 
 The Instruction API contains three major components: the top-level
 instruction representation, the abstract syntax trees representing the
@@ -52,7 +48,7 @@ each of these three components, followed by an example of how the
 Instruction API can be applied to binary analysis.
 
 Instruction Interface
----------------------
+=====================
 
 The Instruction API represents a machine language instruction as an
 Instruction object, which contains an Operation and a collection of
@@ -76,7 +72,7 @@ operations required to compute the value of the operand.
 Figure `1 <#fig:ownership-graph>`__ depicts these ownership
 relationships within an Instruction.
 
-.. figure:: fig/ownership_graph.pdf
+.. figure:: fig/ownership_graph.png
    :alt: An Instruction and the objects it owns
    :name: fig:ownership-graph
 
@@ -101,7 +97,7 @@ using just this second interface (namely the ``getReadSet`` and
 ``getWriteSet`` functions).
 
 Instruction Decoding
---------------------
+====================
 
 An InstructionDecoder interprets a sequence of bytes according to a
 given machine language and transforms them into an instruction
@@ -110,7 +106,7 @@ translates that opcode to an Operation object, uses that Operation to
 determine how to decode the instruction’s Operands, and produces a
 decoded Instruction.
 
-.. figure:: fig/decoder_use.pdf
+.. figure:: fig/decoder_use.png
    :alt: The InstructionDecoder’s inputs and outputs
    :name: fig:decoder-use
 
@@ -133,7 +129,7 @@ platform-independent manner.
 .. _`subsec:hierarchy`:
 
 InstructionAST Hierarchy
-------------------------
+========================
 
 The AST representation of an operand encapsulates the operations
 performed on registers and immediates to produce an operand for the
@@ -142,7 +138,7 @@ machine language instruction.
 The inheritance hierarchy of the AST classes is shown in
 Figure `3 <#fig:inheritance>`__.
 
-.. figure:: fig/full_inheritance_graph.pdf
+.. figure:: fig/full_inheritance_graph.png
    :alt: The InstructionAST inheritance hierarchy
    :name: fig:inheritance
 
@@ -158,13 +154,13 @@ relationships within a given tree, and
 Figure `5 <#fig:representation>`__ shows how an example IA32 instruction
 is represented using these objects.
 
-.. figure:: fig/ast_ownership.pdf
+.. figure:: fig/ast_ownership.png
    :alt: InstructionAST intermediate node types and the objects they own
    :name: fig:ownership
 
    InstructionAST intermediate node types and the objects they own
 
-.. figure:: fig/instruction_representation.pdf
+.. figure:: fig/instruction_representation.png
    :alt: The decomposition of mov %eax, (%esi)
    :name: fig:representation
 
@@ -181,7 +177,7 @@ known at the time an instruction is decoded. More details on this
 mechanism may be found in Section `3.5 <#sec:expression>`__.
 
 Visitor Paradigm
-----------------
+================
 
 An alternative to the bind/eval mechanism is to use a *visitor*
 over an expression tree. The visitor concept applies a user-specified