openpkg/lsync.8

changeset 18
9115bae56135
child 428
f880f219c566
equal deleted inserted replaced
-1:000000000000 0:aca2b5f4549e
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 . ds -- \(*W-
36 . ds PI pi
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39 . ds L" ""
40 . ds R" ""
41 . ds C`
42 . ds C'
43 'br\}
44 .el\{\
45 . ds -- \|\(em\|
46 . ds PI \(*p
47 . ds L" ``
48 . ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 . de IX
57 . tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 . nr % 0
60 . rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
71 .if n \{\
72 . ds #H 0
73 . ds #V .8m
74 . ds #F .3m
75 . ds #[ \f1
76 . ds #] \fP
77 .\}
78 .if t \{\
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . ds #V .6m
81 . ds #F 0
82 . ds #[ \&
83 . ds #] \&
84 .\}
85 . \" simple accents for nroff and troff
86 .if n \{\
87 . ds ' \&
88 . ds ` \&
89 . ds ^ \&
90 . ds , \&
91 . ds ~ ~
92 . ds /
93 .\}
94 .if t \{\
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 . ds : e
119 . ds 8 ss
120 . ds o a
121 . ds d- d\h'-1'\(ga
122 . ds D- D\h'-1'\(hy
123 . ds th \o'bp'
124 . ds Th \o'LP'
125 . ds ae ae
126 . ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "LSYNC 8"
132 .TH LSYNC 8 "OpenPKG" "LSYNC(8)" "OpenPKG"
133 .SH "NAME"
134 \&\fBopenpkg lsync\fR \- Access Layer Synchronization Tool
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBopenpkg lsync\fR
138 [\fB\-\-version\fR|\fB\-v\fR]
139 [\fB\-\-help\fR|\fB\-h\fR]
140 [\fB\-\-init\fR|\fB\-i\fR]
141 [\fB\-\-nop\fR|\fB\-n\fR]
142 [\fB\-\-quiet\fR|\fB\-q\fR]
143 [\fB\-\-trace\fR|\fB\-t\fR]
144 [\fB\-\-local\fR|\fB\-l\fR]
145 [\fB\-\-uninstall\fR|\fB\-u\fR]
146 [\fB\-\-root=\fR\fIroot\fR]
147 [\fB\-\-pkgdir=\fR\fIpkgdir\fR]
148 [\fB\-\-subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
149 .SH "DESCRIPTION"
150 .IX Header "DESCRIPTION"
151 This program activates software packages which were locally
152 installed in a sub-directory of a package hierarchy (located under
153 \&\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
154 (located under \fIroot\fR/) corresponding to package installation
155 files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
156 collected in global directories (located under \fIroot\fR/subdir/).
157 .PP
158 The purpose of this is that individual packages can be installed and
159 deinstalled seperately without interfering with other packages while
160 all packages as a whole still can be treated like a single package
161 (installed into the access layer).
162 .PP
163 The
164 actual creation of symbolic links is as following (\*(L"foo\*(R" indicating an
165 arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
166 .IP "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
167 .IX Item "root/bin/foo -> ../pkgdir/bar/bin/foo"
168 This activates the user executeable
169 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
170 be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
171 variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/bin:.."\fR).
172 .IP "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
173 .IX Item "root/sbin/foo -> ../pkgdir/bar/sbin/foo"
174 This activates the system executeable
175 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
176 be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
177 variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/sbin:.."\fR).
178 .IP "\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo" 4
179 .IX Item "root/man/manN/foo -> ../pkgdir/bar/man/manN/foo"
180 This activates the Unix manual page
181 \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
182 \&\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
183 by placing \fIroot\fR\fB/man\fR into the environment variable \f(CW\*(C`MANPATH\*(C'\fR
184 (\fBMANPATH="..:\fR\fIroot\fR\fB/man:.."\fR). Keep in mind that \fBopenpkg lsync\fR
185 activates any files found in the \fBman/man\f(BIN\fB\fR sub-directory of the
186 package, but the \fIman\fR\|(1) tool usually requires the filename scheme
187 foo\fB.\fR\fIN\fR before it can find the file.
188 .IP "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
189 .IX Item "root/info/foo -> ../pkgdir/bar/info/foo"
190 This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
191 as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
192 tools by placing \fIroot\fR\fB/info\fR into the environment variable
193 \&\f(CW\*(C`INFOPATH\*(C'\fR (\fBINFOPATH="..:\fR\fIroot\fR\fB/info:.."\fR). Keep in mind that
194 \&\fBopenpkg lsync\fR activates any files found in the \fBinfo/\fR sub-directory of the
195 package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
196 scheme foo\fB.info\fR before it can find the file.
197 .IP "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
198 .IX Item "root/include/foo -> ../pkgdir/bar/include/foo"
199 This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
200 as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
201 by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
202 \&\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fBopenpkg lsync\fR activates any
203 files found in the \fBinclude/\fR sub-directory of the package, but the
204 C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
205 .IP "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
206 .IX Item "root/lib/foo -> ../pkgdir/bar/lib/foo"
207 This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
208 as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
209 the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
210 path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
211 Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
212 \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR (\fBLD_LIBRARY_PATH="..:\fR\fIroot\fR\fB/lib:.."\fR).
213 Keep in mind that \fBopenpkg lsync\fR activates any files found in the \fBlib/\fR
214 sub-directory of the package, but the C/\*(C+ compiler usually require the
215 filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
216 scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
217 .PP
218 It is obvious that more sub-directories in a package installation
219 might exist \*(-- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
220 \&\fBopenpkg lsync\fR intentionally does not link files in those directories into
221 corresponding directories of the access layer, because those files do
222 not require that they are located in a global area in order to be used.
223 So \fBopenpkg lsync\fR only creates the access layer for files where a common area
224 is required for (easy) use.
225 .SH "SPECIAL FEATURES"
226 .IX Header "SPECIAL FEATURES"
227 There are two special features supported by \fBopenpkg lsync\fR:
228 .IP "\fBRun-Command Files\fR" 4
229 .IX Item "Run-Command Files"
230 \&\fBopenpkg lsync\fR on startup implicitly reads command line options from
231 \&\f(CW\*(C`.lsyncrc\*(C'\fR files. They are searched in all parent directories and in
232 the callers home directory. Their contents is prepended to the list of
233 given command line options.
234 .IP "\fBMultiple Package Versions\fR" 4
235 .IX Item "Multiple Package Versions"
236 \&\fBopenpkg lsync\fR skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
237 the pattern \*(L"\-[0\-9]\*(R" in their directory name. On the other hand,
238 \&\fBopenpkg lsync\fR follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
239 This can be used for installing multiple versions of a package and
240 switching between them. For instance, if version 1.0 of package
241 \&\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo\-1.0,
242 version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo\-1.1 and version 1.2 into
243 \&\fIroot\fR/\fIpkgdir\fR/foo\-1.2, \fBopenpkg lsync\fR does skip all three. To enable
244 version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
245 pointing to foo\-1.1. Then \fBopenpkg lsync\fR picks up the files in
246 \&\fIroot\fR/\fIpkgdir\fR/foo\-1.1. If you want to temporarily upgrade to
247 foo\-1.2, all you have to do is to change the symlink pointing from
248 foo\-1.1 to foo\-1.2.
249 .IP "\fBTemporarily Deactivated Package\fR" 4
250 .IX Item "Temporarily Deactivated Package"
251 One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
252 and running \*(L"openpkg lsync \-\-local \-\-uninstall\*(R", of course. Alternatively
253 one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
254 Then \fBopenpkg lsync\fR also skips the package. Alternatively, assume
255 package \*(L"foo\*(R" as a whole should not be deactivated, but its
256 \&\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
257 unfortunately contains non-library files), one just sets the sticky bit
258 on \fIroot\fR/\fIpkgdir\fR/foo/lib.
259 .SH "OPTIONS"
260 .IX Header "OPTIONS"
261 .IP "\fB\-\-version\fR, \fB\-v\fR" 4
262 .IX Item "--version, -v"
263 Display program version information only.
264 .IP "\fB\-\-help\fR, \fB\-h\fR" 4
265 .IX Item "--help, -h"
266 Display program usage information only.
267 .IP "\fB\-\-init\fR, \fB\-i\fR" 4
268 .IX Item "--init, -i"
269 Create an initial access layer hierarchy under \fIroot\fR.
270 .IP "\fB\-\-nop\fR, \fB\-n\fR" 4
271 .IX Item "--nop, -n"
272 No Operation \*(-- causes \fBopenpkg lsync\fR to not perform any filesystem
273 operations. In conjunction with \fB\-\-trace\fR you can at least see what
274 would be executed.
275 .IP "\fB\-\-quiet\fR, \fB\-q\fR" 4
276 .IX Item "--quiet, -q"
277 Forces \fBopenpkg lsync\fR to perform the operations quietly, i.e., without any
278 verbose messages.
279 .IP "\fB\-\-trace\fR, \fB\-t\fR" 4
280 .IX Item "--trace, -t"
281 Forces \fBopenpkg lsync\fR to show what filesystem operations are performed.
282 .IP "\fB\-\-local\fR, \fB\-l\fR" 4
283 .IX Item "--local, -l"
284 This restricts the operations to a local package area. This option can
285 only be used if you are physically staying below a package sub-directory
286 under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
287 \&\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB\-\-local\fR,
288 all operations are restricted to the package \*(L"bar\*(R".
289 .IP "\fB\-\-uninstall\fR, \fB\-u\fR" 4
290 .IX Item "--uninstall, -u"
291 This performs only package uninstallation operations, i.e., only
292 symbolic links are removed. This can be used to completely empty the
293 access layer. Additionally it is very useful in combination with
294 \&\fB\-\-local\fR in order to uninstall a particular package without having to
295 remove its files.
296 .IP "\fB\-\-root=\fR\fIroot\fR" 4
297 .IX Item "--root=root"
298 Sets the root directory where the access layer and package subdirectory
299 is located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
300 (see section \*(L"Current configuration\*(R").
301 .IP "\fB\-\-pkgdir=\fR\fIpkgdir\fR" 4
302 .IX Item "--pkgdir=pkgdir"
303 Sets the sub-directory under the root directory where packages are
304 located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR (see
305 section \*(L"Current configuration\*(R").
306 .IP "\fB\-\-subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
307 .IX Item "--subdirs=subdirs[,subdir,...]"
308 Sets one or more sub-directories of the access layer on which \fBopenpkg lsync\fR
309 should act. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
310 (see section \*(L"Current configuration\*(R").
311 .SH "RESULTS"
312 .IX Header "RESULTS"
313 This program uses the following return codes on exit: 0 (operation
314 successful), 1 (system error), 2 (command line error) and 3 (other user
315 error).
316 .SH "HISTORY"
317 .IX Header "HISTORY"
318 The idea of filesystem access layers consisting of symbolic links
319 pointing to actual package installation areas is a rather old one. It
320 dates back to the early days of Unix and was implemented many times over
321 the last decades. One of many implementation was \fBGenOPT\fR, written by
322 Ralf S. Engelschall for sd&m GmbH & Co \s-1KG\s0, Munich in 1992. The name
323 indicates the programs purpose: to generate symbolic links in an access
324 layer which was located under \f(CW\*(C`/opt\*(C'\fR. \fBGenOPT\fR was very flexible, but
325 hence also very complex. Because of lack of documentation it was never
326 released and so only used at sd&m and on all machines which were under
327 control of Ralf S. Engelschall.
328 .PP
329 For Cable & Wireless, Munich, the old \fBGenOPT\fR principle was again
330 needed to manage the \f(CW\*(C`/cw/local\*(C'\fR area on their servers. For this in
331 November 2000 the functionality of \fBGenOPT\fR was revised, heavily
332 stripped down and finally implemented from scratch. The result is the
333 current \fBopenpkg lsync\fR.
334 .SH "AUTHOR"
335 .IX Header "AUTHOR"
336 .Vb 3
337 \& Ralf S. Engelschall
338 \& rse@engelschall.com
339 \& www.engelschall.com
340 .Ve

mercurial