logo

deblob

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

deblob.1 (4144B)

    

  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. Python 2.7 & 3.8/3.9/3.10/3.11/3.12 bytecode files, typically
  96. .Sq *.pyc
  97. .It
  98. Python pickle files, used to serialize Python objects
  99. .It
  100. Portable Executable files, typically
  101. .Sq *.exe
  102. and
  103. .Sq *.dll .
  104. .It
  105. Lua bytecode
  106. .It
  107. WASM (Web Assembly)
  108. .It
  109. Apple Preferred Executable Format
  110. .It
  111. MoarVM bytecode
  112. .It
  113. Parrot bytecode
  114. .It
  115. Perl Storable data (v0.6 and v0.7)
  116. .It
  117. Device Tree Blob, typically
  118. .Sq *.dtb
  119. .It
  120. Chez Scheme bytecode
  121. .It
  122. NekoVM bytecode
  123. .It
  124. OCaml bytecode and native binaries
  125. .It
  126. Racket bytecode
  127. .It
  128. Emacs Lisp Bytecode
  129. .It
  130. Ren'Py Archives v1/v2/v3
  131. .It
  132. Squirrel bytecode
  133. .It
  134. Pre-Compiled Headers: Clang, GCC
  135. .It
  136. GCC Rust Metadata, typically
  137. .It
  138. Dart Kernel and JIT snapshots
  139. .Sq *.rox
  140. .El
  141. .Sh EXAMPLES
  142. The following code block shows how it can be used in Gentoo's
  143. .Pa /etc/portage/bashrc :
  144. .Bd -literal
  145. # Will be ran before configure phase, allowing ebuilds to delete blobs themselves in the prepare phase
  146. if [ "${EBUILD_PHASE}" == "configure" ]; then
  147. 	if grep -q -- '-bin$' <<<"${PN}"; then
  148. 		echo ":: *-bin package, not deblobbing"
  149. 	elif grep -q -- "${PN}" /etc/portage/deblob.reject; then
  150. 		echo ":: package is in /etc/portage/deblob.reject, no removals"
  151. 		time deblob -n -e 'test*' -e '*/test*' -d "${WORKDIR}"
  152. 	else
  153. 		time deblob -e 'test*' -e '*/test*' -d "${WORKDIR}"
  154. 	fi
  155. fi
  156. .Ed
  157. .Sh HISTORY
  158. This tool was originally implemented in Go as "go-deblob" and got rewritten
  159. to hare as "deblob".
  160. .Sh AUTHORS
  161. .An Haelwenn (lanodan) Monnier Aq Mt contact+deblob-mdoc@hacktivis.me
  162. .Sh CAVEATS
  163. .Ss Out of scope formats
  164. .Bl -dash -compact
  165. .It
  166. Generic formats and executables based on them:
  167. .Bl -dash -compact
  168. .It
  169. Generic Archives: Tarballs, Distro Packages, ZIP (including Java\~Jar), Cabinet (CAB), Microsoft Compound File (including MSI), …
  170. .It
  171. Filesystems, disk dumps, databases
  172. .El
  173. .It
  174. Obscure proprietary formats, like executables/firmware where no libre implementation exists for either execution or compilation
  175. .El