logo

deblob

remove binary executables from a directory git clone https://anongit.hacktivis.me/git/deblob.git/

deblob.1 (4167B)

    

  1. .\" SPDX-FileCopyrightText: 2019 deblob Authors <https://hacktivis.me/projects/deblob>
  2. .\" SPDX-License-Identifier: BSD-3-Clause
  3. .Dd 2024-11-16
  4. .Dt DEBLOB 1
  5. .Os
  6. .Sh NAME
  7. .Nm deblob
  8. .Nd remove binary executables ("blobs") from a directory
  9. .Sh SYNOPSIS
  10. .Nm
  11. .Op Fl cn
  12. .Op Fl d Ar workdir
  13. .Op Fl e Ar excluded path ...
  14. .Op Fl j Ar file
  15. .Sh DESCRIPTION
  16. The
  17. .Nm
  18. utility cleans a directory from binary executables ("blobs").
  19. Useful to clean a source tree to make sure it fully builds from source.
  20. .Pp
  21. Scanning for blobs inside source files is considered to be out-of-scope as
  22. .Lk https://www.fsfla.org/svn/fsfla/software/linux-libre/scripts/ linux-libre deblob script
  23. already exists.
  24. .Pp
  25. The options are as follows:
  26. .Bl -tag -width Ds
  27. .It Fl c
  28. Return error if any non-excluded blobs were found.
  29. .It Fl d Ar workdir
  30. Directory to be scanned rather than the current working directory on execution.
  31. .It Fl e Ar excluded path
  32. Paths to be excluded from removal, accepts shell-style globbing.
  33. Pass the option multiple times to do multiple exclusions.
  34. .It Fl j Ar file
  35. JSON file to log actions taken and metadata into.
  36. See
  37. .Sx JSON OUTPUT FORMAT
  38. section.
  39. .It Fl n
  40. Scan the files but do not actually delete them.
  41. .El
  42. .Sh EXIT STATUS
  43. The
  44. .Nm
  45. utility exits with the following statuses:
  46. .Bl -tag -width _
  47. .It 0
  48. No errors happened and if
  49. .Fl c
  50. was passed, no matching blobs were found.
  51. .It 1
  52. Failed scanning for blobs, for example due to an I/O error.
  53. .It 2
  54. Option
  55. .Fl c
  56. passed and matching blobs were found.
  57. .El
  58. .Sh JSON OUTPUT FORMAT
  59. When the
  60. .Fl j Ar file
  61. option is set,
  62. .Nm
  63. writes a JSON list of objects containing the following keys:
  64. .Bl -tag -width format
  65. .It action
  66. Action which
  67. .Nm
  68. took.
  69. For example: "ignoring", "detected", "removing".
  70. .It format
  71. Short description of the detected format, intended for humans.
  72. No stability guarantees.
  73. .It path
  74. Path of the matched file, relative to the working directory, as changed by
  75. .Cm cd
  76. and
  77. .Fl d Ar workdir .
  78. .El
  79. .Sh SUPPORTED FORMATS
  80. Blobs scanned against are the following:
  81. .Bl -dash -compact
  82. .It
  83. Executable and Linking Format (ELF) files
  84. .It
  85. Unix
  86. .Xr ar 1
  87. files
  88. .It
  89. x86 IBM PC BIOS Option Rom
  90. .It
  91. Erlang BEAM files and BEAM/PKZIP-based escripts
  92. .It
  93. Java Class files and Archives (JAR)
  94. .It
  95. Mach-O executables
  96. .It
  97. Python 2.7 & 3.8/3.9/3.10/3.11/3.12 bytecode files, typically
  98. .Sq *.pyc
  99. .It
  100. Python pickle files, used to serialize Python objects
  101. .It
  102. Portable Executable files, typically
  103. .Sq *.exe
  104. and
  105. .Sq *.dll .
  106. .It
  107. Lua bytecode
  108. .It
  109. WASM (Web Assembly)
  110. .It
  111. Apple Preferred Executable Format
  112. .It
  113. MoarVM bytecode
  114. .It
  115. Parrot bytecode
  116. .It
  117. Perl Storable data (v0.6 and v0.7)
  118. .It
  119. Device Tree Blob, typically
  120. .Sq *.dtb
  121. .It
  122. Chez Scheme bytecode
  123. .It
  124. NekoVM bytecode
  125. .It
  126. OCaml bytecode and native binaries
  127. .It
  128. Racket bytecode
  129. .It
  130. Emacs Lisp Bytecode
  131. .It
  132. Ren'Py Archives v1/v2/v3
  133. .It
  134. Squirrel bytecode
  135. .It
  136. Pre-Compiled Headers: Clang, GCC
  137. .It
  138. GCC Rust Metadata, typically
  139. .It
  140. Dart Kernel and JIT snapshots
  141. .Sq *.rox
  142. .El
  143. .Sh EXAMPLES
  144. The following code block shows how it can be used in Gentoo's
  145. .Pa /etc/portage/bashrc :
  146. .Bd -literal
  147. # Will be ran before configure phase, allowing ebuilds to delete blobs themselves in the prepare phase
  148. if [ "${EBUILD_PHASE}" == "configure" ]; then
  149. 	if grep -q -- '-bin$' <<<"${PN}"; then
  150. 		echo ":: *-bin package, not deblobbing"
  151. 	elif grep -q -- "${PN}" /etc/portage/deblob.reject; then
  152. 		echo ":: package is in /etc/portage/deblob.reject, no removals"
  153. 		time deblob -n -e 'test*' -e '*/test*' -d "${WORKDIR}"
  154. 	else
  155. 		time deblob -e 'test*' -e '*/test*' -d "${WORKDIR}"
  156. 	fi
  157. fi
  158. .Ed
  159. .Sh HISTORY
  160. This tool was originally implemented in Go as "go-deblob" and got rewritten
  161. to hare as "deblob".
  162. .Sh AUTHORS
  163. .An Haelwenn (lanodan) Monnier Aq Mt contact+deblob-mdoc@hacktivis.me
  164. .Sh CAVEATS
  165. .Ss Out of scope formats
  166. .Bl -dash -compact
  167. .It
  168. Generic formats and executables based on them:
  169. .Bl -dash -compact
  170. .It
  171. Generic Archives: Tarballs, Distro Packages, ZIP (including Java\~Jar), Cabinet (CAB), Microsoft Compound File (including MSI), …
  172. .It
  173. Filesystems, disk dumps, databases
  174. .El
  175. .It
  176. Obscure proprietary formats, like executables/firmware where no libre implementation exists for either execution or compilation
  177. .El