diff -r 333964c621f1 -r cb59d6afeb61 openpkg/lsync.8 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/openpkg/lsync.8 Tue Jan 06 23:40:39 2009 +0100 @@ -0,0 +1,340 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.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. | will give a +.\" real vertical bar. \*(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-|\(bv\*(Tr +.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\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" 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" +.SH "NAME" +\&\fBopenpkg lsync\fR \- 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