Coverage for src/debputy/plugins/debputy/private_api.py: 83%

1import ctypes 

2import ctypes.util 

3import dataclasses 

4import functools 

5import textwrap 

6import time 

7from datetime import datetime 

8from typing import cast, NotRequired, Union, TypedDict, Annotated, Any 

9from collections.abc import Callable 

10 

11from debian.changelog import Changelog 

12from debian.deb822 import Deb822 

13 

14from debputy._manifest_constants import ( 

15 MK_CONFFILE_MANAGEMENT_X_OWNING_PACKAGE, 

16 MK_CONFFILE_MANAGEMENT_X_PRIOR_TO_VERSION, 

17 MK_INSTALLATIONS_INSTALL_EXAMPLES, 

18 MK_INSTALLATIONS_INSTALL, 

19 MK_INSTALLATIONS_INSTALL_DOCS, 

20 MK_INSTALLATIONS_INSTALL_MAN, 

21 MK_INSTALLATIONS_DISCARD, 

22 MK_INSTALLATIONS_MULTI_DEST_INSTALL, 

23) 

24from debputy.exceptions import DebputyManifestVariableRequiresDebianDirError 

25from debputy.installations import InstallRule 

26from debputy.maintscript_snippet import DpkgMaintscriptHelperCommand 

27from debputy.manifest_conditions import ( 

28 ManifestCondition, 

29 BinaryPackageContextArchMatchManifestCondition, 

30 BuildProfileMatch, 

31 SourceContextArchMatchManifestCondition, 

32) 

33from debputy.manifest_parser.base_types import ( 

34 FileSystemMode, 

35 StaticFileSystemOwner, 

36 StaticFileSystemGroup, 

37 SymlinkTarget, 

38 FileSystemExactMatchRule, 

39 FileSystemMatchRule, 

40 SymbolicMode, 

41 OctalMode, 

42 FileSystemExactNonDirMatchRule, 

43 BuildEnvironmentDefinition, 

44 DebputyParsedContentStandardConditional, 

45) 

46from debputy.manifest_parser.exceptions import ManifestParseException 

47from debputy.manifest_parser.mapper_code import type_mapper_str2package, PackageSelector 

48from debputy.manifest_parser.parse_hints import DebputyParseHint 

49from debputy.manifest_parser.parser_data import ParserContextData 

50from debputy.manifest_parser.tagging_types import ( 

51 DebputyParsedContent, 

52 TypeMapping, 

53) 

54from debputy.manifest_parser.util import AttributePath, check_integration_mode 

55from debputy.packages import BinaryPackage 

56from debputy.path_matcher import ExactFileSystemPath 

57from debputy.plugin.api import ( 

58 DebputyPluginInitializer, 

59 documented_attr, 

60 reference_documentation, 

61 VirtualPath, 

62 packager_provided_file_reference_documentation, 

63) 

64from debputy.plugin.api.impl import DebputyPluginInitializerProvider 

65from debputy.plugin.api.impl_types import automatic_discard_rule_example, PPFFormatParam 

66from debputy.plugin.api.spec import ( 

67 type_mapping_reference_documentation, 

68 type_mapping_example, 

69 not_integrations, 

70 INTEGRATION_MODE_DH_DEBPUTY_RRR, 

71) 

72from debputy.plugin.api.std_docs import docs_from 

73from debputy.plugins.debputy.binary_package_rules import register_binary_package_rules 

74from debputy.plugins.debputy.discard_rules import ( 

75 _debputy_discard_pyc_files, 

76 _debputy_prune_la_files, 

77 _debputy_prune_doxygen_cruft, 

78 _debputy_prune_binary_debian_dir, 

79 _debputy_prune_info_dir_file, 

80 _debputy_prune_backup_files, 

81 _debputy_prune_vcs_paths, 

82) 

83from debputy.plugins.debputy.manifest_root_rules import register_manifest_root_rules 

84from debputy.plugins.debputy.package_processors import ( 

85 process_manpages, 

86 apply_compression, 

87 clean_la_files, 

88) 

89from debputy.plugins.debputy.service_management import ( 

90 detect_systemd_service_files, 

91 generate_snippets_for_systemd_units, 

92 detect_sysv_init_service_files, 

93 generate_snippets_for_init_scripts, 

94) 

95from debputy.plugins.debputy.shlib_metadata_detectors import detect_shlibdeps 

96from debputy.plugins.debputy.strip_non_determinism import strip_non_determinism 

97from debputy.substitution import VariableContext 

98from debputy.transformation_rules import ( 

99 CreateSymlinkReplacementRule, 

100 TransformationRule, 

101 CreateDirectoryTransformationRule, 

102 RemoveTransformationRule, 

103 MoveTransformationRule, 

104 PathMetadataTransformationRule, 

105 CreateSymlinkPathTransformationRule, 

106) 

107from debputy.util import ( 

108 _normalize_path, 

109 PKGNAME_REGEX, 

110 PKGVERSION_REGEX, 

111 debian_policy_normalize_symlink_target, 

112 active_profiles_match, 

113 _error, 

114 _warn, 

115 _info, 

116 assume_not_none, 

117 manifest_format_doc, 

118 PackageTypeSelector, 

119) 

