1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This manual describes GNU Stow version 2.4.1
(8 September 2024), a program for managing farms of symbolic links.
Software and documentation is copyrighted by the following:
© 1993, 1994, 1995, 1996 Bob Glickstein bobg+stow@zanshin.com
© 2000, 2001 Guillaume Morin gmorin@gnu.org
© 2007 Kahlil (Kal) Hodgson kahlil@internode.on.net
© 2011 Adam Spiers stow@adamspiers.org
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.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled "GNU General Public License" 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.
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. -->
<title>Terminology (Stow)</title>
<meta name="description" content="Terminology (Stow)">
<meta name="keywords" content="Terminology (Stow)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Index.html" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html" rel="up" title="Top">
<link href="Invoking-Stow.html" rel="next" title="Invoking Stow">
<link href="Introduction.html" rel="prev" title="Introduction">
</head>
<body lang="en">
<div class="chapter-level-extent" id="Terminology">
<div class="nav-panel">
<p>
Next: <a href="Invoking-Stow.html" accesskey="n" rel="next">Invoking Stow</a>, Previous: <a href="Introduction.html" accesskey="p" rel="prev">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h2 class="chapter" id="Terminology-1">2 Terminology</h2>
<a class="index-entry-id" id="index-package"></a>
<p>A <em class="dfn">package</em> 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
<samp class="file">bin</samp>, <samp class="file">lib</samp>, and <samp class="file">man</samp> subdirectories.
</p>
<a class="index-entry-id" id="index-target-directory"></a>
<p>A <em class="dfn">target directory</em> is the root of a tree in which one or more
packages wish to <em class="emph">appear</em> to be installed. <samp class="file">/usr/local</samp> is a
common choice for this, but by no means the only such location. Another
common choice is <samp class="file">~</samp> (i.e. the user’s <code class="code">$HOME</code> directory) in
the case where Stow is being used to manage the user’s configuration
(“dotfiles”) and other files in their <code class="code">$HOME</code>. The examples in
this manual will use <samp class="file">/usr/local</samp> as the target directory.
</p>
<a class="index-entry-id" id="index-stow-directory"></a>
<p>A <em class="dfn">stow directory</em> 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
will use <samp class="file">/usr/local/stow</samp> as the stow directory, so that
individual packages will be, for example, <samp class="file">/usr/local/stow/perl</samp>
and <samp class="file">/usr/local/stow/emacs</samp>.
</p>
<a class="index-entry-id" id="index-installation-image"></a>
<p>An <em class="dfn">installation image</em> is the layout of files and directories
required by a package, relative to the target directory. Thus, the
installation image for Perl includes: a <samp class="file">bin</samp> directory containing
<samp class="file">perl</samp> and <samp class="file">a2p</samp> (among others); an <samp class="file">info</samp> directory
containing Texinfo documentation; a <samp class="file">lib/perl</samp> directory containing
Perl libraries; and a <samp class="file">man/man1</samp> directory containing man pages.
</p>
<blockquote class="quotation">
<p><b class="b">Note:</b> This is a <em class="emph">pre-</em>installation image which exists even before Stow
has installed any symlinks into the target directory which point to it.
</p></blockquote>
<a class="index-entry-id" id="index-package-directory"></a>
<a class="index-entry-id" id="index-package-name"></a>
<p>A <em class="dfn">package directory</em> 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
<samp class="file">/usr/local/stow/perl</samp> must reside in the stow directory
<samp class="file">/usr/local/stow</samp>. The <em class="dfn">name</em> of a package is the name of its
directory within the stow directory — e.g., <samp class="file">perl</samp>.
</p>
<p>Thus, the Perl executable might reside in
<samp class="file">/usr/local/stow/perl/bin/perl</samp>, where <samp class="file">/usr/local</samp> is the
target directory, <samp class="file">/usr/local/stow</samp> is the stow directory,
<samp class="file">/usr/local/stow/perl</samp> is the package directory, and
<samp class="file">bin/perl</samp> within is part of the installation image.
</p>
<a class="anchor" id="symlink"></a><a class="index-entry-id" id="index-symlink"></a>
<a class="index-entry-id" id="index-symlink-source"></a>
<a class="index-entry-id" id="index-symlink-destination"></a>
<a class="index-entry-id" id="index-relative-symlink"></a>
<a class="index-entry-id" id="index-absolute-symlink"></a>
<p>A <em class="dfn">symlink</em> is a symbolic link, i.e. an entry on the filesystem
whose path is sometimes called the <em class="dfn">symlink source</em>, which points to
another location on the filesystem called the <em class="dfn">symlink destination</em>.
There is no guarantee that the destination actually exists.
</p>
<p>In general, symlinks can be <em class="dfn">relative</em> or <em class="dfn">absolute</em>. A symlink
is absolute when the destination names a full path; that is, one
starting from <samp class="file">/</samp>. A symlink is relative when the destination
names a relative path; that is, one not starting from <samp class="file">/</samp>. The
destination of a relative symlink is computed starting from the
symlink’s own directory, i.e. the directory containing the symlink
source.
</p>
<blockquote class="quotation">
<p><b class="b">Note:</b> Stow only creates symlinks within the target directory which point to
locations <em class="emph">outside</em> the target directory and inside the stow
directory.
</p>
<p>Consequently, we avoid referring to symlink destinations as symlink
<em class="emph">targets</em>, since this would result in the word “target” having
two different meanings:
</p>
<ol class="enumerate">
<li> the target directory, i.e. the directory into which Stow targets
installation, where symlinks are managed by Stow, and
</li><li> the destinations of those symlinks.
</li></ol>
<p>If we did not avoid the second meaning of “target”, then it would lead
to confusing language, such as describing Stow as installing symlinks
into the target directory which point to targets <em class="emph">outside</em> the
target directory.
</p>
<p>Similarly, the word “source” can have two different meanings in this
context:
</p>
<ol class="enumerate">
<li> the installation image, or some of its contents, and
</li><li> the location of symlinks (the “source” of the link, vs. its
destination).
</li></ol>
<p>Therefore it should also be avoided, or at least care taken to ensure
that the meaning is not ambiguous.
</p>
</blockquote>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Invoking-Stow.html">Invoking Stow</a>, Previous: <a href="Introduction.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
