openpkg-packages/openpkg/lsync.8

.rn '' }`
''' $RCSfile$$Revision$$Date$
'''
''' $Log$
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.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" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH LSYNC 1 "perl 5.005, patch 03" "18/Sep/2001" "User Contributed Perl Documentation"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" 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 ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.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 ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" 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 v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.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
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'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 v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	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
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
\fBlsync\fR \- Access Layer Synchronization Tool
.SH "SYNOPSIS"
\fBlsync\fR
[\fB--version\fR|\fB\-v\fR]
[\fB--help\fR|\fB\-h\fR]
[\fB--init\fR|\fB\-i\fR]
[\fB--nop\fR|\fB\-n\fR]
[\fB--quiet\fR|\fB\-q\fR]
[\fB--trace\fR|\fB\-t\fR]
[\fB--local\fR|\fB\-l\fR]
[\fB--uninstall\fR|\fB\-u\fR]
[\fB--root=\fR\fIroot\fR]
[\fB--pkgdir=\fR\fIpkgdir\fR]
[\fB--subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
.SH "DESCRIPTION"
This program activates software packages which were locally
installed in a sub-directory of a package hierarchy (located under
\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
(located under \fIroot\fR/) corresponding to package installation
files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
collected in global directories (located under \fIroot\fR/subdir/). 
.PP
The purpose of this is that individual packages can be installed and
deinstalled seperately without interfering with other packages while
all packages as a whole still can be treated like a single package
(installed into the access layer).
.PP
The
actual creation of symbolic links is as following ("foo\*(R" indicating an
arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
.Ip "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
This activates the user executeable
\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
variable \f(CWPATH\fR (\fB\s-1PATH\s0=\*(R"..:\fR\fIroot\fR\fB/bin:..\*(R"\fR).
.Ip "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
This activates the system executeable
\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
variable \f(CWPATH\fR (\fB\s-1PATH\s0=\*(R"..:\fR\fIroot\fR\fB/sbin:..\*(R"\fR).
.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
This activates the Unix manual page
\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
by placing \fIroot\fR\fB/man\fR into the environment variable \f(CWMANPATH\fR
(\fB\s-1MANPATH\s0=\*(R"..:\fR\fIroot\fR\fB/man:..\*(R"\fR). Keep in mind that \fIlsync\fR\|(1)
activates any files found in the \fBman/man\fIN\fR\fR sub-directory of the
package, but the \fIman\fR\|(1) tool usually requires the filename scheme
foo\fB.\fR\fIN\fR before it can find the file.
.Ip "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
tools by placing \fIroot\fR\fB/info\fR into the environment variable
\f(CWINFOPATH\fR (\fB\s-1INFOPATH\s0=\*(R"..:\fR\fIroot\fR\fB/info:..\*(R"\fR). Keep in mind that
\fIlsync\fR\|(1) activates any files found in the \fBinfo/\fR sub-directory of the
package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
scheme foo\fB.info\fR before it can find the file.
.Ip "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fIlsync\fR\|(1) activates any
files found in the \fBinclude/\fR sub-directory of the package, but the
C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
.Ip "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
\f(CWLD_LIBRARY_PATH\fR (\fB\s-1LD_LIBRARY_PATH\s0=\*(R"..:\fR\fIroot\fR\fB/lib:..\*(R"\fR).
Keep in mind that \fIlsync\fR\|(1) activates any files found in the \fBlib/\fR
sub-directory of the package, but the C/\*(C+ compiler usually require the
filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
.PP
It is obvious that more sub-directories in a package installation
might exist -- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
\fIlsync\fR\|(1) intentionally does not link files in those directories into
corresponding directories of the access layer, because those files do
not require that they are located in a global area in order to be used.
So \fIlsync\fR\|(1) only creates the access layer for files where a common area
is required for (easy) use.
.SH "SPECIAL FEATURES"
There are two special features supported by \fIlsync\fR\|(1):
.Ip "\fBRun-Command Files\fR" 4
\fIlsync\fR\|(1) on startup implicitly reads command line options from
\&\f(CW.lsyncrc\fR files. They are searched in all parent directories and in
the callers home directory. Their contents is prepended to the list of
given command line options.
.Ip "\fBMultiple Package Versions\fR" 4
\fIlsync\fR\|(1) skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
the pattern \*(L"\-[0-9]\*(R" in their directory name. On the other hand,
\fIlsync\fR\|(1) follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
This can be used for installing multiple versions of a package and
switching between them. For instance, if version 1.0 of package
\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo-1.0,
version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo-1.1 and version 1.2 into
\fIroot\fR/\fIpkgdir\fR/foo-1.2, \fIlsync\fR\|(1) does skip all three. To enable
version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
pointing to foo-1.1. Then \fIlsync\fR\|(1) picks up the files in
\fIroot\fR/\fIpkgdir\fR/foo-1.1. If you want to temporarily upgrade to
foo-1.2, all you have to do is to change the symlink pointing from
foo-1.1 to foo-1.2.
.Ip "\fBTemporarily Deactivated Package\fR" 4
One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
and running \*(L"lsync --local --uninstall\*(R", of course. Alternatively
one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
Then \fIlsync\fR\|(1) also skips the package. Alternatively, assume
package \*(L"foo\*(R" as a whole should not be deactivated, but its
\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
unfortunately contains non-library files), one just sets the sticky bit
on \fIroot\fR/\fIpkgdir\fR/foo/lib.
.SH "OPTIONS"
.Ip "\fB--version\fR, \fB\-v\fR" 4
Display program version information only.
.Ip "\fB--help\fR, \fB\-h\fR" 4
Display program usage information only.
.Ip "\fB--init\fR, \fB\-i\fR" 4
Create an initial access layer hierarchy under \fIroot\fR.
.Ip "\fB--nop\fR, \fB\-n\fR" 4
No Operation -- causes \fIlsync\fR\|(1) to not perform any filesystem
operations. In conjunction with \fB--trace\fR you can at least see what
would be executed.
.Ip "\fB--quiet\fR, \fB\-q\fR" 4
Forces \fIlsync\fR\|(1) to perform the operations quietly, i.e., without any
verbose messages.
.Ip "\fB--trace\fR, \fB\-t\fR" 4
Forces \fIlsync\fR\|(1) to show what filesystem operations are performed.
.Ip "\fB--local\fR, \fB\-l\fR" 4
This restricts the operations to a local package area. This option can
only be used if you are physically staying below a package sub-directory
under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB--local\fR,
all operations are restricted to the package \*(L"bar\*(R".
.Ip "\fB--uninstall\fR, \fB\-u\fR" 4
This performs only package uninstallation operations, i.e., only
symbolic links are removed. This can be used to completely empty the
access layer. Additionally it is very useful in combination with
\fB--local\fR in order to uninstall a particular package without having to
remove its files.
.Ip "\fB--root=\fR\fIroot\fR" 4
Sets the root directory where the access layer and package subdirectory
is located. The default can be determined by running \f(CWlsync --help\fR
(see section \*(L"Current configuration").
.Ip "\fB--pkgdir=\fR\fIpkgdir\fR" 4
Sets the sub-directory under the root directory where packages are
located. The default can be determined by running \f(CWlsync --help\fR (see
section \*(L"Current configuration").
.Ip "\fB--subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
Sets one or more sub-directories of the access layer on which \fIlsync\fR\|(1)
should act. The default can be determined by running \f(CWlsync --help\fR
(see section \*(L"Current configuration").
.SH "RESULTS"
This program uses the following return codes on exit: 0 (operation
successful), 1 (system error), 2 (command line error) and 3 (other user
error).
.SH "HISTORY"
The idea of filesystem access layers consisting of symbolic links
pointing to actual package installation areas is a rather old one. It
dates back to the early days of Unix and was implemented many times over
the last decades. One of many implementation was \fBGenOPT\fR, written by
Ralf S. Engelschall for sd&m GmbH & Co KG, Munich in 1992. The name
indicates the programs purpose: to generate symbolic links in an access
layer which was located under \f(CW/opt\fR. \fBGenOPT\fR was very flexible, but
hence also very complex. Because of lack of documentation it was never
released and so only used at sd&m and on all machines which were under
control of Ralf S. Engelschall.
.PP
For Cable & Wireless Deutschland GmbH, Munich, the old \fBGenOPT\fR
principle was again needed to manage the \f(CW/cw/local\fR area on their
servers. For this in November 2000 the functionality of \fBGenOPT\fR was
revised, heavily stripped down and finally implemented from scratch. The
result is the current \fBLSync\fR.
.SH "AUTHOR"
.PP
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve

.rn }` ''
.IX Title "LSYNC 1"
.IX Name "B<lsync> - Access Layer Synchronization Tool"

.IX Header "NAME"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Item "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo"

.IX Item "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo"

.IX Item "\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo"

.IX Item "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo"

.IX Item "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo"

.IX Item "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo"

.IX Header "SPECIAL FEATURES"

.IX Item "\fBRun-Command Files\fR"

.IX Item "\fBMultiple Package Versions\fR"

.IX Item "\fBTemporarily Deactivated Package\fR"

.IX Header "OPTIONS"

.IX Item "\fB--version\fR, \fB\-v\fR"

.IX Item "\fB--help\fR, \fB\-h\fR"

.IX Item "\fB--init\fR, \fB\-i\fR"

.IX Item "\fB--nop\fR, \fB\-n\fR"

.IX Item "\fB--quiet\fR, \fB\-q\fR"

.IX Item "\fB--trace\fR, \fB\-t\fR"

.IX Item "\fB--local\fR, \fB\-l\fR"

.IX Item "\fB--uninstall\fR, \fB\-u\fR"

.IX Item "\fB--root=\fR\fIroot\fR"

.IX Item "\fB--pkgdir=\fR\fIpkgdir\fR"

.IX Item "\fB--subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]"

.IX Header "RESULTS"

.IX Header "HISTORY"

.IX Header "AUTHOR"