120 

121_DOCUMENTED_DPKG_ARCH_TYPES = { 

122 "HOST": ( 

123 "installed on", 

124 "The package will be **installed** on this type of machine / system", 

125 ), 

126 "BUILD": ( 

127 "compiled on", 

128 "The compilation of this package will be performed **on** this kind of machine / system", 

129 ), 

130 "TARGET": ( 

131 "cross-compiler output", 

132 "When building a cross-compiler, it will produce output for this kind of machine/system", 

133 ), 

134} 

135 

136_DOCUMENTED_DPKG_ARCH_VARS = { 

137 "ARCH": "Debian's name for the architecture", 

138 "ARCH_ABI": "Debian's name for the architecture ABI", 

139 "ARCH_BITS": "Number of bits in the pointer size", 

140 "ARCH_CPU": "Debian's name for the CPU type", 

141 "ARCH_ENDIAN": "Endianness of the architecture (little/big)", 

142 "ARCH_LIBC": "Debian's name for the libc implementation", 

143 "ARCH_OS": "Debian name for the OS/kernel", 

144 "GNU_CPU": "GNU's name for the CPU", 

145 "GNU_SYSTEM": "GNU's name for the system", 

146 "GNU_TYPE": "GNU system type (GNU_CPU and GNU_SYSTEM combined)", 

147 "MULTIARCH": "Multi-arch tuple", 

148} 

149 

150 

151_NOT_INTEGRATION_RRR = not_integrations(INTEGRATION_MODE_DH_DEBPUTY_RRR) 

152 

153 

154@dataclasses.dataclass(slots=True, frozen=True) 

155class Capability: 

156 value: str 

157 

158 @classmethod 

159 def parse( 

160 cls, 

161 raw_value: str, 

162 _attribute_path: AttributePath, 

163 _parser_context: "ParserContextData", 

164 ) -> "Capability": 

165 return cls(raw_value) 

166 

167 

168@functools.lru_cache 

169def load_libcap() -> tuple[bool, str | None, Callable[[str], bool]]: 

170 cap_library_path = ctypes.util.find_library("cap.so") 

171 has_libcap = False 

172 libcap = None 

173 if cap_library_path: 173 ↛ 180line 173 didn't jump to line 180 because the condition on line 173 was always true

174 try: 

175 libcap = ctypes.cdll.LoadLibrary(cap_library_path) 

176 has_libcap = True 

177 except OSError: 

178 pass 

179 

180 if libcap is None: 180 ↛ 181line 180 didn't jump to line 181 because the condition on line 180 was never true

181 warned = False 

182 

183 def _is_valid_cap(cap: str) -> bool: 

184 nonlocal warned 

185 if not warned: 

186 _info( 

187 "Could not load libcap.so; will not validate capabilities. Use `apt install libcap2` to provide" 

188 " checking of capabilities." 

189 ) 

190 warned = True 

191 return True 

192 

193 else: 

194 # cap_t cap_from_text(const char *path_p) 

195 libcap.cap_from_text.argtypes = [ctypes.c_char_p] 

196 libcap.cap_from_text.restype = ctypes.c_char_p 

197 

198 libcap.cap_free.argtypes = [ctypes.c_void_p] 

199 libcap.cap_free.restype = None 

200 

201 def _is_valid_cap(cap: str) -> bool: 

202 cap_t = libcap.cap_from_text(cap.encode("utf-8")) 

203 ok = cap_t is not None 

204 libcap.cap_free(cap_t) 

205 return ok 

206 

207 return has_libcap, cap_library_path, _is_valid_cap 

208 

209 

210def check_cap_checker() -> Callable[[str, str], None]: 

211 _, libcap_path, is_valid_cap = load_libcap() 

212 

213 seen_cap = set() 

214 

215 def _check_cap(cap: str, definition_source: str) -> None: 

216 if cap not in seen_cap and not is_valid_cap(cap): 

217 seen_cap.add(cap) 

218 cap_path = f" ({libcap_path})" if libcap_path is not None else "" 

219 _warn( 

220 f'The capabilities "{cap}" provided in {definition_source} were not understood by' 

221 f" libcap.so{cap_path}. Please verify you provided the correct capabilities." 

222 f" Note: This warning can be a false-positive if you are targeting a newer libcap.so" 

223 f" than the one installed on this system." 

224 ) 

225 

226 return _check_cap 

227 

228 

229def load_source_variables(variable_context: VariableContext) -> dict[str, str]: 

230 try: 

231 changelog = variable_context.debian_dir.lookup("changelog") 

232 if changelog is None: 

233 raise DebputyManifestVariableRequiresDebianDirError( 

234 "The changelog was not present" 

235 ) 

236 with changelog.open() as fd: 

237 dch = Changelog(fd, max_blocks=2) 

238 except FileNotFoundError as e: 

