1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/lsync.8 Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,340 @@
1.4 +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
1.5 +.\"
1.6 +.\" Standard preamble:
1.7 +.\" ========================================================================
1.8 +.de Sh \" Subsection heading
1.9 +.br
1.10 +.if t .Sp
1.11 +.ne 5
1.12 +.PP
1.13 +\fB\\$1\fR
1.14 +.PP
1.15 +..
1.16 +.de Sp \" Vertical space (when we can't use .PP)
1.17 +.if t .sp .5v
1.18 +.if n .sp
1.19 +..
1.20 +.de Vb \" Begin verbatim text
1.21 +.ft CW
1.22 +.nf
1.23 +.ne \\$1
1.24 +..
1.25 +.de Ve \" End verbatim text
1.26 +.ft R
1.27 +.fi
1.28 +..
1.29 +.\" Set up some character translations and predefined strings. \*(-- will
1.30 +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
1.31 +.\" double quote, and \*(R" will give a right double quote. | will give a
1.32 +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
1.33 +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
1.34 +.\" expand to `' in nroff, nothing in troff, for use with C<>.
1.35 +.tr \(*W-|\(bv\*(Tr
1.36 +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
1.37 +.ie n \{\
1.38 +. ds -- \(*W-
1.39 +. ds PI pi
1.40 +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
1.41 +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
1.42 +. ds L" ""
1.43 +. ds R" ""
1.44 +. ds C`
1.45 +. ds C'
1.46 +'br\}
1.47 +.el\{\
1.48 +. ds -- \|\(em\|
1.49 +. ds PI \(*p
1.50 +. ds L" ``
1.51 +. ds R" ''
1.52 +'br\}
1.53 +.\"
1.54 +.\" If the F register is turned on, we'll generate index entries on stderr for
1.55 +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
1.56 +.\" entries marked with X<> in POD. Of course, you'll have to process the
1.57 +.\" output yourself in some meaningful fashion.
1.58 +.if \nF \{\
1.59 +. de IX
1.60 +. tm Index:\\$1\t\\n%\t"\\$2"
1.61 +..
1.62 +. nr % 0
1.63 +. rr F
1.64 +.\}
1.65 +.\"
1.66 +.\" For nroff, turn off justification. Always turn off hyphenation; it makes
1.67 +.\" way too many mistakes in technical documents.
1.68 +.hy 0
1.69 +.if n .na
1.70 +.\"
1.71 +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
1.72 +.\" Fear. Run. Save yourself. No user-serviceable parts.
1.73 +. \" fudge factors for nroff and troff
1.74 +.if n \{\
1.75 +. ds #H 0
1.76 +. ds #V .8m
1.77 +. ds #F .3m
1.78 +. ds #[ \f1
1.79 +. ds #] \fP
1.80 +.\}
1.81 +.if t \{\
1.82 +. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
1.83 +. ds #V .6m
1.84 +. ds #F 0
1.85 +. ds #[ \&
1.86 +. ds #] \&
1.87 +.\}
1.88 +. \" simple accents for nroff and troff
1.89 +.if n \{\
1.90 +. ds ' \&
1.91 +. ds ` \&
1.92 +. ds ^ \&
1.93 +. ds , \&
1.94 +. ds ~ ~
1.95 +. ds /
1.96 +.\}
1.97 +.if t \{\
1.98 +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
1.99 +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
1.100 +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
1.101 +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
1.102 +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
1.103 +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
1.104 +.\}
1.105 +. \" troff and (daisy-wheel) nroff accents
1.106 +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
1.107 +.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
1.108 +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
1.109 +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
1.110 +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
1.111 +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
1.112 +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
1.113 +.ds ae a\h'-(\w'a'u*4/10)'e
1.114 +.ds Ae A\h'-(\w'A'u*4/10)'E
1.115 +. \" corrections for vroff
1.116 +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
1.117 +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
1.118 +. \" for low resolution devices (crt and lpr)
1.119 +.if \n(.H>23 .if \n(.V>19 \
1.120 +\{\
1.121 +. ds : e
1.122 +. ds 8 ss
1.123 +. ds o a
1.124 +. ds d- d\h'-1'\(ga
1.125 +. ds D- D\h'-1'\(hy
1.126 +. ds th \o'bp'
1.127 +. ds Th \o'LP'
1.128 +. ds ae ae
1.129 +. ds Ae AE
1.130 +.\}
1.131 +.rm #[ #] #H #V #F C
1.132 +.\" ========================================================================
1.133 +.\"
1.134 +.IX Title "LSYNC 8"
1.135 +.TH LSYNC 8 "OpenPKG" "LSYNC(8)" "OpenPKG"
1.136 +.SH "NAME"
1.137 +\&\fBopenpkg lsync\fR \- Access Layer Synchronization Tool
1.138 +.SH "SYNOPSIS"
1.139 +.IX Header "SYNOPSIS"
1.140 +\&\fBopenpkg lsync\fR
1.141 +[\fB\-\-version\fR|\fB\-v\fR]
1.142 +[\fB\-\-help\fR|\fB\-h\fR]
1.143 +[\fB\-\-init\fR|\fB\-i\fR]
1.144 +[\fB\-\-nop\fR|\fB\-n\fR]
1.145 +[\fB\-\-quiet\fR|\fB\-q\fR]
1.146 +[\fB\-\-trace\fR|\fB\-t\fR]
1.147 +[\fB\-\-local\fR|\fB\-l\fR]
1.148 +[\fB\-\-uninstall\fR|\fB\-u\fR]
1.149 +[\fB\-\-root=\fR\fIroot\fR]
1.150 +[\fB\-\-pkgdir=\fR\fIpkgdir\fR]
1.151 +[\fB\-\-subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
1.152 +.SH "DESCRIPTION"
1.153 +.IX Header "DESCRIPTION"
1.154 +This program activates software packages which were locally
1.155 +installed in a sub-directory of a package hierarchy (located under
1.156 +\&\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
1.157 +(located under \fIroot\fR/) corresponding to package installation
1.158 +files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
1.159 +collected in global directories (located under \fIroot\fR/subdir/).
1.160 +.PP
1.161 +The purpose of this is that individual packages can be installed and
1.162 +deinstalled seperately without interfering with other packages while
1.163 +all packages as a whole still can be treated like a single package
1.164 +(installed into the access layer).
1.165 +.PP
1.166 +The
1.167 +actual creation of symbolic links is as following (\*(L"foo\*(R" indicating an
1.168 +arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
1.169 +.IP "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
1.170 +.IX Item "root/bin/foo -> ../pkgdir/bar/bin/foo"
1.171 +This activates the user executeable
1.172 +\&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
1.173 +be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
1.174 +variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/bin:.."\fR).
1.175 +.IP "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
1.176 +.IX Item "root/sbin/foo -> ../pkgdir/bar/sbin/foo"
1.177 +This activates the system executeable
1.178 +\&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
1.179 +be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
1.180 +variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/sbin:.."\fR).
1.181 +.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
1.182 +.IX Item "root/man/manN/foo -> ../pkgdir/bar/man/manN/foo"
1.183 +This activates the Unix manual page
1.184 +\&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
1.185 +\&\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
1.186 +by placing \fIroot\fR\fB/man\fR into the environment variable \f(CW\*(C`MANPATH\*(C'\fR
1.187 +(\fBMANPATH="..:\fR\fIroot\fR\fB/man:.."\fR). Keep in mind that \fBopenpkg lsync\fR
1.188 +activates any files found in the \fBman/man\f(BIN\fB\fR sub-directory of the
1.189 +package, but the \fIman\fR\|(1) tool usually requires the filename scheme
1.190 +foo\fB.\fR\fIN\fR before it can find the file.
1.191 +.IP "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
1.192 +.IX Item "root/info/foo -> ../pkgdir/bar/info/foo"
1.193 +This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
1.194 +as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
1.195 +tools by placing \fIroot\fR\fB/info\fR into the environment variable
1.196 +\&\f(CW\*(C`INFOPATH\*(C'\fR (\fBINFOPATH="..:\fR\fIroot\fR\fB/info:.."\fR). Keep in mind that
1.197 +\&\fBopenpkg lsync\fR activates any files found in the \fBinfo/\fR sub-directory of the
1.198 +package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
1.199 +scheme foo\fB.info\fR before it can find the file.
1.200 +.IP "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
1.201 +.IX Item "root/include/foo -> ../pkgdir/bar/include/foo"
1.202 +This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
1.203 +as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
1.204 +by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
1.205 +\&\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fBopenpkg lsync\fR activates any
1.206 +files found in the \fBinclude/\fR sub-directory of the package, but the
1.207 +C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
1.208 +.IP "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
1.209 +.IX Item "root/lib/foo -> ../pkgdir/bar/lib/foo"
1.210 +This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
1.211 +as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
1.212 +the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
1.213 +path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
1.214 +Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
1.215 +\&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR (\fBLD_LIBRARY_PATH="..:\fR\fIroot\fR\fB/lib:.."\fR).
1.216 +Keep in mind that \fBopenpkg lsync\fR activates any files found in the \fBlib/\fR
1.217 +sub-directory of the package, but the C/\*(C+ compiler usually require the
1.218 +filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
1.219 +scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
1.220 +.PP
1.221 +It is obvious that more sub-directories in a package installation
1.222 +might exist \*(-- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
1.223 +\&\fBopenpkg lsync\fR intentionally does not link files in those directories into
1.224 +corresponding directories of the access layer, because those files do
1.225 +not require that they are located in a global area in order to be used.
1.226 +So \fBopenpkg lsync\fR only creates the access layer for files where a common area
1.227 +is required for (easy) use.
1.228 +.SH "SPECIAL FEATURES"
1.229 +.IX Header "SPECIAL FEATURES"
1.230 +There are two special features supported by \fBopenpkg lsync\fR:
1.231 +.IP "\fBRun-Command Files\fR" 4
1.232 +.IX Item "Run-Command Files"
1.233 +\&\fBopenpkg lsync\fR on startup implicitly reads command line options from
1.234 +\&\f(CW\*(C`.lsyncrc\*(C'\fR files. They are searched in all parent directories and in
1.235 +the callers home directory. Their contents is prepended to the list of
1.236 +given command line options.
1.237 +.IP "\fBMultiple Package Versions\fR" 4
1.238 +.IX Item "Multiple Package Versions"
1.239 +\&\fBopenpkg lsync\fR skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
1.240 +the pattern \*(L"\-[0\-9]\*(R" in their directory name. On the other hand,
1.241 +\&\fBopenpkg lsync\fR follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
1.242 +This can be used for installing multiple versions of a package and
1.243 +switching between them. For instance, if version 1.0 of package
1.244 +\&\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo\-1.0,
1.245 +version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo\-1.1 and version 1.2 into
1.246 +\&\fIroot\fR/\fIpkgdir\fR/foo\-1.2, \fBopenpkg lsync\fR does skip all three. To enable
1.247 +version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
1.248 +pointing to foo\-1.1. Then \fBopenpkg lsync\fR picks up the files in
1.249 +\&\fIroot\fR/\fIpkgdir\fR/foo\-1.1. If you want to temporarily upgrade to
1.250 +foo\-1.2, all you have to do is to change the symlink pointing from
1.251 +foo\-1.1 to foo\-1.2.
1.252 +.IP "\fBTemporarily Deactivated Package\fR" 4
1.253 +.IX Item "Temporarily Deactivated Package"
1.254 +One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
1.255 +and running \*(L"openpkg lsync \-\-local \-\-uninstall\*(R", of course. Alternatively
1.256 +one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
1.257 +Then \fBopenpkg lsync\fR also skips the package. Alternatively, assume
1.258 +package \*(L"foo\*(R" as a whole should not be deactivated, but its
1.259 +\&\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
1.260 +unfortunately contains non-library files), one just sets the sticky bit
1.261 +on \fIroot\fR/\fIpkgdir\fR/foo/lib.
1.262 +.SH "OPTIONS"
1.263 +.IX Header "OPTIONS"
1.264 +.IP "\fB\-\-version\fR, \fB\-v\fR" 4
1.265 +.IX Item "--version, -v"
1.266 +Display program version information only.
1.267 +.IP "\fB\-\-help\fR, \fB\-h\fR" 4
1.268 +.IX Item "--help, -h"
1.269 +Display program usage information only.
1.270 +.IP "\fB\-\-init\fR, \fB\-i\fR" 4
1.271 +.IX Item "--init, -i"
1.272 +Create an initial access layer hierarchy under \fIroot\fR.
1.273 +.IP "\fB\-\-nop\fR, \fB\-n\fR" 4
1.274 +.IX Item "--nop, -n"
1.275 +No Operation \*(-- causes \fBopenpkg lsync\fR to not perform any filesystem
1.276 +operations. In conjunction with \fB\-\-trace\fR you can at least see what
1.277 +would be executed.
1.278 +.IP "\fB\-\-quiet\fR, \fB\-q\fR" 4
1.279 +.IX Item "--quiet, -q"
1.280 +Forces \fBopenpkg lsync\fR to perform the operations quietly, i.e., without any
1.281 +verbose messages.
1.282 +.IP "\fB\-\-trace\fR, \fB\-t\fR" 4
1.283 +.IX Item "--trace, -t"
1.284 +Forces \fBopenpkg lsync\fR to show what filesystem operations are performed.
1.285 +.IP "\fB\-\-local\fR, \fB\-l\fR" 4
1.286 +.IX Item "--local, -l"
1.287 +This restricts the operations to a local package area. This option can
1.288 +only be used if you are physically staying below a package sub-directory
1.289 +under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
1.290 +\&\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB\-\-local\fR,
1.291 +all operations are restricted to the package \*(L"bar\*(R".
1.292 +.IP "\fB\-\-uninstall\fR, \fB\-u\fR" 4
1.293 +.IX Item "--uninstall, -u"
1.294 +This performs only package uninstallation operations, i.e., only
1.295 +symbolic links are removed. This can be used to completely empty the
1.296 +access layer. Additionally it is very useful in combination with
1.297 +\&\fB\-\-local\fR in order to uninstall a particular package without having to
1.298 +remove its files.
1.299 +.IP "\fB\-\-root=\fR\fIroot\fR" 4
1.300 +.IX Item "--root=root"
1.301 +Sets the root directory where the access layer and package subdirectory
1.302 +is located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
1.303 +(see section \*(L"Current configuration\*(R").
1.304 +.IP "\fB\-\-pkgdir=\fR\fIpkgdir\fR" 4
1.305 +.IX Item "--pkgdir=pkgdir"
1.306 +Sets the sub-directory under the root directory where packages are
1.307 +located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR (see
1.308 +section \*(L"Current configuration\*(R").
1.309 +.IP "\fB\-\-subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
1.310 +.IX Item "--subdirs=subdirs[,subdir,...]"
1.311 +Sets one or more sub-directories of the access layer on which \fBopenpkg lsync\fR
1.312 +should act. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
1.313 +(see section \*(L"Current configuration\*(R").
1.314 +.SH "RESULTS"
1.315 +.IX Header "RESULTS"
1.316 +This program uses the following return codes on exit: 0 (operation
1.317 +successful), 1 (system error), 2 (command line error) and 3 (other user
1.318 +error).
1.319 +.SH "HISTORY"
1.320 +.IX Header "HISTORY"
1.321 +The idea of filesystem access layers consisting of symbolic links
1.322 +pointing to actual package installation areas is a rather old one. It
1.323 +dates back to the early days of Unix and was implemented many times over
1.324 +the last decades. One of many implementation was \fBGenOPT\fR, written by
1.325 +Ralf S. Engelschall for sd&m GmbH & Co \s-1KG\s0, Munich in 1992. The name
1.326 +indicates the programs purpose: to generate symbolic links in an access
1.327 +layer which was located under \f(CW\*(C`/opt\*(C'\fR. \fBGenOPT\fR was very flexible, but
1.328 +hence also very complex. Because of lack of documentation it was never
1.329 +released and so only used at sd&m and on all machines which were under
1.330 +control of Ralf S. Engelschall.
1.331 +.PP
1.332 +For Cable & Wireless, Munich, the old \fBGenOPT\fR principle was again
1.333 +needed to manage the \f(CW\*(C`/cw/local\*(C'\fR area on their servers. For this in
1.334 +November 2000 the functionality of \fBGenOPT\fR was revised, heavily
1.335 +stripped down and finally implemented from scratch. The result is the
1.336 +current \fBopenpkg lsync\fR.
1.337 +.SH "AUTHOR"
1.338 +.IX Header "AUTHOR"
1.339 +.Vb 3
1.340 +\& Ralf S. Engelschall
1.341 +\& rse@engelschall.com
1.342 +\& www.engelschall.com
1.343 +.Ve
