logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

samu.1 (5583B)


  1. .Dd November 10, 2021
  2. .Dt SAMU 1
  3. .Os
  4. .Sh NAME
  5. .Nm samu
  6. .Nd ninja-compatible build tool
  7. .Sh SYNOPSIS
  8. .Nm
  9. .Op Fl C Ar dir
  10. .Op Fl d Ar debugflag
  11. .Op Fl f Ar buildfile
  12. .Op Fl j Ar maxjobs
  13. .Op Fl k Ar maxfail
  14. .Op Fl l Ar maxload
  15. .Op Fl w Ar warnflag=action
  16. .Op Fl nv
  17. .Op Ar target...
  18. .Nm
  19. .Op Fl C Ar dir
  20. .Op Fl f Ar buildfile
  21. .Fl t Cm clean
  22. .Op Fl gr
  23. .Op Ar target...
  24. .Nm
  25. .Op Fl C Ar dir
  26. .Op Fl f Ar buildfile
  27. .Fl t Cm compdb
  28. .Op Fl x
  29. .Op Ar rule...
  30. .Nm
  31. .Op Fl C Ar dir
  32. .Op Fl f Ar buildfile
  33. .Fl t Cm commands
  34. .Op Ar target...
  35. .Nm
  36. .Op Fl C Ar dir
  37. .Op Fl f Ar buildfile
  38. .Fl t Cm graph
  39. .Op Ar target...
  40. .Nm
  41. .Op Fl C Ar dir
  42. .Op Fl f Ar buildfile
  43. .Fl t Cm query
  44. .Op Ar target...
  45. .Nm
  46. .Op Fl C Ar dir
  47. .Op Fl f Ar buildfile
  48. .Fl t Cm targets
  49. .Op Cm depth Op Ar maxdepth
  50. .Nm
  51. .Op Fl C Ar dir
  52. .Op Fl f Ar buildfile
  53. .Fl t Cm targets
  54. .Cm rule
  55. .Op Ar rulename
  56. .Nm
  57. .Op Fl C Ar dir
  58. .Op Fl f Ar buildfile
  59. .Fl t Cm targets
  60. .Cm all
  61. .Nm
  62. .Fl t Cm list
  63. .Sh DESCRIPTION
  64. .Nm
  65. loads a build manifest from
  66. .Ar buildfile
  67. and rebuilds
  68. .Ar targets
  69. if they are out of date.
  70. If no targets are specified, the manifest's default targets are built.
  71. If there are no default targets, the leaf nodes of the dependency graph are
  72. built (outputs that have no consuming action).
  73. .Pp
  74. Targets are out of date if they are older than the generating action's newest
  75. input, they have no entry in the build log, or if the command to build the
  76. target differs from what was used previously.
  77. Targets built with
  78. .Cm generator
  79. rules are not rebuilt if the command changes.
  80. .Pp
  81. If the
  82. .Cm clean
  83. tool is used, the targets are cleaned instead.
  84. When a target is cleaned, it is removed and are all of its inputs are cleaned.
  85. Targets with no generating actions are never removed.
  86. Targets built with
  87. .Sy generator
  88. rules are only removed if
  89. .Fl g
  90. is specified.
  91. .Pp
  92. If the
  93. .Cm commands
  94. tool is used, a list of shell commands used to build the specified
  95. (or default) targets is printed.
  96. .Pp
  97. If the
  98. .Cm compdb
  99. tool is used, a compilation database
  100. .Pq Lk https://clang.llvm.org/docs/JSONCompilationDatabase.html
  101. is printed instead.
  102. .Pp
  103. If the
  104. .Cm graph
  105. tool is used, a graphviz dot file is printed instead.
  106. .Pp
  107. If the
  108. .Cm query
  109. tool is used, the inputs and outputs of the targets are printed instead.
  110. .Pp
  111. If the
  112. .Cm targets
  113. tool is used, a list of targets will be displayed, either by rule or by depth.
  114. The first argument determines how the targets will be displayed:
  115. .Bl -tag -width Ds
  116. .It Cm depth
  117. An indented tree of targets will be displayed, starting by the root targets
  118. (those with no dependent targets), up to the depth specified by
  119. .Ar maxdepth
  120. (defaults to 1).
  121. .It Cm rule
  122. If
  123. .Ar rulename
  124. is given, a list of targets using the given rule will be displayed.
  125. Otherwise, a list of source files will be displayed.
  126. .It Cm all
  127. A list of all targets will be displayed.
  128. .El
  129. .Pp
  130. If the
  131. .Cm list
  132. tool is used, a list of available tools is displayed.
  133. .Sh OPTIONS
  134. .Bl -tag -width Ds
  135. .It Fl C
  136. Switch working directory to
  137. .Ar dir
  138. before building.
  139. .It Fl d
  140. Enable a debugging option.
  141. This flag may be specified multiple times to enable multiple debugging options.
  142. Possible values for
  143. .Ar debugflag
  144. are:
  145. .Bl -tag -width keepdepfile
  146. .It Cm explain
  147. Print messages explaining why outputs were dirty.
  148. .It Cm keepdepfile
  149. Don't remove $depfile after it was parsed.
  150. .It Cm keeprsp
  151. Don't remove $rspfile after job completion or failure.
  152. .El
  153. .It Fl f
  154. Load manifest from
  155. .Ar buildfile
  156. instead of build.ninja.
  157. .It Fl j
  158. Run up to
  159. .Ar maxjobs
  160. jobs in parallel (default based on number of CPUs).
  161. If zero, allow unlimited concurrent jobs.
  162. .It Fl k
  163. Allow up to
  164. .Ar maxfail
  165. job failures.
  166. If negative or zero, allow any number of job failures.
  167. .It Fl l
  168. Do not spawn new jobs if the system load percentage is greater than
  169. .Ar maxload .
  170. If zero, spawn jobs as soon as possible.
  171. .It Fl n
  172. Do not actually execute the commands or update the log.
  173. .It Fl v
  174. Print full commands instead of just
  175. .Sy description .
  176. .It Fl w
  177. Control how certain errors are handled.
  178. If
  179. .Ar warnflag
  180. is
  181. .Cm dupbuild ,
  182. .Ar action
  183. specifies what to do if an output is listed in multiple build edges.
  184. If
  185. .Ar action
  186. is
  187. .Cm err ,
  188. treat it like an error and fail.
  189. If
  190. .Ar action
  191. is
  192. .Cm warn ,
  193. only print a diagnostic message.
  194. .It Fl t
  195. Instead of building, invoke a subtool.
  196. All arguments and flags after the subtool are interpreted by the subtool.
  197. The currently supported subtools are
  198. .Cm clean ,
  199. .Cm commands ,
  200. .Cm compdb ,
  201. .Cm graph ,
  202. .Cm query ,
  203. and
  204. .Cm targets .
  205. .It Fl g
  206. When cleaning, also clean outputs of
  207. .Sy generator
  208. actions.
  209. .It Fl r
  210. .Ar targets
  211. are interpreted as rules, and all outputs of actions with the specified rule
  212. types will be cleaned instead.
  213. .It Fl x
  214. When printing a compilation database, replace @$rspfile with $rspfile_content (with <blank> in place of <newline>).
  215. .El
  216. .Sh ENVIRONMENT
  217. .Bl -tag -width NINJA_STATUS
  218. .It Ev SAMUFLAGS
  219. Options for
  220. .Nm
  221. that get applied before those specified on the command-line.
  222. The only options allowed in
  223. .Ev SAMUFLAGS
  224. are
  225. .Fl v ,
  226. .Fl j
  227. and
  228. .Fl l .
  229. .It Ev NINJA_STATUS
  230. The status output printed to the left of each rule description, using printf-like conversion specifiers.
  231. If unset, the default is "[%s/%t] ".
  232. .Pp
  233. Available conversion specifiers:
  234. .Bl -tag -width Ds
  235. .It Cm %s
  236. Number of started jobs.
  237. .It Cm %f
  238. Number of finished jobs.
  239. .It Cm %t
  240. Total number of jobs.
  241. .It Cm %r
  242. Number of running jobs.
  243. .It Cm %u
  244. Number of remaining jobs.
  245. .It Cm %p
  246. Percentage of completed jobs.
  247. .It Cm %o
  248. Rate of finished jobs per second (to 1 decimal place).
  249. .It Cm %e
  250. Elapsed time in seconds (to 3 decimal places).
  251. .It Cm %%
  252. The '%' character.
  253. .El
  254. .El
  255. .Sh SEE ALSO
  256. .Xr make 1