239 raise DebputyManifestVariableRequiresDebianDirError( 

240 "The changelog was not present" 

241 ) from e 

242 first_entry = dch[0] 

243 first_non_binnmu_entry = dch[0] 

244 if first_non_binnmu_entry.other_pairs.get("binary-only", "no") == "yes": 

245 first_non_binnmu_entry = dch[1] 

246 assert first_non_binnmu_entry.other_pairs.get("binary-only", "no") == "no" 

247 source_version = first_entry.version 

248 epoch = source_version.epoch 

249 upstream_version = source_version.upstream_version 

250 debian_revision = source_version.debian_revision 

251 epoch_upstream = upstream_version 

252 upstream_debian_revision = upstream_version 

253 if epoch is not None and epoch != "": 253 ↛ 255line 253 didn't jump to line 255 because the condition on line 253 was always true

254 epoch_upstream = f"{epoch}:{upstream_version}" 

255 if debian_revision is not None and debian_revision != "": 255 ↛ 258line 255 didn't jump to line 258 because the condition on line 255 was always true

256 upstream_debian_revision = f"{upstream_version}-{debian_revision}" 

257 

258 package = first_entry.package 

259 if package is None: 259 ↛ 260line 259 didn't jump to line 260 because the condition on line 259 was never true

260 _error("Cannot determine the source package name from debian/changelog.") 

261 

262 date = first_entry.date 

263 if date is not None: 263 ↛ 267line 263 didn't jump to line 267 because the condition on line 263 was always true

264 local_time = datetime.strptime(date, "%a, %d %b %Y %H:%M:%S %z") 

265 source_date_epoch = str(int(local_time.timestamp())) 

266 else: 

267 _warn( 

268 "The latest changelog entry does not have a (parsable) date, using current time" 

269 " for SOURCE_DATE_EPOCH" 

270 ) 

271 source_date_epoch = str(int(time.time())) 

272 

273 if first_non_binnmu_entry is not first_entry: 

274 non_binnmu_date = first_non_binnmu_entry.date 

275 if non_binnmu_date is not None: 275 ↛ 279line 275 didn't jump to line 279 because the condition on line 275 was always true

276 local_time = datetime.strptime(non_binnmu_date, "%a, %d %b %Y %H:%M:%S %z") 

277 snd_source_date_epoch = str(int(local_time.timestamp())) 

278 else: 

279 _warn( 

280 "The latest (non-binNMU) changelog entry does not have a (parsable) date, using current time" 

281 " for SOURCE_DATE_EPOCH (for strip-nondeterminism)" 

282 ) 

283 snd_source_date_epoch = source_date_epoch = str(int(time.time())) 

284 else: 

285 snd_source_date_epoch = source_date_epoch 

286 return { 

287 "DEB_SOURCE": package, 

288 "DEB_VERSION": source_version.full_version, 

289 "DEB_VERSION_EPOCH_UPSTREAM": epoch_upstream, 

290 "DEB_VERSION_UPSTREAM_REVISION": upstream_debian_revision, 

291 "DEB_VERSION_UPSTREAM": upstream_version, 

292 "SOURCE_DATE_EPOCH": source_date_epoch, 

293 "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE": str(first_non_binnmu_entry.version), 

294 "_DEBPUTY_SND_SOURCE_DATE_EPOCH": snd_source_date_epoch, 

295 } 

296 

297 

298def initialize_via_private_api(public_api: DebputyPluginInitializer) -> None: 

299 api = cast("DebputyPluginInitializerProvider", public_api) 

300 

301 api.metadata_or_maintscript_detector( 

302 "dpkg-shlibdeps", 

303 # Private because detect_shlibdeps expects private API (hench this cast) 

304 cast("MetadataAutoDetector", detect_shlibdeps), 

305 package_types=PackageTypeSelector.DEB | PackageTypeSelector.UDEB, 

306 ) 

307 register_type_mappings(api) 

308 register_variables_via_private_api(api) 

309 document_builtin_variables(api) 

310 register_automatic_discard_rules(api) 

311 register_special_ppfs(api) 

312 register_install_rules(api) 

313 register_transformation_rules(api) 

314 register_manifest_condition_rules(api) 

315 register_dpkg_conffile_rules(api) 

316 register_processing_steps(api) 

317 register_service_managers(api) 

318 register_manifest_root_rules(api) 

319 register_binary_package_rules(api) 

320 

321 

322def register_type_mappings(api: DebputyPluginInitializerProvider) -> None: 

323 api.register_mapped_type( 

324 TypeMapping(Capability, str, Capability.parse), 

325 reference_documentation=type_mapping_reference_documentation( 

326 description=textwrap.dedent( 

327 """\ 

328 The value is a Linux capability parsable by cap_from_text on the host system. 

329 

330 With `libcap2` installed, `debputy` will attempt to parse the value and provide 

331 warnings if the value cannot be parsed by `libcap2`. However, `debputy` will 

332 currently never emit hard errors for unknown capabilities. 

333 """, 

334 ), 

335 examples=[ 

336 type_mapping_example("cap_chown=p"), 

337 type_mapping_example("cap_chown=ep"), 

338 type_mapping_example("cap_kill-pe"), 

339 type_mapping_example("=ep cap_chown-e cap_kill-ep"), 

340 ], 

341 ), 

342 ) 

