509 lines
21 KiB
Groff
509 lines
21 KiB
Groff
|
.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
. ds C`
|
||
|
|
. ds C'
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.\"
|
||
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
||
|
|
.de IX
|
||
|
|
..
|
||
|
|
.nr rF 0
|
||
|
|
.if \n(.g .if rF .nr rF 1
|
||
|
|
.if (\n(rF:(\n(.g==0)) \{
|
||
|
|
. if \nF \{
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. if !\nF==2 \{
|
||
|
|
. nr % 0
|
||
|
|
. nr F 2
|
||
|
|
. \}
|
||
|
|
. \}
|
||
|
|
.\}
|
||
|
|
.rr rF
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "IO::FILE=IO(0X81D9F0) 1"
|
||
|
|
.TH IO::FILE=IO(0X81D9F0) 1 "2015-11-09" "perl v5.20.1" "User Contributed Perl Documentation"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "NAME"
|
||
|
|
stow \- software package installation manager
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
stow [ options ] package ...
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
This manual page describes \s-1GNU\s0 Stow 2.2.2, a program for managing
|
||
|
|
the installation of software packages. This is not the definitive
|
||
|
|
documentation for stow; for that, see the info manual.
|
||
|
|
.PP
|
||
|
|
Stow is a tool for managing the installation of multiple software
|
||
|
|
packages in the same run-time directory tree. One historical
|
||
|
|
difficulty of this task has been the need to administer, upgrade,
|
||
|
|
install, and remove files in independent packages without confusing
|
||
|
|
them with other files sharing the same filesystem space. For instance,
|
||
|
|
it is common to install Perl and Emacs in \fI/usr/local\fR. When one
|
||
|
|
does so, one winds up (as of Perl 4.036 and Emacs 19.22) with the
|
||
|
|
following files in \fI/usr/local/man/man1\fR: \fIa2p.1\fR; \fIctags.1\fR;
|
||
|
|
\&\fIemacs.1\fR; \fIetags.1\fR; \fIh2ph.1\fR; \fIperl.1\fR; and \fIs2p.1\fR. Now
|
||
|
|
suppose it's time to uninstall Perl. Which man pages get removed?
|
||
|
|
Obviously \fIperl.1\fR is one of them, but it should not be the
|
||
|
|
administrator's responsibility to memorize the ownership of individual
|
||
|
|
files by separate packages.
|
||
|
|
.PP
|
||
|
|
The approach used by Stow is to install each package into its own
|
||
|
|
tree, then use symbolic links to make it appear as though the files
|
||
|
|
are installed in the common tree. Administration can be performed in
|
||
|
|
the package's private tree in isolation from clutter from other
|
||
|
|
packages. Stow can then be used to update the symbolic links. The
|
||
|
|
structure of each private tree should reflect the desired structure in
|
||
|
|
the common tree; i.e. (in the typical case) there should be a \fIbin\fR
|
||
|
|
directory containing executables, a \fIman/man1\fR directory containing
|
||
|
|
section 1 man pages, and so on.
|
||
|
|
.PP
|
||
|
|
Stow was inspired by Carnegie Mellon's Depot program, but is
|
||
|
|
substantially simpler and safer. Whereas Depot required database files
|
||
|
|
to keep things in sync, Stow stores no extra state between runs, so
|
||
|
|
there's no danger (as there was in Depot) of mangling directories when
|
||
|
|
file hierarchies don't match the database. Also unlike Depot, Stow
|
||
|
|
will never delete any files, directories, or links that appear in a
|
||
|
|
Stow directory (e.g., \fI/usr/local/stow/emacs\fR), so it's always
|
||
|
|
possible to rebuild the target tree (e.g., \fI/usr/local\fR).
|
||
|
|
.SH "TERMINOLOGY"
|
||
|
|
.IX Header "TERMINOLOGY"
|
||
|
|
A \*(L"package\*(R" is a related collection of files and directories that
|
||
|
|
you wish to administer as a unit \*(-- e.g., Perl or Emacs \*(-- and that
|
||
|
|
needs to be installed in a particular directory structure \*(-- e.g.,
|
||
|
|
with \fIbin\fR, \fIlib\fR, and \fIman\fR subdirectories.
|
||
|
|
.PP
|
||
|
|
A \*(L"target directory\*(R" is the root of a tree in which one or more
|
||
|
|
packages wish to \fBappear\fR to be installed. A common, but by no means
|
||
|
|
the only such location is \fI/usr/local\fR. The examples in this manual
|
||
|
|
page will use \fI/usr/local\fR as the target directory.
|
||
|
|
.PP
|
||
|
|
A \*(L"stow directory\*(R" is the root of a tree containing separate
|
||
|
|
packages in private subtrees. When Stow runs, it uses the current
|
||
|
|
directory as the default stow directory. The examples in this manual
|
||
|
|
page will use \fI/usr/local/stow\fR as the stow directory, so that
|
||
|
|
individual packages will be, for example, \fI/usr/local/stow/perl\fR and
|
||
|
|
\&\fI/usr/local/stow/emacs\fR.
|
||
|
|
.PP
|
||
|
|
An \*(L"installation image\*(R" is the layout of files and directories
|
||
|
|
required by a package, relative to the target directory. Thus, the
|
||
|
|
installation image for Perl includes: a \fIbin\fR directory containing
|
||
|
|
\&\fIperl\fR and \fIa2p\fR (among others); an \fIinfo\fR directory containing
|
||
|
|
Texinfo documentation; a \fIlib/perl\fR directory containing Perl
|
||
|
|
libraries; and a \fIman/man1\fR directory containing man pages.
|
||
|
|
.PP
|
||
|
|
A \*(L"package directory\*(R" is the root of a tree containing the
|
||
|
|
installation image for a particular package. Each package directory
|
||
|
|
must reside in a stow directory \*(-- e.g., the package directory
|
||
|
|
\&\fI/usr/local/stow/perl\fR must reside in the stow directory
|
||
|
|
\&\fI/usr/local/stow\fR. The \*(L"name\*(R" of a package is the name of its
|
||
|
|
directory within the stow directory \*(-- e.g., \fIperl\fR.
|
||
|
|
.PP
|
||
|
|
Thus, the Perl executable might reside in
|
||
|
|
\&\fI/usr/local/stow/perl/bin/perl\fR, where \fI/usr/local\fR is the target
|
||
|
|
directory, \fI/usr/local/stow\fR is the stow directory,
|
||
|
|
\&\fI/usr/local/stow/perl\fR is the package directory, and \fIbin/perl\fR
|
||
|
|
within is part of the installation image.
|
||
|
|
.PP
|
||
|
|
A \*(L"symlink\*(R" is a symbolic link. A symlink can be \*(L"relative\*(R" or
|
||
|
|
\&\*(L"absolute\*(R". An absolute symlink names a full path; that is, one
|
||
|
|
starting from \fI/\fR. A relative symlink names a relative path; that
|
||
|
|
is, one not starting from \fI/\fR. The target of a relative symlink is
|
||
|
|
computed starting from the symlink's own directory. Stow only creates
|
||
|
|
relative symlinks.
|
||
|
|
.SH "OPTIONS"
|
||
|
|
.IX Header "OPTIONS"
|
||
|
|
The stow directory is assumed to be the value of the \f(CW\*(C`STOW_DIR\*(C'\fR
|
||
|
|
environment variable or if unset the current directory, and the target
|
||
|
|
directory is assumed to be the parent of the current directory (so it
|
||
|
|
is typical to execute \fIstow\fR from the directory \fI/usr/local/stow\fR).
|
||
|
|
Each \fIpackage\fR given on the command line is the name of a package in
|
||
|
|
the stow directory (e.g., \fIperl\fR). By default, they are installed
|
||
|
|
into the target directory (but they can be deleted instead using
|
||
|
|
\&\f(CW\*(C`\-D\*(C'\fR).
|
||
|
|
.IP "\-n" 4
|
||
|
|
.IX Item "-n"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-no" 4
|
||
|
|
.IX Item "--no"
|
||
|
|
.PD
|
||
|
|
Do not perform any operations that modify the filesystem; merely show
|
||
|
|
what would happen.
|
||
|
|
.IP "\-d \s-1DIR\s0" 4
|
||
|
|
.IX Item "-d DIR"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-dir=DIR" 4
|
||
|
|
.IX Item "--dir=DIR"
|
||
|
|
.PD
|
||
|
|
Set the stow directory to \f(CW\*(C`DIR\*(C'\fR instead of the current directory.
|
||
|
|
This also has the effect of making the default target directory be the
|
||
|
|
parent of \f(CW\*(C`DIR\*(C'\fR.
|
||
|
|
.IP "\-t \s-1DIR\s0" 4
|
||
|
|
.IX Item "-t DIR"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-target=DIR" 4
|
||
|
|
.IX Item "--target=DIR"
|
||
|
|
.PD
|
||
|
|
Set the target directory to \f(CW\*(C`DIR\*(C'\fR instead of the parent of the stow
|
||
|
|
directory.
|
||
|
|
.IP "\-v" 4
|
||
|
|
.IX Item "-v"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-verbose[=N]" 4
|
||
|
|
.IX Item "--verbose[=N]"
|
||
|
|
.PD
|
||
|
|
Send verbose output to standard error describing what Stow is
|
||
|
|
doing. Verbosity levels are 0, 1, 2, 3, and 4; 0 is the default.
|
||
|
|
Using \f(CW\*(C`\-v\*(C'\fR or \f(CW\*(C`\-\-verbose\*(C'\fR increases the verbosity by one; using
|
||
|
|
`\-\-verbose=N' sets it to N.
|
||
|
|
.IP "\-S" 4
|
||
|
|
.IX Item "-S"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-stow" 4
|
||
|
|
.IX Item "--stow"
|
||
|
|
.PD
|
||
|
|
Stow the packages that follow this option into the target directory.
|
||
|
|
This is the default action and so can be omitted if you are only
|
||
|
|
stowing packages rather than performing a mixture of
|
||
|
|
stow/delete/restow actions.
|
||
|
|
.IP "\-D" 4
|
||
|
|
.IX Item "-D"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-delete" 4
|
||
|
|
.IX Item "--delete"
|
||
|
|
.PD
|
||
|
|
Unstow the packages that follow this option from the target directory rather
|
||
|
|
than installing them.
|
||
|
|
.IP "\-R" 4
|
||
|
|
.IX Item "-R"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-restow" 4
|
||
|
|
.IX Item "--restow"
|
||
|
|
.PD
|
||
|
|
Restow packages (first unstow, then stow again). This is useful
|
||
|
|
for pruning obsolete symlinks from the target tree after updating
|
||
|
|
the software in a package.
|
||
|
|
.IP "\-\-adopt" 4
|
||
|
|
.IX Item "--adopt"
|
||
|
|
\&\fBWarning!\fR This behaviour is specifically intended to alter the
|
||
|
|
contents of your stow directory. If you do not want that, this option
|
||
|
|
is not for you.
|
||
|
|
.Sp
|
||
|
|
When stowing, if a target is encountered which already exists but is a
|
||
|
|
plain file (and hence not owned by any existing stow package), then
|
||
|
|
normally Stow will register this as a conflict and refuse to proceed.
|
||
|
|
This option changes that behaviour so that the file is moved to the
|
||
|
|
same relative place within the package's installation image within the
|
||
|
|
stow directory, and then stowing proceeds as before. So effectively,
|
||
|
|
the file becomes adopted by the stow package, without its contents
|
||
|
|
changing.
|
||
|
|
.IP "\-\-no\-folding" 4
|
||
|
|
.IX Item "--no-folding"
|
||
|
|
Disable folding of newly stowed directories when stowing, and
|
||
|
|
refolding of newly foldable directories when unstowing.
|
||
|
|
.IP "\-\-ignore=REGEX" 4
|
||
|
|
.IX Item "--ignore=REGEX"
|
||
|
|
Ignore files ending in this Perl regex.
|
||
|
|
.IP "\-\-defer=REGEX" 4
|
||
|
|
.IX Item "--defer=REGEX"
|
||
|
|
Don't stow files beginning with this Perl regex if the file is already
|
||
|
|
stowed to another package.
|
||
|
|
.IP "\-\-override=REGEX" 4
|
||
|
|
.IX Item "--override=REGEX"
|
||
|
|
Force stowing files beginning with this Perl regex if the file is
|
||
|
|
already stowed to another package.
|
||
|
|
.IP "\-V" 4
|
||
|
|
.IX Item "-V"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-version" 4
|
||
|
|
.IX Item "--version"
|
||
|
|
.PD
|
||
|
|
Show Stow version number, and exit.
|
||
|
|
.IP "\-h" 4
|
||
|
|
.IX Item "-h"
|
||
|
|
.PD 0
|
||
|
|
.IP "\-\-help" 4
|
||
|
|
.IX Item "--help"
|
||
|
|
.PD
|
||
|
|
Show Stow command syntax, and exit.
|
||
|
|
.SH "INSTALLING PACKAGES"
|
||
|
|
.IX Header "INSTALLING PACKAGES"
|
||
|
|
The default action of Stow is to install a package. This means
|
||
|
|
creating symlinks in the target tree that point into the package tree.
|
||
|
|
Stow attempts to do this with as few symlinks as possible; in other
|
||
|
|
words, if Stow can create a single symlink that points to an entire
|
||
|
|
subtree within the package tree, it will choose to do that rather than
|
||
|
|
create a directory in the target tree and populate it with symlinks.
|
||
|
|
.PP
|
||
|
|
For example, suppose that no packages have yet been installed in
|
||
|
|
\&\fI/usr/local\fR; it's completely empty (except for the \fIstow\fR
|
||
|
|
subdirectory, of course). Now suppose the Perl package is installed.
|
||
|
|
Recall that it includes the following directories in its installation
|
||
|
|
image: \fIbin\fR; \fIinfo\fR; \fIlib/perl\fR; \fIman/man1\fR. Rather than
|
||
|
|
creating the directory \fI/usr/local/bin\fR and populating it with
|
||
|
|
symlinks to \fI../stow/perl/bin/perl\fR and \fI../stow/perl/bin/a2p\fR (and
|
||
|
|
so on), Stow will create a single symlink, \fI/usr/local/bin\fR, which
|
||
|
|
points to \fIstow/perl/bin\fR. In this way, it still works to refer to
|
||
|
|
\&\fI/usr/local/bin/perl\fR and \fI/usr/local/bin/a2p\fR, and fewer symlinks
|
||
|
|
have been created. This is called \*(L"tree folding\*(R", since an entire
|
||
|
|
subtree is \*(L"folded\*(R" into a single symlink.
|
||
|
|
.PP
|
||
|
|
To complete this example, Stow will also create the symlink
|
||
|
|
\&\fI/usr/local/info\fR pointing to \fIstow/perl/info\fR; the symlink
|
||
|
|
\&\fI/usr/local/lib\fR pointing to \fIstow/perl/lib\fR; and the symlink
|
||
|
|
\&\fI/usr/local/man\fR pointing to \fIstow/perl/man\fR.
|
||
|
|
.PP
|
||
|
|
Now suppose that instead of installing the Perl package into an empty
|
||
|
|
target tree, the target tree is not empty to begin with. Instead, it
|
||
|
|
contains several files and directories installed under a different
|
||
|
|
system-administration philosophy. In particular, \fI/usr/local/bin\fR
|
||
|
|
already exists and is a directory, as are \fI/usr/local/lib\fR and
|
||
|
|
\&\fI/usr/local/man/man1\fR. In this case, Stow will descend into
|
||
|
|
\&\fI/usr/local/bin\fR and create symlinks to \fI../stow/perl/bin/perl\fR and
|
||
|
|
\&\fI../stow/perl/bin/a2p\fR (etc.), and it will descend into
|
||
|
|
\&\fI/usr/local/lib\fR and create the tree-folding symlink \fIperl\fR pointing
|
||
|
|
to \fI../stow/perl/lib/perl\fR, and so on. As a rule, Stow only descends
|
||
|
|
as far as necessary into the target tree when it can create a
|
||
|
|
tree-folding symlink.
|
||
|
|
.PP
|
||
|
|
The time often comes when a tree-folding symlink has to be undone
|
||
|
|
because another package uses one or more of the folded subdirectories
|
||
|
|
in its installation image. This operation is called \*(L"splitting open\*(R"
|
||
|
|
a folded tree. It involves removing the original symlink from the
|
||
|
|
target tree, creating a true directory in its place, and then
|
||
|
|
populating the new directory with symlinks to the newly-installed
|
||
|
|
package \fBand\fR to the old package that used the old symlink. For
|
||
|
|
example, suppose that after installing Perl into an empty
|
||
|
|
\&\fI/usr/local\fR, we wish to install Emacs. Emacs's installation image
|
||
|
|
includes a \fIbin\fR directory containing the \fIemacs\fR and \fIetags\fR
|
||
|
|
executables, among others. Stow must make these files appear to be
|
||
|
|
installed in \fI/usr/local/bin\fR, but presently \fI/usr/local/bin\fR is a
|
||
|
|
symlink to \fIstow/perl/bin\fR. Stow therefore takes the following
|
||
|
|
steps: the symlink \fI/usr/local/bin\fR is deleted; the directory
|
||
|
|
\&\fI/usr/local/bin\fR is created; links are made from \fI/usr/local/bin\fR to
|
||
|
|
\&\fI../stow/emacs/bin/emacs\fR and \fI../stow/emacs/bin/etags\fR; and links
|
||
|
|
are made from \fI/usr/local/bin\fR to \fI../stow/perl/bin/perl\fR and
|
||
|
|
\&\fI../stow/perl/bin/a2p\fR.
|
||
|
|
.PP
|
||
|
|
When splitting open a folded tree, Stow makes sure that the symlink
|
||
|
|
it is about to remove points inside a valid package in the current stow
|
||
|
|
directory.
|
||
|
|
.SS "Stow will never delete anything that it doesn't own."
|
||
|
|
.IX Subsection "Stow will never delete anything that it doesn't own."
|
||
|
|
Stow \*(L"owns\*(R" everything living in the target tree that points into a
|
||
|
|
package in the stow directory. Anything Stow owns, it can recompute if
|
||
|
|
lost. Note that by this definition, Stow doesn't \*(L"own\*(R" anything
|
||
|
|
\&\fBin\fR the stow directory or in any of the packages.
|
||
|
|
.PP
|
||
|
|
If Stow needs to create a directory or a symlink in the target tree
|
||
|
|
and it cannot because that name is already in use and is not owned by
|
||
|
|
Stow, then a conflict has arisen. See the \*(L"Conflicts\*(R" section in the
|
||
|
|
info manual.
|
||
|
|
.SH "DELETING PACKAGES"
|
||
|
|
.IX Header "DELETING PACKAGES"
|
||
|
|
When the \f(CW\*(C`\-D\*(C'\fR option is given, the action of Stow is to delete a
|
||
|
|
package from the target tree. Note that Stow will not delete anything
|
||
|
|
it doesn't \*(L"own\*(R". Deleting a package does \fBnot\fR mean removing it from
|
||
|
|
the stow directory or discarding the package tree.
|
||
|
|
.PP
|
||
|
|
To delete a package, Stow recursively scans the target tree, skipping
|
||
|
|
over the stow directory (since that is usually a subdirectory of the
|
||
|
|
target tree) and any other stow directories it encounters (see
|
||
|
|
\&\*(L"Multiple stow directories\*(R" in the info manual). Any symlink it
|
||
|
|
finds that points into the package being deleted is removed. Any
|
||
|
|
directory that contained only symlinks to the package being deleted is
|
||
|
|
removed. Any directory that, after removing symlinks and empty
|
||
|
|
subdirectories, contains only symlinks to a single other package, is
|
||
|
|
considered to be a previously \*(L"folded\*(R" tree that was \*(L"split open.\*(R"
|
||
|
|
Stow will re-fold the tree by removing the symlinks to the surviving
|
||
|
|
package, removing the directory, then linking the directory back to
|
||
|
|
the surviving package.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
The full documentation for \fIstow\fR is maintained as a Texinfo manual.
|
||
|
|
If the \fIinfo\fR and \fIstow\fR programs are properly installed at your site, the command
|
||
|
|
.PP
|
||
|
|
.Vb 1
|
||
|
|
\& info stow
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
should give you access to the complete manual.
|
||
|
|
.SH "BUGS"
|
||
|
|
.IX Header "BUGS"
|
||
|
|
Please report bugs in Stow using the Debian bug tracking system.
|
||
|
|
.PP
|
||
|
|
Currently known bugs include:
|
||
|
|
.IP "\(bu" 4
|
||
|
|
The empty-directory problem.
|
||
|
|
.Sp
|
||
|
|
If package \fIfoo\fR includes an empty directory \*(-- say, \fIfoo/bar\fR \*(--
|
||
|
|
then if no other package has a \fIbar\fR subdirectory, everything's fine.
|
||
|
|
If another stowed package \fIquux\fR, has a \fIbar\fR subdirectory, then
|
||
|
|
when stowing, \fItargetdir/bar\fR will be \*(L"split open\*(R" and the contents
|
||
|
|
of \fIquux/bar\fR will be individually stowed. So far, so good. But when
|
||
|
|
unstowing \fIquux\fR, \fItargetdir/bar\fR will be removed, even though
|
||
|
|
\&\fIfoo/bar\fR needs it to remain. A workaround for this problem is to
|
||
|
|
create a file in \fIfoo/bar\fR as a placeholder. If you name that file
|
||
|
|
\&\fI.placeholder\fR, it will be easy to find and remove such files when
|
||
|
|
this bug is fixed.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
When using multiple stow directories (see \*(L"Multiple stow directories\*(R"
|
||
|
|
in the info manual), Stow fails to \*(L"split open\*(R" tree-folding symlinks
|
||
|
|
(see \*(L"Installing packages\*(R" in the info manual) that point into a stow
|
||
|
|
directory which is not the one in use by the current Stow
|
||
|
|
command. Before failing, it should search the target of the link to
|
||
|
|
see whether any element of the path contains a \fI.stow\fR file. If it
|
||
|
|
finds one, it can \*(L"learn\*(R" about the cooperating stow directory to
|
||
|
|
short-circuit the \fI.stow\fR search the next time it encounters a
|
||
|
|
tree-folding symlink.
|
||
|
|
.SH "AUTHOR"
|
||
|
|
.IX Header "AUTHOR"
|
||
|
|
This man page was originally constructed by Charles Briscoe-Smith from
|
||
|
|
parts of Stow's info manual, and then converted to \s-1POD\s0 format by Adam
|
||
|
|
Spiers. The info manual contains the following notice, which, as it
|
||
|
|
says, applies to this manual page, too. The text of the section
|
||
|
|
entitled \*(L"\s-1GNU\s0 General Public License\*(R" can be found in the file
|
||
|
|
\&\fI/usr/share/common\-licenses/GPL\fR on any Debian GNU/Linux system. If
|
||
|
|
you don't have access to a Debian system, or the \s-1GPL\s0 is not there,
|
||
|
|
write to the Free Software Foundation, Inc., 59 Temple Place, Suite
|
||
|
|
330, Boston, \s-1MA, 02111\-1307, USA.\s0
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright (C)
|
||
|
|
1993, 1994, 1995, 1996 by Bob Glickstein <bobg+stow@zanshin.com>;
|
||
|
|
2000, 2001 by Guillaume Morin;
|
||
|
|
2007 by Kahlil Hodgson;
|
||
|
|
2011 by Adam Spiers;
|
||
|
|
and others.
|
||
|
|
.PP
|
||
|
|
Permission is granted to make and distribute verbatim copies of this
|
||
|
|
manual provided the copyright notice and this permission notice are
|
||
|
|
preserved on all copies.
|
||
|
|
.PP
|
||
|
|
Permission is granted to copy and distribute modified versions of this
|
||
|
|
manual under the conditions for verbatim copying, provided also that
|
||
|
|
the section entitled \*(L"\s-1GNU\s0 General Public License\*(R" is included with the
|
||
|
|
modified manual, and provided that the entire resulting derived work
|
||
|
|
is distributed under the terms of a permission notice identical to
|
||
|
|
this one.
|
||
|
|
.PP
|
||
|
|
Permission is granted to copy and distribute translations of this
|
||
|
|
manual into another language, under the above conditions for modified
|
||
|
|
versions, except that this permission notice may be stated in a
|
||
|
|
translation approved by the Free Software Foundation.
|