NAME¶
dh_linktree - create symlink trees to embed files from other packages
SYNOPSIS¶
dh_linktree [
debhelper options] [
-A]
[
-Xitem] [
action source destination ...]
DESCRIPTION¶
dh_linktree is a debhelper program that creates symlink trees in package
build directories. The symlinks points to files provided by other packages and
which have to be present during build. As such you have to put the packages
providing the destination files in the build dependencies. For any symlink it
creates, it will add to
${misc:Depends} the dependency that is required
to ensure that the target of the symlink is available.
RATIONALE¶
This tool has been developed to handle the case of embedded libraries written in
interpreted languages (javascript, PHP, etc.). You usually want to replace the
embedded copy by the packaged one except if they are not compatible. Since
both versions evolve separately, you might have to frequently switch between
the embedded version and the packaged one.
If the embedded library had been replaced by a symlink to the top-level
directory, you would have to add code to the preinst/postinst every time that
you switch from one to the other (to replace the real directory with a symlink
and vice-versa). With a symlink tree, dpkg is doing everything by itself.
Since symlink trees are created statically at build-time, they are not very
future-proof and have a risk to miss some files introduced by a newer version
of the package providing the file tree which is duplicated. That's why the
generated dependencies generally ensure that the same upstream version be used
at run-time than at build-time.
USAGE¶
dh_linktree accepts arguments by set of 3. One action followed by source
and destination file/directories. Symlinking files works just like
dh_link but symlinking directories will recreate the same directory
hierarchy and all individual files will be turned into symlinks.
The source files are the already existing files that will be symlinked from. The
destination files are the symlinks that will be created.
Be sure you
do specify the full filename to both the source and
destination files (unlike what you would do if you were using something like
ln(1)).
dh_linktree will generate symlinks that comply with Debian policy:
absolute when policy says they should be absolute, and relative links with as
short a path as possible. It will also create any subdirectories it needs to
to put the symlinks in.
Note that
dh_linktree will not be executed automatically by
dh,
you need to use
dh $@ --with linktree to get it hooked in the list of
dh_* commands automatically executed by
dh.
FILES¶
- debian/package.linktrees
- Lists source and destination trees to be symlinked. Each line consists of
3 fields: the action, the source directory, the destination directory.
should be put on its own line, with the source and destination separated
by whitespace.
OPTIONS¶
- -Xitem, --exclude=item
- Do not create symlinks for files that contain item anywhere in
their filename.
- action source destination ...
- If the action is "embed" create a symlink tree named
destination with all files within it pointing to the corresponding
file in source. It generates a strong dependency ("exactly
same upstream version").
The "deduplicate" action will not create new files but it will
replace existing files in the destination directory with symlinks to the
corresponding source file provided that both files have the same content.
It generates a strong dependency.
The "replace" action is like "deduplicate" except that
it does replace existing files even if their content is different from the
content of the source files. It generates a weak dependency ("at
least the current upstream version") on the basis that you already
assume that both version are compatible, otherwise you would have used
"deduplicate" or "embed".
EXAMPLES¶
dh_linktree embed usr/share/javascript/jquery usr/share/wordpress/plugin-jquery
Make
plugin-jquery be a symlink tree to
jquery.
ERRORS¶
dpkg-query: no path found matching pattern /some/file.
[...]
dh_linktree: error: dpkg --search -- /some/file [...] gave error exit status 1
You get this error when the source tree contains files (here
/some/file)
that are not managed by dpkg.
dh_linktree can't generate a correct
dependency for a file that is unknown to dpkg and thus fails.
SEE ALSO¶
debhelper(7)
This program is a part of debhelper.
AUTHOR¶
Raphael Hertzog <hertzog@debian.org> Joey Hess
<joeyh@debian.org>