343 api.register_mapped_type( 

344 TypeMapping( 

345 FileSystemMatchRule, 

346 str, 

347 FileSystemMatchRule.parse_path_match, 

348 ), 

349 reference_documentation=type_mapping_reference_documentation( 

350 description=textwrap.dedent( 

351 """\ 

352 A generic file system path match with globs. 

353 

354 Manifest variable substitution will be applied and glob expansion will be performed. 

355 

356 The match will be read as one of the following cases: 

357 

358 - Exact path match if there is no globs characters like `usr/bin/debputy` 

359 - A basename glob like `*.txt` or `**/foo` 

360 - A generic path glob otherwise like `usr/lib/*.so*` 

361 

362 Except for basename globs, all matches are always relative to the root directory of 

363 the match, which is typically the package root directory or a search directory. 

364 

365 For basename globs, any path matching that basename beneath the package root directory 

366 or relevant search directories will match. 

367 

368 Please keep in mind that: 

369 

370 * glob patterns often have to be quoted as YAML interpret the glob metacharacter as 

371 an anchor reference. 

372 

373 * Directories can be matched via this type. Whether the rule using this type 

374 recurse into the directory depends on the usage and not this type. Related, if 

375 value for this rule ends with a literal "/", then the definition can *only* match 

376 directories (similar to the shell). 

377 

378 * path matches involving glob expansion are often subject to different rules than 

379 path matches without them. As an example, automatic discard rules does not apply 

380 to exact path matches, but they will filter out glob matches. 

381 """, 

382 ), 

383 examples=[ 

384 type_mapping_example("usr/bin/debputy"), 

385 type_mapping_example("*.txt"), 

386 type_mapping_example("**/foo"), 

387 type_mapping_example("usr/lib/*.so*"), 

388 type_mapping_example("usr/share/foo/data-*/"), 

389 ], 

390 ), 

391 ) 

392 

393 api.register_mapped_type( 

394 TypeMapping( 

395 FileSystemExactMatchRule, 

396 str, 

397 FileSystemExactMatchRule.parse_path_match, 

398 ), 

399 reference_documentation=type_mapping_reference_documentation( 

400 description=textwrap.dedent( 

401 """\ 

402 A file system match that does **not** expand globs. 

403 

404 Manifest variable substitution will be applied. However, globs will not be expanded. 

405 Any glob metacharacters will be interpreted as a literal part of path. 

406 

407 Note that a directory can be matched via this type. Whether the rule using this type 

408 recurse into the directory depends on the usage and is not defined by this type. 

409 Related, if value for this rule ends with a literal "/", then the definition can 

410 *only* match directories (similar to the shell). 

411 """, 

412 ), 

413 examples=[ 

414 type_mapping_example("usr/bin/dpkg"), 

415 type_mapping_example("usr/share/foo/"), 

416 type_mapping_example("usr/share/foo/data.txt"), 

417 ], 

418 ), 

419 ) 

420 

421 api.register_mapped_type( 

422 TypeMapping( 

423 FileSystemExactNonDirMatchRule, 

424 str, 

425 FileSystemExactNonDirMatchRule.parse_path_match, 

426 ), 

427 reference_documentation=type_mapping_reference_documentation( 

428 description=textwrap.dedent( 

429 f"""\ 

430 A file system match that does **not** expand globs and must not match a directory. 

431 

432 Manifest variable substitution will be applied. However, globs will not be expanded. 

433 Any glob metacharacters will be interpreted as a literal part of path. 

434 

435 This is like {FileSystemExactMatchRule.__name__} except that the match will fail if the 

436 provided path matches a directory. Since a directory cannot be matched, it is an error 

437 for any input to end with a "/" as only directories can be matched if the path ends 

438 with a "/". 

439 """, 

440 ), 

441 examples=[ 

442 type_mapping_example("usr/bin/dh_debputy"), 

443 type_mapping_example("usr/share/foo/data.txt"), 

444 ], 

445 ), 

446 ) 

447 

448 api.register_mapped_type( 

449 TypeMapping( 

450 SymlinkTarget, 

451 str, 

452 lambda v, ap, pc: SymlinkTarget.parse_symlink_target( 

453 v, ap, assume_not_none(pc).substitution 

454 ), 

455 ), 

456 reference_documentation=type_mapping_reference_documentation( 

457 description=textwrap.dedent( 

458 """\ 

459 A symlink target. 

460 

461 Manifest variable substitution will be applied. This is distinct from an exact file 

462 system match in that a symlink target is not relative to the package root by default 

463 (explicitly prefix for "/" for absolute path targets) 

464 

465 Note that `debputy` will policy normalize symlinks when assembling the deb, so 

466 use of relative or absolute symlinks comes down to preference. 

467 """, 

468 ), 

469 examples=[ 

470 type_mapping_example("../foo"), 

471 type_mapping_example("/usr/share/doc/bar"), 

472 ], 

473 ), 

474 ) 

