Fix remaining warnings and enable RTD failures on warnings

angr · Aug 11, 2023 · 1b12d2a · 1b12d2a
1 parent 1411960
commit 1b12d2a
Show file tree

Hide file tree

Showing 23 changed files with 50 additions and 45 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -17,3 +17,6 @@ python:
       path: .
       extra_requirements:
         - docs
+
+sphinx:
+  fail_on_warning: true
diff --git a/README.md b/README.md
@@ -95,9 +95,8 @@ There are several backends that can be used to load a single file:
   - PE is a backend to load Microsoft's Portable Executable format,
     effectively Windows binaries. It uses the (optional) `pefile` module.
 
-  - Mach-O is a backend to load, you guessed it, Mach-O binaries. It is
-    subject to several limitations, which you can read about in the
-    [readme in the macho directory](backends/macho/README.md)
+  - Mach-O is a backend to load, you guessed it, Mach-O binaries. Support is
+    limited for this backend.
 
   - Blob is a backend to load unknown data. It requires that you specify
     the architecture it would be run on, in the form of a class from

diff --git a/cle/backends/macho/README.md b/cle/backends/macho/README.md
diff --git a/cle/backends/macho/macho.py b/cle/backends/macho/macho.py
@@ -71,20 +71,19 @@ def get_by_name_and_ordinal(self, name: str, ordinal: int, include_stab=False) -
 
 # pylint: enable =abstract-method
 
-
 class MachO(Backend):
     """
     Mach-O binaries for CLE
+    -----------------------
 
-    The Mach-O format is notably different from other formats, as such:
-    *   Sections are always part of a segment, self.sections will thus be empty
-    *   Symbols cannot be categorized like in ELF
-    *   Symbol resolution must be handled by the binary
-    *   Rebasing in dyld is implemented via adding a small slide to addresses inside the binary, instead of
-        changing the base address of the binary and the addresses being relative. CLE needs relative addresses,
-        so there are a lot of AT.from_lva().to_rva() calls in this backend.
+    The Mach-O format is notably different from other formats. Specifically:
 
-    *   ...
+    - Sections are always part of a segment, so `self.sections` will be empty.
+    - Symbols cannot be categorized like in ELF.
+    - Symbol resolution must be handled by the binary.
+    - Rebasing in dyld is implemented by adding a small slide to addresses inside the binary, instead of
+      changing the base address of the binary. Consequently, the addresses are absolute rather than relative.
+      CLE requires relative addresses, leading to numerous `AT.from_lva().to_rva()` calls in this backend.
     """
 
     is_default = True  # Tell CLE to automatically consider using the MachO backend

diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
diff --git a/docs/api/backend.rst b/docs/api/backend.rst
@@ -1,3 +1,6 @@
+Backend Interface
+=================
+
 .. automodule:: cle.backends.backend
 .. automodule:: cle.backends.symbol
 .. automodule:: cle.backends.regions

diff --git a/docs/api/backends/binja.rst b/docs/api/backends/binja.rst
@@ -1 +1,4 @@
+Binary Ninja
+============
+
 .. automodule:: cle.backends.binja
diff --git a/docs/api/backends/blob.rst b/docs/api/backends/blob.rst
@@ -1 +1,4 @@
+Blob
+====
+
 .. automodule:: cle.backends.blob
diff --git a/docs/api/backends/cgc.rst b/docs/api/backends/cgc.rst
@@ -1,3 +1,6 @@
+CGC
+===
+
 .. automodule:: cle.backends.cgc
 .. automodule:: cle.backends.cgc.cgc
 .. automodule:: cle.backends.cgc.backedcgc
diff --git a/docs/api/backends/elf.rst b/docs/api/backends/elf.rst
@@ -2,7 +2,6 @@ ELF Backend
 ===========
 
 .. autoclass:: cle.backends.ELF
-.. autoclass:: cle.backends.ELFSymbol
 
 .. autoclass:: cle.backends.elf.ELFCore
 

diff --git a/docs/api/backends/ihex.rst b/docs/api/backends/ihex.rst
@@ -1 +1,4 @@
+IHex
+====
+
 .. automodule:: cle.backends.ihex
diff --git a/docs/api/backends/index.rst b/docs/api/backends/index.rst
@@ -4,12 +4,10 @@ Backends
 .. toctree::
    :maxdepth: 1
 
-   .. Most common backends
    ELF <elf>
    PE <pe>
    Mach-O <macho>
 
-   .. Other backends in alphabetical order
    Binary Ninja <binja>
    Blob <blob>
    CGC <cgc>

diff --git a/docs/api/backends/java.rst b/docs/api/backends/java.rst
@@ -1,3 +1,6 @@
+Java
+====
+
 .. automodule:: cle.backends.java.android_lifecycle
 .. automodule:: cle.backends.java.apk
 .. automodule:: cle.backends.java.jar

diff --git a/docs/api/backends/macho.rst b/docs/api/backends/macho.rst
@@ -1,5 +1,5 @@
-Mach-O Backend
-==============
+Mach-O
+======
 
 .. autoclass:: cle.backends.macho.macho.MachO
 .. autoclass:: cle.backends.macho.macho.SymbolList
@@ -8,5 +8,4 @@ Mach-O Backend
 .. automodule:: cle.backends.macho.section
 .. automodule:: cle.backends.macho.segment
 .. automodule:: cle.backends.macho.binding
-.. automodule:: cle.backends.macho.macho_load_commands
 .. automodule:: cle.backends.macho.structs
diff --git a/docs/api/backends/minidump.rst b/docs/api/backends/minidump.rst
@@ -1 +1,4 @@
+Minidump
+========
+
 .. automodule:: cle.backends.minidump
diff --git a/docs/api/backends/pe.rst b/docs/api/backends/pe.rst
@@ -1,5 +1,5 @@
-PE Backend
-==========
+PE
+==
 
 .. autoclass:: cle.backends.PE
 

diff --git a/docs/api/backends/static_archive.rst b/docs/api/backends/static_archive.rst
@@ -1 +1,4 @@
+Static Archive
+==============
+
 .. automodule:: cle.backends.static_archive
diff --git a/docs/api/backends/uefi_firmware.rst b/docs/api/backends/uefi_firmware.rst
@@ -1,2 +1,5 @@
+UEFI Firmware
+=============
+
 .. automodule:: cle.backends.uefi_firmware
 .. automodule:: cle.backends.te
diff --git a/docs/api/backends/xbe.rst b/docs/api/backends/xbe.rst
@@ -1 +1,4 @@
+Xbox Executable
+===============
+
 .. automodule:: cle.backends.xbe
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -2,7 +2,7 @@ API Documentation
 =================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 0
 
    Loader Interface <loader>
    Backend Interface <backend>

diff --git a/docs/api/relocations.rst b/docs/api/relocations.rst
@@ -12,7 +12,6 @@ Look at the existing versions for details.
 .. automodule:: cle.backends.elf.relocation.elfreloc
 .. automodule:: cle.backends.elf.relocation.mips64
 .. automodule:: cle.backends.elf.relocation.generic
-.. automodule:: cle.backends.elf.relocation.armel
 .. automodule:: cle.backends.elf.relocation.ppc
 .. automodule:: cle.backends.elf.relocation.armhf
 .. automodule:: cle.backends.elf.relocation.pcc64

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,7 +22,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
-    "sphinx.ext.viewcode",
+    # "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "myst_parser",
 ]

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,7 +6,7 @@ The first shows basic usage of CLE, and the second shows the API reference.
 
 
 .. toctree::
-   :maxdepth: 5
+   :maxdepth: 1
    :caption: Contents:
 
    Quickstart <quickstart>