DH_LINKTREE(1)							  dh_linktree 0.3						    DH_LINKTREE(1)

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 aXX 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>

dh_linktree 0.3 						    2012-06-08							    DH_LINKTREE(1)