475 

476 api.register_mapped_type( 

477 TypeMapping( 

478 StaticFileSystemOwner, 

479 Union[int, str], 

480 lambda v, ap, _: StaticFileSystemOwner.from_manifest_value(v, ap), 

481 ), 

482 reference_documentation=type_mapping_reference_documentation( 

483 description=textwrap.dedent( 

484 """\ 

485 File system owner reference that is part of the passwd base data (such as "root"). 

486 

487 The group can be provided in either of the following three forms: 

488 

489 * A name (recommended), such as "root" 

490 * The UID in the form of an integer (that is, no quoting), such as 0 (for "root") 

491 * The name and the UID separated by colon such as "root:0" (for "root"). 

492 

493 Note in the last case, the `debputy` will validate that the name and the UID match. 

494 

495 Some owners (such as "nobody") are deliberately disallowed. 

496 """ 

497 ), 

498 examples=[ 

499 type_mapping_example("root"), 

500 type_mapping_example(0), 

501 type_mapping_example("root:0"), 

502 type_mapping_example("bin"), 

503 ], 

504 ), 

505 ) 

506 api.register_mapped_type( 

507 TypeMapping( 

508 StaticFileSystemGroup, 

509 Union[int, str], 

510 lambda v, ap, _: StaticFileSystemGroup.from_manifest_value(v, ap), 

511 ), 

512 reference_documentation=type_mapping_reference_documentation( 

513 description=textwrap.dedent( 

514 """\ 

515 File system group reference that is part of the passwd base data (such as "root"). 

516 

517 The group can be provided in either of the following three forms: 

518 

519 * A name (recommended), such as "root" 

520 * The GID in the form of an integer (that is, no quoting), such as 0 (for "root") 

521 * The name and the GID separated by colon such as "root:0" (for "root"). 

522 

523 Note in the last case, the `debputy` will validate that the name and the GID match. 

524 

525 Some owners (such as "nobody") are deliberately disallowed. 

526 """ 

527 ), 

528 examples=[ 

529 type_mapping_example("root"), 

530 type_mapping_example(0), 

531 type_mapping_example("root:0"), 

532 type_mapping_example("tty"), 

533 ], 

534 ), 

535 ) 

536 

537 api.register_mapped_type( 

538 TypeMapping( 

539 BinaryPackage, 

540 str, 

541 type_mapper_str2package, 

542 ), 

543 reference_documentation=type_mapping_reference_documentation( 

544 description="Name of a package in debian/control", 

545 ), 

546 ) 

547 

548 api.register_mapped_type( 

549 TypeMapping( 

550 PackageSelector, 

551 str, 

552 PackageSelector.parse, 

553 ), 

554 reference_documentation=type_mapping_reference_documentation( 

555 description=textwrap.dedent( 

556 """\ 

557 Match a package or set of a packages from debian/control 

558 

559 The simplest package selector is the name of a binary package from `debian/control`. 

560 However, selections can also match multiple packages based on a given criteria, such 

561 as `arch:all`/`arch:any` (matches packages where the `Architecture` field is set to 

562 `all` or is not set to `all` respectively) or `package-type:deb` / `package-type:udeb` 

563 (matches packages where `Package-Type` is set to `deb` or is set to `udeb` 

564 respectively). 

565 """ 

566 ), 

567 ), 

568 ) 

569 

570 api.register_mapped_type( 

571 TypeMapping( 

572 FileSystemMode, 

573 str, 

574 lambda v, ap, _: FileSystemMode.parse_filesystem_mode(v, ap), 

575 ), 

576 reference_documentation=type_mapping_reference_documentation( 

577 description="A file system mode either in the form of an octal mode or a symbolic mode.", 

578 examples=[ 

579 type_mapping_example("a+x"), 

580 type_mapping_example("u=rwX,go=rX"), 

581 type_mapping_example("0755"), 

582 ], 

583 ), 

584 ) 

585 api.register_mapped_type( 

586 TypeMapping( 

587 OctalMode, 

588 str, 

589 lambda v, ap, _: OctalMode.parse_filesystem_mode(v, ap), 

590 ), 

591 reference_documentation=type_mapping_reference_documentation( 

592 description="A file system mode using the octal mode representation. Must always be a provided as a string (that is, quoted).", 

593 examples=[ 

594 type_mapping_example("0644"), 

595 type_mapping_example("0755"), 

596 ], 

597 ), 

598 ) 

599 api.register_mapped_type( 

600 TypeMapping( 

601 BuildEnvironmentDefinition, 

602 str, 

603 lambda v, ap, pc: pc.resolve_build_environment(v, ap), 

604 ), 

605 reference_documentation=type_mapping_reference_documentation( 

606 description="Reference to a build environment defined in `build-environments`", 

607 ), 

608 ) 

609 

610 

611def register_service_managers( 

612 api: DebputyPluginInitializerProvider, 

613) -> None: 

