DH_INSTALLEXAMPLES(1)

📦
version 14.5ubuntu1 · 12 versions
, in ubuntu stonking

💖 DH_INSTALLEXAMPLES — bestie, let's install some examples 💖

okay so this is a page from the debhelper manual, and it's all about dh_installexamples. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

dh_installexamples — the tool that puts your example files into your package build directories. she's giving "show them how it's done" energy. 👑

🌸 SYNOPSIS 🌸

dh_installexamples [debhelper options] [-A] [-Xitem] [file ...]

🦋 DESCRIPTION 🦋

so like, dh_installexamples is a debhelper program and her whole job — her entire main character arc — is installing examples into usr/share/doc/package/examples inside your package build directories. that's it. that's the gig. 💅

and here's a lil something you need to know: starting from debhelper compatibility level 11 on, dh_install will fall back to looking in debian/tmp for files if it doesn't find them in the current directory (or wherever you told it to look with --sourcedir). so it's got a backup plan. she's prepared. ✨

🎀 FILES 🎀

  • debian/package.examples — this file lists the example files or directories you want installed. iykyk.

real talk though: if upstream ships an examples directory, you're usually gonna want to write examples/* in this file instead of just examples. why?? because the plain examples would create /usr/share/doc/package/examples/examples, which is lowkey never what you actually want. nested examples directories?? it's giving redundant. 🙈

also it supports substitution variables in compat 13 and later, as documented over in debhelper(7). slay.

🧚 OPTIONS 🧚

  • -A, --all — install any files specified by the command line parameters in ALL packages acted on. all of them. every single one. no cap.
  • --sourcedir=dir — look in the directory dir for files to be installed. heads up bestie, this option requires compat 11 or later — in compat 10 or earlier it's just silently ignored. 💀
⚠️ and no, this is not the same as the --sourcedirectory option that the dh_auto_* commands use. don't mix them up, they're different girlies. also, you rarely even need this option, because dh_installexamples automatically looks for files in debian/tmp in debhelper compatibility level 11 and above. so like, chill. 🫶
  • --doc-main-package=main-package — set the main package for a documentation package. this is used to install the documentation of the documentation package into /usr/share/doc/main-package, as recommended by the Debian policy manual 3.9.7 in §12.3. very official. very demure. 📜

in compat 11 (or later), this option is only useful if debhelper's auto-detection of the main package is wrong. it can also be used to silence a warning from debhelper when the auto-detection fails but the default happens to be correct. so basically it's the "shhh, i got this" button. 🤫

🚨 this option cannot be used when dh_installexamples is instructed to act on multiple packages. if you need it, you'll generally need to combine it with -p to make sure exactly one package is acted on. one package. singular. periodt.

the X-Doc-Main-Package field can be used instead since debhelper/13.28. it has similar semantics but doesn't require command line options — so it's the low-effort, high-reward version. iconic. 🌈

  • -Xitem, --exclude=item — exclude files that contain item anywhere in their filename from being installed. bye bye, you're not invited. 👋
  • file ... — install these files (or directories) as examples into the first package acted on. (or into all packages if -A is specified.) so it's first-come-first-served unless you say otherwise. ✨

⭐ NOTES ⭐

okay important vibes check: dh_installexamples will happily copy entire directory hierarchies if you ask her to (similar to cp -a). if it's asked to install a directory, it installs the complete contents of the directory. all of it. every last file. she does not do things halfway. 🔥

⚠️ so maybe don't point her at a giant directory unless that's actually the plan, bestie.

💜 SEE ALSO 💜

this program is a part of debhelper. one big happy family. 🫶

👑 AUTHOR 👑

Joey Hess <joeyh@debian.org>

okay that's the whole page, you're officially educated, go forth and install those examples 💅✨

much love from debhelper 14.5ubuntu1, dated 2026-09-21 — catch you on the next man page, bestie 💖🎀🦋

📦 where this page comes from