michael@428: .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
michael@13: .\"
michael@13: .\" Standard preamble:
michael@13: .\" ========================================================================
michael@13: .de Sp \" Vertical space (when we can't use .PP)
michael@13: .if t .sp .5v
michael@13: .if n .sp
michael@13: ..
michael@13: .de Vb \" Begin verbatim text
michael@13: .ft CW
michael@13: .nf
michael@13: .ne \\$1
michael@13: ..
michael@13: .de Ve \" End verbatim text
michael@13: .ft R
michael@13: .fi
michael@13: ..
michael@13: .\" Set up some character translations and predefined strings.  \*(-- will
michael@13: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
michael@428: .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
michael@428: .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
michael@428: .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
michael@428: .\" nothing in troff, for use with C<>.
michael@428: .tr \(*W-
michael@13: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
michael@13: .ie n \{\
michael@13: .    ds -- \(*W-
michael@13: .    ds PI pi
michael@13: .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
michael@13: .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
michael@13: .    ds L" ""
michael@13: .    ds R" ""
michael@13: .    ds C` 
michael@13: .    ds C' 
michael@13: 'br\}
michael@13: .el\{\
michael@13: .    ds -- \|\(em\|
michael@13: .    ds PI \(*p
michael@13: .    ds L" ``
michael@13: .    ds R" ''
michael@13: 'br\}
michael@13: .\"
michael@428: .\" Escape single quotes in literal strings from groff's Unicode transform.
michael@428: .ie \n(.g .ds Aq \(aq
michael@428: .el       .ds Aq '
michael@428: .\"
michael@13: .\" If the F register is turned on, we'll generate index entries on stderr for
michael@428: .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
michael@13: .\" entries marked with X<> in POD.  Of course, you'll have to process the
michael@13: .\" output yourself in some meaningful fashion.
michael@428: .ie \nF \{\
michael@13: .    de IX
michael@13: .    tm Index:\\$1\t\\n%\t"\\$2"
michael@13: ..
michael@13: .    nr % 0
michael@13: .    rr F
michael@13: .\}
michael@428: .el \{\
michael@428: .    de IX
michael@428: ..
michael@428: .\}
michael@13: .\"
michael@13: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
michael@13: .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
michael@13: .    \" fudge factors for nroff and troff
michael@13: .if n \{\
michael@13: .    ds #H 0
michael@13: .    ds #V .8m
michael@13: .    ds #F .3m
michael@13: .    ds #[ \f1
michael@13: .    ds #] \fP
michael@13: .\}
michael@13: .if t \{\
michael@13: .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
michael@13: .    ds #V .6m
michael@13: .    ds #F 0
michael@13: .    ds #[ \&
michael@13: .    ds #] \&
michael@13: .\}
michael@13: .    \" simple accents for nroff and troff
michael@13: .if n \{\
michael@13: .    ds ' \&
michael@13: .    ds ` \&
michael@13: .    ds ^ \&
michael@13: .    ds , \&
michael@13: .    ds ~ ~
michael@13: .    ds /
michael@13: .\}
michael@13: .if t \{\
michael@13: .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
michael@13: .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
michael@13: .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
michael@13: .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
michael@13: .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
michael@13: .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
michael@13: .\}
michael@13: .    \" troff and (daisy-wheel) nroff accents
michael@13: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
michael@13: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
michael@13: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
michael@13: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
michael@13: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
michael@13: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
michael@13: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
michael@13: .ds ae a\h'-(\w'a'u*4/10)'e
michael@13: .ds Ae A\h'-(\w'A'u*4/10)'E
michael@13: .    \" corrections for vroff
michael@13: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
michael@13: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
michael@13: .    \" for low resolution devices (crt and lpr)
michael@13: .if \n(.H>23 .if \n(.V>19 \
michael@13: \{\
michael@13: .    ds : e
michael@13: .    ds 8 ss
michael@13: .    ds o a
michael@13: .    ds d- d\h'-1'\(ga
michael@13: .    ds D- D\h'-1'\(hy
michael@13: .    ds th \o'bp'
michael@13: .    ds Th \o'LP'
michael@13: .    ds ae ae
michael@13: .    ds Ae AE
michael@13: .\}
michael@13: .rm #[ #] #H #V #F C
michael@13: .\" ========================================================================
michael@13: .\"
michael@13: .IX Title "LSYNC 8"
michael@13: .TH LSYNC 8 "OpenPKG" "LSYNC(8)" "OpenPKG"
michael@428: .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
michael@428: .\" way too many mistakes in technical documents.
michael@428: .if n .ad l
michael@428: .nh
michael@13: .SH "NAME"
michael@428: openpkg lsync \- Access Layer Synchronization Tool
michael@13: .SH "SYNOPSIS"
michael@13: .IX Header "SYNOPSIS"
michael@13: \&\fBopenpkg lsync\fR
michael@13: [\fB\-\-version\fR|\fB\-v\fR]
michael@13: [\fB\-\-help\fR|\fB\-h\fR]
michael@13: [\fB\-\-init\fR|\fB\-i\fR]
michael@13: [\fB\-\-nop\fR|\fB\-n\fR]
michael@13: [\fB\-\-quiet\fR|\fB\-q\fR]
michael@13: [\fB\-\-trace\fR|\fB\-t\fR]
michael@13: [\fB\-\-local\fR|\fB\-l\fR]
michael@13: [\fB\-\-uninstall\fR|\fB\-u\fR]
michael@13: [\fB\-\-root=\fR\fIroot\fR]
michael@13: [\fB\-\-pkgdir=\fR\fIpkgdir\fR]
michael@13: [\fB\-\-subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
michael@13: .SH "DESCRIPTION"
michael@13: .IX Header "DESCRIPTION"
michael@13: This program activates software packages which were locally
michael@13: installed in a sub-directory of a package hierarchy (located under
michael@13: \&\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
michael@13: (located under \fIroot\fR/) corresponding to package installation
michael@13: files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
michael@13: collected in global directories (located under \fIroot\fR/subdir/).
michael@13: .PP
michael@13: The purpose of this is that individual packages can be installed and
michael@13: deinstalled seperately without interfering with other packages while
michael@13: all packages as a whole still can be treated like a single package
michael@13: (installed into the access layer).
michael@13: .PP
michael@13: The
michael@13: actual creation of symbolic links is as following (\*(L"foo\*(R" indicating an
michael@13: arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
michael@13: .IP "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
michael@13: .IX Item "root/bin/foo -> ../pkgdir/bar/bin/foo"
michael@13: This activates the user executeable
michael@13: \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
michael@13: be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
michael@13: variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/bin:.."\fR).
michael@13: .IP "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
michael@13: .IX Item "root/sbin/foo -> ../pkgdir/bar/sbin/foo"
michael@13: This activates the system executeable
michael@13: \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
michael@13: be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
michael@13: variable \f(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/sbin:.."\fR).
michael@13: .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
michael@13: .IX Item "root/man/manN/foo -> ../pkgdir/bar/man/manN/foo"
michael@13: This activates the Unix manual page
michael@13: \&\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
michael@13: \&\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
michael@13: by placing \fIroot\fR\fB/man\fR into the environment variable \f(CW\*(C`MANPATH\*(C'\fR
michael@13: (\fBMANPATH="..:\fR\fIroot\fR\fB/man:.."\fR). Keep in mind that \fBopenpkg lsync\fR
michael@13: activates any files found in the \fBman/man\f(BIN\fB\fR sub-directory of the
michael@13: package, but the \fIman\fR\|(1) tool usually requires the filename scheme
michael@13: foo\fB.\fR\fIN\fR before it can find the file.
michael@13: .IP "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
michael@13: .IX Item "root/info/foo -> ../pkgdir/bar/info/foo"
michael@13: This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
michael@13: as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
michael@13: tools by placing \fIroot\fR\fB/info\fR into the environment variable
michael@13: \&\f(CW\*(C`INFOPATH\*(C'\fR (\fBINFOPATH="..:\fR\fIroot\fR\fB/info:.."\fR). Keep in mind that
michael@13: \&\fBopenpkg lsync\fR activates any files found in the \fBinfo/\fR sub-directory of the
michael@13: package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
michael@13: scheme foo\fB.info\fR before it can find the file.
michael@13: .IP "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
michael@13: .IX Item "root/include/foo -> ../pkgdir/bar/include/foo"
michael@13: This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
michael@13: as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
michael@13: by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
michael@13: \&\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fBopenpkg lsync\fR activates any
michael@13: files found in the \fBinclude/\fR sub-directory of the package, but the
michael@13: C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
michael@13: .IP "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
michael@13: .IX Item "root/lib/foo -> ../pkgdir/bar/lib/foo"
michael@13: This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
michael@13: as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
michael@13: the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
michael@13: path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
michael@13: Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
michael@13: \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR (\fBLD_LIBRARY_PATH="..:\fR\fIroot\fR\fB/lib:.."\fR).
michael@13: Keep in mind that \fBopenpkg lsync\fR activates any files found in the \fBlib/\fR
michael@13: sub-directory of the package, but the C/\*(C+ compiler usually require the
michael@13: filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
michael@13: scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
michael@13: .PP
michael@13: It is obvious that more sub-directories in a package installation
michael@13: might exist \*(-- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
michael@13: \&\fBopenpkg lsync\fR intentionally does not link files in those directories into
michael@13: corresponding directories of the access layer, because those files do
michael@13: not require that they are located in a global area in order to be used.
michael@13: So \fBopenpkg lsync\fR only creates the access layer for files where a common area
michael@13: is required for (easy) use.
michael@13: .SH "SPECIAL FEATURES"
michael@13: .IX Header "SPECIAL FEATURES"
michael@13: There are two special features supported by \fBopenpkg lsync\fR:
michael@13: .IP "\fBRun-Command Files\fR" 4
michael@13: .IX Item "Run-Command Files"
michael@13: \&\fBopenpkg lsync\fR on startup implicitly reads command line options from
michael@13: \&\f(CW\*(C`.lsyncrc\*(C'\fR files. They are searched in all parent directories and in
michael@13: the callers home directory. Their contents is prepended to the list of
michael@13: given command line options.
michael@13: .IP "\fBMultiple Package Versions\fR" 4
michael@13: .IX Item "Multiple Package Versions"
michael@13: \&\fBopenpkg lsync\fR skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
michael@13: the pattern \*(L"\-[0\-9]\*(R" in their directory name. On the other hand,
michael@13: \&\fBopenpkg lsync\fR follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
michael@13: This can be used for installing multiple versions of a package and
michael@13: switching between them. For instance, if version 1.0 of package
michael@13: \&\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo\-1.0,
michael@13: version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo\-1.1 and version 1.2 into
michael@13: \&\fIroot\fR/\fIpkgdir\fR/foo\-1.2, \fBopenpkg lsync\fR does skip all three. To enable
michael@13: version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
michael@13: pointing to foo\-1.1. Then \fBopenpkg lsync\fR picks up the files in
michael@13: \&\fIroot\fR/\fIpkgdir\fR/foo\-1.1. If you want to temporarily upgrade to
michael@13: foo\-1.2, all you have to do is to change the symlink pointing from
michael@13: foo\-1.1 to foo\-1.2.
michael@13: .IP "\fBTemporarily Deactivated Package\fR" 4
michael@13: .IX Item "Temporarily Deactivated Package"
michael@13: One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
michael@13: and running \*(L"openpkg lsync \-\-local \-\-uninstall\*(R", of course. Alternatively
michael@13: one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
michael@13: Then \fBopenpkg lsync\fR also skips the package. Alternatively, assume
michael@13: package \*(L"foo\*(R" as a whole should not be deactivated, but its
michael@13: \&\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
michael@13: unfortunately contains non-library files), one just sets the sticky bit
michael@13: on \fIroot\fR/\fIpkgdir\fR/foo/lib.
michael@13: .SH "OPTIONS"
michael@13: .IX Header "OPTIONS"
michael@13: .IP "\fB\-\-version\fR, \fB\-v\fR" 4
michael@13: .IX Item "--version, -v"
michael@13: Display program version information only.
michael@13: .IP "\fB\-\-help\fR, \fB\-h\fR" 4
michael@13: .IX Item "--help, -h"
michael@13: Display program usage information only.
michael@13: .IP "\fB\-\-init\fR, \fB\-i\fR" 4
michael@13: .IX Item "--init, -i"
michael@13: Create an initial access layer hierarchy under \fIroot\fR.
michael@13: .IP "\fB\-\-nop\fR, \fB\-n\fR" 4
michael@13: .IX Item "--nop, -n"
michael@13: No Operation \*(-- causes \fBopenpkg lsync\fR to not perform any filesystem
michael@13: operations. In conjunction with \fB\-\-trace\fR you can at least see what
michael@13: would be executed.
michael@13: .IP "\fB\-\-quiet\fR, \fB\-q\fR" 4
michael@13: .IX Item "--quiet, -q"
michael@13: Forces \fBopenpkg lsync\fR to perform the operations quietly, i.e., without any
michael@13: verbose messages.
michael@13: .IP "\fB\-\-trace\fR, \fB\-t\fR" 4
michael@13: .IX Item "--trace, -t"
michael@13: Forces \fBopenpkg lsync\fR to show what filesystem operations are performed.
michael@13: .IP "\fB\-\-local\fR, \fB\-l\fR" 4
michael@13: .IX Item "--local, -l"
michael@13: This restricts the operations to a local package area. This option can
michael@13: only be used if you are physically staying below a package sub-directory
michael@13: under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
michael@13: \&\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB\-\-local\fR,
michael@13: all operations are restricted to the package \*(L"bar\*(R".
michael@13: .IP "\fB\-\-uninstall\fR, \fB\-u\fR" 4
michael@13: .IX Item "--uninstall, -u"
michael@13: This performs only package uninstallation operations, i.e., only
michael@13: symbolic links are removed. This can be used to completely empty the
michael@13: access layer. Additionally it is very useful in combination with
michael@13: \&\fB\-\-local\fR in order to uninstall a particular package without having to
michael@13: remove its files.
michael@13: .IP "\fB\-\-root=\fR\fIroot\fR" 4
michael@13: .IX Item "--root=root"
michael@13: Sets the root directory where the access layer and package subdirectory
michael@13: is located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
michael@13: (see section \*(L"Current configuration\*(R").
michael@13: .IP "\fB\-\-pkgdir=\fR\fIpkgdir\fR" 4
michael@13: .IX Item "--pkgdir=pkgdir"
michael@13: Sets the sub-directory under the root directory where packages are
michael@13: located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR (see
michael@13: section \*(L"Current configuration\*(R").
michael@13: .IP "\fB\-\-subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
michael@13: .IX Item "--subdirs=subdirs[,subdir,...]"
michael@13: Sets one or more sub-directories of the access layer on which \fBopenpkg lsync\fR
michael@13: should act. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR
michael@13: (see section \*(L"Current configuration\*(R").
michael@13: .SH "RESULTS"
michael@13: .IX Header "RESULTS"
michael@13: This program uses the following return codes on exit: 0 (operation
michael@13: successful), 1 (system error), 2 (command line error) and 3 (other user
michael@13: error).
michael@13: .SH "HISTORY"
michael@13: .IX Header "HISTORY"
michael@13: The idea of filesystem access layers consisting of symbolic links
michael@13: pointing to actual package installation areas is a rather old one. It
michael@13: dates back to the early days of Unix and was implemented many times over
michael@13: the last decades. One of many implementation was \fBGenOPT\fR, written by
michael@13: Ralf S. Engelschall for sd&m GmbH & Co \s-1KG\s0, Munich in 1992. The name
michael@13: indicates the programs purpose: to generate symbolic links in an access
michael@13: layer which was located under \f(CW\*(C`/opt\*(C'\fR. \fBGenOPT\fR was very flexible, but
michael@13: hence also very complex. Because of lack of documentation it was never
michael@13: released and so only used at sd&m and on all machines which were under
michael@13: control of Ralf S. Engelschall.
michael@13: .PP
michael@13: For Cable & Wireless, Munich, the old \fBGenOPT\fR principle was again
michael@13: needed to manage the \f(CW\*(C`/cw/local\*(C'\fR area on their servers. For this in
michael@13: November 2000 the functionality of \fBGenOPT\fR was revised, heavily
michael@13: stripped down and finally implemented from scratch. The result is the
michael@13: current \fBopenpkg lsync\fR.
michael@13: .SH "AUTHOR"
michael@13: .IX Header "AUTHOR"
michael@13: .Vb 3
michael@13: \& Ralf S. Engelschall
michael@13: \& rse@engelschall.com
michael@13: \& www.engelschall.com
michael@13: .Ve