614 api.service_provider( 

615 "systemd", 

616 detect_systemd_service_files, 

617 generate_snippets_for_systemd_units, 

618 ) 

619 api.service_provider( 

620 "sysvinit", 

621 detect_sysv_init_service_files, 

622 generate_snippets_for_init_scripts, 

623 ) 

624 

625 

626def register_automatic_discard_rules( 

627 api: DebputyPluginInitializerProvider, 

628) -> None: 

629 api.automatic_discard_rule( 

630 "python-cache-files", 

631 _debputy_discard_pyc_files, 

632 rule_reference_documentation="Discards any *.pyc, *.pyo files and any __pycache__ directories", 

633 examples=automatic_discard_rule_example( 

634 (".../foo.py", False), 

635 ".../__pycache__/", 

636 ".../__pycache__/...", 

637 ".../foo.pyc", 

638 ".../foo.pyo", 

639 ), 

640 ) 

641 api.automatic_discard_rule( 

642 "la-files", 

643 _debputy_prune_la_files, 

644 rule_reference_documentation="Discards any file with the extension .la beneath the directory /usr/lib", 

645 examples=automatic_discard_rule_example( 

646 "usr/lib/libfoo.la", 

647 ("usr/lib/libfoo.so.1.0.0", False), 

648 ), 

649 ) 

650 api.automatic_discard_rule( 

651 "backup-files", 

652 _debputy_prune_backup_files, 

653 rule_reference_documentation="Discards common back up files such as foo~, foo.bak or foo.orig", 

654 examples=( 

655 automatic_discard_rule_example( 

656 ".../foo~", 

657 ".../foo.orig", 

658 ".../foo.rej", 

659 ".../DEADJOE", 

660 ".../.foo.sw.", 

661 ), 

662 ), 

663 ) 

664 api.automatic_discard_rule( 

665 "version-control-paths", 

666 _debputy_prune_vcs_paths, 

667 rule_reference_documentation="Discards common version control paths such as .git, .gitignore, CVS, etc.", 

668 examples=automatic_discard_rule_example( 

669 ("tools/foo", False), 

670 ".../CVS/", 

671 ".../CVS/...", 

672 ".../.gitignore", 

673 ".../.gitattributes", 

674 ".../.git/", 

675 ".../.git/...", 

676 ), 

677 ) 

678 api.automatic_discard_rule( 

679 "gnu-info-dir-file", 

680 _debputy_prune_info_dir_file, 

681 rule_reference_documentation="Discards the /usr/share/info/dir file (causes package file conflicts)", 

682 examples=automatic_discard_rule_example( 

683 "usr/share/info/dir", 

684 ("usr/share/info/foo.info", False), 

685 ("usr/share/info/dir.info", False), 

686 ("usr/share/random/case/dir", False), 

687 ), 

688 ) 

689 api.automatic_discard_rule( 

690 "debian-dir", 

691 _debputy_prune_binary_debian_dir, 

692 rule_reference_documentation="(Implementation detail) Discards any DEBIAN directory to avoid it from appearing" 

693 " literally in the file listing", 

694 examples=( 

695 automatic_discard_rule_example( 

696 "DEBIAN/", 

697 "DEBIAN/control", 

698 ("usr/bin/foo", False), 

699 ("usr/share/DEBIAN/foo", False), 

700 ), 

701 ), 

702 ) 

703 api.automatic_discard_rule( 

704 "doxygen-cruft-files", 

705 _debputy_prune_doxygen_cruft, 

706 rule_reference_documentation="Discards cruft files generated by doxygen", 

707 examples=automatic_discard_rule_example( 

708 ("usr/share/doc/foo/api/doxygen.css", False), 

709 ("usr/share/doc/foo/api/doxygen.svg", False), 

710 ("usr/share/doc/foo/api/index.html", False), 

711 "usr/share/doc/foo/api/.../cruft.map", 

712 "usr/share/doc/foo/api/.../cruft.md5", 

713 ), 

714 ) 

715 

716 

717def register_processing_steps(api: DebputyPluginInitializerProvider) -> None: 

718 api.package_processor("manpages", process_manpages) 

719 api.package_processor("clean-la-files", clean_la_files) 

720 # strip-non-determinism makes assumptions about the PackageProcessingContext implementation 

721 api.package_processor( 

722 "strip-nondeterminism", 

723 cast("Any", strip_non_determinism), 

724 depends_on_processor=["manpages"], 

725 ) 

726 api.package_processor( 

727 "compression", 

728 apply_compression, 

729 depends_on_processor=["manpages", "strip-nondeterminism"], 

730 ) 

731 

732 

733def register_variables_via_private_api(api: DebputyPluginInitializerProvider) -> None: 

