OpenPKG Specs / file revision

 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)

 .\"

 .\" Standard preamble:

 .\" ========================================================================

 .de Sp \" Vertical space (when we can't use .PP)

 .if t .sp .5v

 .if n .sp

 ..

 .de Vb \" Begin verbatim text

 .ft CW

 .nf

 .ne \\$1

 ..

 .de Ve \" End verbatim text

 .ft R

 .fi

 ..

 .\" Set up some character translations and predefined strings.  \*(-- will

 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will

 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and

 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,

 .\" nothing in troff, for use with C<>.

 .tr \(*W-

 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

 .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" ""

 .    ds C` 

 .    ds C' 

 'br\}

 .el\{\

 .    ds -- \|\(em\|

 .    ds PI \(*p

 .    ds L" ``

 .    ds R" ''

 'br\}

 .\"

 .\" Escape single quotes in literal strings from groff's Unicode transform.

 .ie \n(.g .ds Aq \(aq

 .el       .ds Aq '

 .\"

 .\" If the F register is turned on, we'll generate index entries on stderr for

 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index

 .\" entries marked with X<> in POD.  Of course, you'll have to process the

 .\" output yourself in some meaningful fashion.

 .ie \nF \{\

 .    de IX

 .    tm Index:\\$1\t\\n%\t"\\$2"

 ..

 .    nr % 0

 .    rr F

 .\}

 .el \{\

 .    de IX

 ..

 .\}

 .\"

 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.

 .    \" 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 /

 .\}

 .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 / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

 .\}

 .    \" 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 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

 .    \" 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 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

 .\}

 .rm #[ #] #H #V #F C

 .\" ========================================================================

 .\"

 .IX Title "LSYNC 8"

 .TH LSYNC 8 "OpenPKG" "LSYNC(8)" "OpenPKG"

 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes

 .\" way too many mistakes in technical documents.

 .if n .ad l

 .nh

 .SH "NAME"

 openpkg lsync \- Access Layer Synchronization Tool

 .SH "SYNOPSIS"

 .IX Header "SYNOPSIS"

 \&\fBopenpkg lsync\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"

 .IX Header "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 (\*(L"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

 .IX Item "root/bin/foo -> ../pkgdir/bar/bin/foo"

 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(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/bin:.."\fR).

 .IP "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4

 .IX Item "root/sbin/foo -> ../pkgdir/bar/sbin/foo"

 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(CW\*(C`PATH\*(C'\fR (\fBPATH="..:\fR\fIroot\fR\fB/sbin:.."\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

 .IX Item "root/man/manN/foo -> ../pkgdir/bar/man/manN/foo"

 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(CW\*(C`MANPATH\*(C'\fR

 (\fBMANPATH="..:\fR\fIroot\fR\fB/man:.."\fR). Keep in mind that \fBopenpkg lsync\fR

 activates any files found in the \fBman/man\f(BIN\fB\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

 .IX Item "root/info/foo -> ../pkgdir/bar/info/foo"

 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(CW\*(C`INFOPATH\*(C'\fR (\fBINFOPATH="..:\fR\fIroot\fR\fB/info:.."\fR). Keep in mind that

 \&\fBopenpkg lsync\fR 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

 .IX Item "root/include/foo -> ../pkgdir/bar/include/foo"

 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 \fBopenpkg lsync\fR 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

 .IX Item "root/lib/foo -> ../pkgdir/bar/lib/foo"

 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(CW\*(C`LD_LIBRARY_PATH\*(C'\fR (\fBLD_LIBRARY_PATH="..:\fR\fIroot\fR\fB/lib:.."\fR).

 Keep in mind that \fBopenpkg lsync\fR 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

 \&\fBopenpkg lsync\fR 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 \fBopenpkg lsync\fR only creates the access layer for files where a common area

 is required for (easy) use.

 .SH "SPECIAL FEATURES"

 .IX Header "SPECIAL FEATURES"

 There are two special features supported by \fBopenpkg lsync\fR:

 .IP "\fBRun-Command Files\fR" 4

 .IX Item "Run-Command Files"

 \&\fBopenpkg lsync\fR on startup implicitly reads command line options from

 \&\f(CW\*(C`.lsyncrc\*(C'\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

 .IX Item "Multiple Package Versions"

 \&\fBopenpkg lsync\fR skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain

 the pattern \*(L"\-[0\-9]\*(R" in their directory name. On the other hand,

 \&\fBopenpkg lsync\fR 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, \fBopenpkg lsync\fR 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 \fBopenpkg lsync\fR 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

 .IX Item "Temporarily Deactivated Package"

 One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/

 and running \*(L"openpkg lsync \-\-local \-\-uninstall\*(R", of course. Alternatively

 one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.

 Then \fBopenpkg lsync\fR 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"

 .IX Header "OPTIONS"

 .IP "\fB\-\-version\fR, \fB\-v\fR" 4

 .IX Item "--version, -v"

 Display program version information only.

 .IP "\fB\-\-help\fR, \fB\-h\fR" 4

 .IX Item "--help, -h"

 Display program usage information only.

 .IP "\fB\-\-init\fR, \fB\-i\fR" 4

 .IX Item "--init, -i"

 Create an initial access layer hierarchy under \fIroot\fR.

 .IP "\fB\-\-nop\fR, \fB\-n\fR" 4

 .IX Item "--nop, -n"

 No Operation \*(-- causes \fBopenpkg lsync\fR 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

 .IX Item "--quiet, -q"

 Forces \fBopenpkg lsync\fR to perform the operations quietly, i.e., without any

 verbose messages.

 .IP "\fB\-\-trace\fR, \fB\-t\fR" 4

 .IX Item "--trace, -t"

 Forces \fBopenpkg lsync\fR to show what filesystem operations are performed.

 .IP "\fB\-\-local\fR, \fB\-l\fR" 4

 .IX Item "--local, -l"

 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

 .IX Item "--uninstall, -u"

 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

 .IX Item "--root=root"

 Sets the root directory where the access layer and package subdirectory

 is located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR

 (see section \*(L"Current configuration\*(R").

 .IP "\fB\-\-pkgdir=\fR\fIpkgdir\fR" 4

 .IX Item "--pkgdir=pkgdir"

 Sets the sub-directory under the root directory where packages are

 located. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR (see

 section \*(L"Current configuration\*(R").

 .IP "\fB\-\-subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4

 .IX Item "--subdirs=subdirs[,subdir,...]"

 Sets one or more sub-directories of the access layer on which \fBopenpkg lsync\fR

 should act. The default can be determined by running \f(CW\*(C`openpkg lsync \-\-help\*(C'\fR

 (see section \*(L"Current configuration\*(R").

 .SH "RESULTS"

 .IX Header "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"

 .IX Header "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 \s-1KG\s0, Munich in 1992. The name

 indicates the programs purpose: to generate symbolic links in an access

 layer which was located under \f(CW\*(C`/opt\*(C'\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, Munich, the old \fBGenOPT\fR principle was again

 needed to manage the \f(CW\*(C`/cw/local\*(C'\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 \fBopenpkg lsync\fR.

 .SH "AUTHOR"

 .IX Header "AUTHOR"

 .Vb 3

 \& Ralf S. Engelschall

 \& rse@engelschall.com

 \& www.engelschall.com

 .Ve