734 api.manifest_variable_provider( 

735 load_source_variables, 

736 { 

737 "DEB_SOURCE": "Name of the source package (`dpkg-parsechangelog -SSource`)", 

738 "DEB_VERSION": "Version from the top most changelog entry (`dpkg-parsechangelog -SVersion`)", 

739 "DEB_VERSION_EPOCH_UPSTREAM": "Version from the top most changelog entry *without* the Debian revision", 

740 "DEB_VERSION_UPSTREAM_REVISION": "Version from the top most changelog entry *without* the epoch", 

741 "DEB_VERSION_UPSTREAM": "Upstream version from the top most changelog entry (that is, *without* epoch and Debian revision)", 

742 "SOURCE_DATE_EPOCH": textwrap.dedent( 

743 """\ 

744 Timestamp from the top most changelog entry (`dpkg-parsechangelog -STimestamp`) 

745 Please see <https://reproducible-builds.org/docs/source-date-epoch/> for the full definition of 

746 this variable. 

747 """ 

748 ), 

749 "_DEBPUTY_INTERNAL_NON_BINNMU_SOURCE": None, 

750 "_DEBPUTY_SND_SOURCE_DATE_EPOCH": None, 

751 }, 

752 ) 

753 

754 

755def document_builtin_variables(api: DebputyPluginInitializerProvider) -> None: 

756 api.document_builtin_variable( 

757 "PACKAGE", 

758 "Name of the binary package (only available in binary context)", 

759 is_context_specific=True, 

760 ) 

761 

762 arch_types = _DOCUMENTED_DPKG_ARCH_TYPES 

763 

764 for arch_type, (arch_type_tag, arch_type_doc) in arch_types.items(): 

765 for arch_var, arch_var_doc in _DOCUMENTED_DPKG_ARCH_VARS.items(): 

766 full_var = f"DEB_{arch_type}_{arch_var}" 

767 documentation = textwrap.dedent( 

768 f"""\ 

769 {arch_var_doc} ({arch_type_tag}) 

770 This variable describes machine information used when the package is compiled and assembled. 

771 * Machine type: {arch_type_doc} 

772 * Value description: {arch_var_doc} 

773 

774 The value is the output of: `dpkg-architecture -q{full_var}` 

775 """ 

776 ) 

777 api.document_builtin_variable( 

778 full_var, 

779 documentation, 

780 is_for_special_case=arch_type != "HOST", 

781 ) 

782 

783 

784def _format_docbase_filename( 

785 path_format: str, 

786 format_param: PPFFormatParam, 

787 docbase_file: VirtualPath, 

788) -> str: 

789 with docbase_file.open() as fd: 

790 content = Deb822(fd) 

791 proper_name = content["Document"] 

792 if proper_name is not None: 792 ↛ 795line 792 didn't jump to line 795 because the condition on line 792 was always true

793 format_param["name"] = proper_name 

794 else: 

795 _warn( 

796 f"The docbase file {docbase_file.fs_path} is missing the Document field" 

797 ) 

798 return path_format.format(**format_param) 

799 

800 

801def register_special_ppfs(api: DebputyPluginInitializerProvider) -> None: 

802 api.packager_provided_file( 

803 "doc-base", 

804 "/usr/share/doc-base/{owning_package}.{name}", 

805 format_callback=_format_docbase_filename, 

806 ) 

807 

808 api.packager_provided_file( 

809 "shlibs", 

810 "DEBIAN/shlibs", 

811 allow_name_segment=False, 

812 reservation_only=True, 

813 reference_documentation=packager_provided_file_reference_documentation( 

814 format_documentation_uris=["man:deb-shlibs(5)"], 

815 ), 

816 ) 

817 api.packager_provided_file( 

818 "symbols", 

819 "DEBIAN/symbols", 

820 allow_name_segment=False, 

821 allow_architecture_segment=True, 

822 reservation_only=True, 

823 reference_documentation=packager_provided_file_reference_documentation( 

824 format_documentation_uris=["man:deb-symbols(5)"], 

825 ), 

826 ) 

827 api.packager_provided_file( 

828 "conffiles", 

829 "DEBIAN/conffiles", 

830 allow_name_segment=False, 

831 allow_architecture_segment=True, 

832 reservation_only=True, 

833 ) 

834 api.packager_provided_file( 

835 "templates", 

836 "DEBIAN/templates", 

837 allow_name_segment=False, 

838 allow_architecture_segment=False, 

839 reservation_only=True, 

840 ) 

841 api.packager_provided_file( 

842 "alternatives", 

843 "DEBIAN/alternatives", 

844 allow_name_segment=False, 

845 allow_architecture_segment=True, 

846 reservation_only=True, 

847 ) 

848 

849 

850def register_install_rules(api: DebputyPluginInitializerProvider) -> None: 

851 api.pluggable_manifest_rule( 

852 InstallRule, 

853 MK_INSTALLATIONS_INSTALL, 

854 ParsedInstallRule, 

855 _install_rule_handler, 

856 source_format=_with_alt_form(ParsedInstallRuleSourceFormat), 

857 inline_reference_documentation=reference_documentation( 

858 title="Generic install (`install`)", 

859 description=textwrap.dedent( 

860 """\ 

861 The generic `install` rule can be used to install arbitrary paths into packages 

862 and is *similar* to how `dh_install` from debhelper works. It is a two "primary" uses. 

863 

864 1) The classic "install into directory" similar to the standard `dh_install` 

865 2) The "install as" similar to `dh-exec`'s `foo => bar` feature. 

866 

867 The `install` rule installs a path exactly once into each package it acts on. In 

868 the rare case that you want to install the same source *multiple* times into the 

869 *same* packages, please have a look at `{MULTI_DEST_INSTALL}`. 

870 """.format( 

871 MULTI_DEST_INSTALL=MK_INSTALLATIONS_MULTI_DEST_INSTALL 

872 ) 

873 ), 

874 non_mapping_description=textwrap.dedent( 

875 """\ 

876 When the input is a string or a list of string, then that value is used as shorthand 

877 for `source` or `sources` (respectively). This form can only be used when `into` is 

878 not required. 

879 """ 

880 ), 

881 attributes=[ 

882 documented_attr( 

883 ["source", "sources"], 

884 textwrap.dedent( 

885 """\ 

886 A path match (`source`) or a list of path matches (`sources`) defining the 

887 source path(s) to be installed. The path match(es) can use globs. Each match 

888 is tried against default search directories. 

889 - When a symlink is matched, then the symlink (not its target) is installed 

890 as-is. When a directory is matched, then the directory is installed along 

891 with all the contents that have not already been installed somewhere. 

892 """ 

893 ), 

894 ), 

895 documented_attr( 

896 "dest_dir", 

897 textwrap.dedent( 

898 """\ 

899 A path defining the destination *directory*. The value *cannot* use globs, but can 

900 use substitution. If neither `as` nor `dest-dir` is given, then `dest-dir` defaults 

901 to the directory name of the `source`. 

902 """ 

903 ), 

904 ), 

905 documented_attr( 

906 "into", 

907 textwrap.dedent( 

908 """\ 

909 Either a package name or a list of package names for which these paths should be 

910 installed. This key is conditional on whether there are multiple binary packages listed 

911 in `debian/control`. When there is only one binary package, then that binary is the 

912 default for `into`. Otherwise, the key is required. 

913 """ 

914 ), 

915 ), 

916 documented_attr( 

917 "install_as", 

918 textwrap.dedent( 

919 """\ 

920 A path defining the path to install the source as. This is a full path. This option 

921 is mutually exclusive with `dest-dir` and `sources` (but not `source`). When `as` is 

922 given, then `source` must match exactly one "not yet matched" path. 

923 """ 

924 ), 

925 ), 

926 *docs_from(DebputyParsedContentStandardConditional), 

927 ], 

928 reference_documentation_url=manifest_format_doc("generic-install-install"), 

929 ), 

930 ) 

931 api.pluggable_manifest_rule( 

932 InstallRule, 

933 [ 

934 MK_INSTALLATIONS_INSTALL_DOCS, 

935 "install-doc", 

936 ], 

937 ParsedInstallRule, 

938 _install_docs_rule_handler, 

939 source_format=_with_alt_form(ParsedInstallDocRuleSourceFormat), 

940 inline_reference_documentation=reference_documentation( 

941 title="Install documentation (`install-docs`)", 

942 description=textwrap.dedent( 

943 """\ 

944 This install rule resemble that of `dh_installdocs`. It is a shorthand over the generic 

945 `install` rule with the following key features: 

946 

947 1) The default `dest-dir` is to use the package's documentation directory (usually something 

948 like `/usr/share/doc/{{PACKAGE}}`, though it respects the "main documentation package" 

949 recommendation from Debian Policy). The `dest-dir` or `as` can be set in case the 

950 documentation in question goes into another directory or with a concrete path. In this 

951 case, it is still "better" than `install` due to the remaining benefits. 

952 2) The rule comes with pre-defined conditional logic for skipping the rule under 

953 `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself. 

954 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb` 

955 package listed in `debian/control`. 

956 

957 With these two things in mind, it behaves just like the `install` rule. 

958 

959 Note: It is often worth considering to use a more specialized version of the `install-docs` 

960 rule when one such is available. If you are looking to install an example or a man page, 

961 consider whether `install-examples` or `install-man` might be a better fit for your 

962 use-case. 

963 """ 

964 ), 

965 non_mapping_description=textwrap.dedent( 

966 """\ 

967 When the input is a string or a list of string, then that value is used as shorthand 

968 for `source` or `sources` (respectively). This form can only be used when `into` is 

969 not required. 

970 """ 

971 ), 

972 attributes=[ 

973 documented_attr( 

974 ["source", "sources"], 

975 textwrap.dedent( 

976 """\ 

977 A path match (`source`) or a list of path matches (`sources`) defining the 

978 source path(s) to be installed. The path match(es) can use globs. Each match 

979 is tried against default search directories. 

980 - When a symlink is matched, then the symlink (not its target) is installed 

981 as-is. When a directory is matched, then the directory is installed along 

982 with all the contents that have not already been installed somewhere. 

983 

984 - **CAVEAT**: Specifying `source: examples` where `examples` resolves to a 

985 directory for `install-examples` will give you an `examples/examples`