OpenPKG Specs / file revision

 ##

 ##  lsync.pod -- Access Layer Synchronization Tool (Manual Page)

 ##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>

 ##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>

 ##

 ##  Permission to use, copy, modify, and distribute this software for

 ##  any purpose with or without fee is hereby granted, provided that

 ##  the above copyright notice and this permission notice appear in all

 ##  copies.

 ##

 ##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

 ##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

 ##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

 ##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR

 ##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 ##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 ##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

 ##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

 ##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

 ##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

 ##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

 ##  SUCH DAMAGE.

 ##

 =pod

 =head1 NAME

 B<openpkg lsync> - Access Layer Synchronization Tool

 =head1 SYNOPSIS

 B<openpkg lsync>

 [B<--version>|B<-v>]

 [B<--help>|B<-h>]

 [B<--init>|B<-i>]

 [B<--nop>|B<-n>]

 [B<--quiet>|B<-q>]

 [B<--trace>|B<-t>]

 [B<--local>|B<-l>]

 [B<--uninstall>|B<-u>]

 [B<--root=>I<root>]

 [B<--pkgdir=>I<pkgdir>]

 [B<--subdirs=>I<subdir>[,I<subdir>,...]]

 =head1 DESCRIPTION

 This program activates software packages which were locally

 installed in a sub-directory of a package hierarchy (located under

 I<root>/I<pkgdir>/) by managing symbolic links in an access layer

 (located under I<root>/) corresponding to package installation

 files (found in I<root>/I<pkgdir>/pkgname/subdir/) which need to be

 collected in global directories (located under I<root>/subdir/).

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

 The

 actual creation of symbolic links is as following ("foo" indicating an

 arbitrary file; "bar" indicating an arbitrary package name):

 =over 4

 =item I<root>B</bin/>foo -> B<../>I<pkgdir>B</>barB</bin/>foo

 This activates the user executeable

 I<root>B</>I<pkgdir>B</>barB</bin>/foo as I<root>B</bin/>foo. It can

 be found by the shell by placing I<root>B</bin> into the environment

 variable C<PATH> (B<PATH="..:>I<root>B</bin:..">).

 =item I<root>B</sbin/>foo -> B<../>I<pkgdir>B</>barB</sbin/>foo

 This activates the system executeable

 I<root>B</>I<pkgdir>B</>barB</sbin>/foo as I<root>B</sbin/>foo. It can

 be found by the shell by placing I<root>B</sbin> into the environment

 variable C<PATH> (B<PATH="..:>I<root>B</sbin:..">).

 =item I<root>B</man/man>I<N>B</>foo -> B<../>I<pkgdir>B</>barB</man/man>I<N>B</>foo

 This activates the Unix manual page

 I<root>B</>I<pkgdir>B</>barB</man/man>I<N>B</>foo as

 I<root>B</man/man>I<N>B</>foo. It can be found by the man(1) tool

 by placing I<root>B</man> into the environment variable C<MANPATH>

 (B<MANPATH="..:>I<root>B</man:..">). Keep in mind that B<openpkg lsync>

 activates any files found in the B<man/manI<N>> sub-directory of the

 package, but the man(1) tool usually requires the filename scheme

 fooB<.>I<N> before it can find the file.

 =item I<root>B</info/>foo -> B<../>I<pkgdir>B</>barB</info/>foo

 This activates the GNU info page I<root>B</>I<pkgdir>B</>barB</info/>foo

 as I<root>B</info/>foo. It can be found by the info(1) and pinfo(1)

 tools by placing I<root>B</info> into the environment variable

 C<INFOPATH> (B<INFOPATH="..:>I<root>B</info:..">). Keep in mind that

 B<openpkg lsync> activates any files found in the B<info/> sub-directory of the

 package, but the info(1) and pinfo(1) tools usually require the filename

 scheme fooB<.info> before it can find the file.

 =item I<root>B</include/>foo -> B<../>I<pkgdir>B</>barB</include/>foo

 This activates the C header I<root>B</>I<pkgdir>B</>barB</include>/foo

 as I<root>B</include/>foo. It can be found by the C/C++ compilers

 by adding I<root>B</include> to their include search path (B<cc ..

 -I>I<root>B</include> B<...>). Keep in mind that B<openpkg lsync> activates any

 files found in the B<include/> sub-directory of the package, but the

 C/C++ compiler usually by convention use the filename scheme fooB<.h>.

 =item I<root>B</lib/>foo -> B<../>I<pkgdir>B</>barB</lib/>foo

 This activates the C library I<root>B</>I<pkgdir>B</>barB</lib>/foo

 as I<root>B</lib/>foo. It can be found by the C/C++ compilers (and

 the linker they use) by adding I<root>B</lib> to their library search

 path (B<cc .. -L>I<root>B</lib> B<...>). It can be found by the Unix

 Dynamic Loader by adding I<root>B</lib> to the environment variable

 C<LD_LIBRARY_PATH> (B<LD_LIBRARY_PATH="..:>I<root>B</lib:..">).

 Keep in mind that B<openpkg lsync> activates any files found in the B<lib/>

 sub-directory of the package, but the C/C++ compiler usually require the

 filename scheme B<lib>fooB<.a> and the Unix Dynamic Loader the filename

 scheme B<lib>fooB<.so> before they actually can use the file.

 =back

 It is obvious that more sub-directories in a package installation

 might exist -- for instance B<share/>, B<var/>, B<libexec/>, etc. But

 B<openpkg lsync> 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 B<openpkg lsync> only creates the access layer for files where a common area

 is required for (easy) use.

 =head1 SPECIAL FEATURES

 There are two special features supported by B<openpkg lsync>:

 =over 4

 =item B<Run-Command Files>

 B<openpkg lsync> on startup implicitly reads command line options from

 C<.lsyncrc> 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.

 =item B<Multiple Package Versions>

 B<openpkg lsync> skips all directories under I<root>/I<pkgdir>/ which contain

 the pattern "-[0-9]" in their directory name. On the other hand,

 B<openpkg lsync> follows also symbolic links under I<root>/I<pkgdir>/.

 This can be used for installing multiple versions of a package and

 switching between them. For instance, if version 1.0 of package

 "foo" is installed into directory I<root>/I<pkgdir>/foo-1.0,

 version 1.1 into I<root>/I<pkgdir>/foo-1.1 and version 1.2 into

 I<root>/I<pkgdir>/foo-1.2, B<openpkg lsync> does skip all three. To enable

 version 1.1 one just creates a symbolic link I<root>/I<pkgdir>/foo

 pointing to foo-1.1. Then B<openpkg lsync> picks up the files in

 I<root>/I<pkgdir>/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.

 =item B<Temporarily Deactivated Package>

 One can deactivate a package "foo" by going to I<root>/I<pkgdir>/foo/

 and running "openpkg lsync --local --uninstall", of course. Alternatively

 one can set the sticky bit on the directory I<root>/I<pkgdir>/foo.

 Then B<openpkg lsync> also skips the package. Alternatively, assume

 package "foo" as a whole should not be deactivated, but its

 I<root>/I<pkgdir>/foo/lib directory (usually because this directory

 unfortunately contains non-library files), one just sets the sticky bit

 on I<root>/I<pkgdir>/foo/lib.

 =back

 =head1 OPTIONS

 =over 4

 =item B<--version>, B<-v>

 Display program version information only.

 =item B<--help>, B<-h>

 Display program usage information only.

 =item B<--init>, B<-i>

 Create an initial access layer hierarchy under I<root>.

 =item B<--nop>, B<-n>

 No Operation -- causes B<openpkg lsync> to not perform any filesystem

 operations. In conjunction with B<--trace> you can at least see what

 would be executed.

 =item B<--quiet>, B<-q>

 Forces B<openpkg lsync> to perform the operations quietly, i.e., without any

 verbose messages.

 =item B<--trace>, B<-t>

 Forces B<openpkg lsync> to show what filesystem operations are performed.

 =item B<--local>, B<-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 I<root>/I<pkgdir>/. For instance, when you are staying in

 I<root>/I<pkgdir>/bar or I<root>/I<pkgdir>/bar/bin and use B<--local>,

 all operations are restricted to the package "bar".

 =item B<--uninstall>, B<-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

 B<--local> in order to uninstall a particular package without having to

 remove its files.

 =item B<--root=>I<root>

 Sets the root directory where the access layer and package subdirectory

 is located. The default can be determined by running C<openpkg lsync --help>

 (see section "Current configuration").

 =item B<--pkgdir=>I<pkgdir>

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

 located. The default can be determined by running C<openpkg lsync --help> (see

 section "Current configuration").

 =item B<--subdirs=>I<subdirs>[,I<subdir>,...]

 Sets one or more sub-directories of the access layer on which B<openpkg lsync>

 should act. The default can be determined by running C<openpkg lsync --help>

 (see section "Current configuration").

 =back

 =head1 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).

 =head1 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 B<GenOPT>, 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 C</opt>. B<GenOPT> 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.

 For Cable & Wireless, Munich, the old B<GenOPT> principle was again

 needed to manage the C</cw/local> area on their servers. For this in

 November 2000 the functionality of B<GenOPT> was revised, heavily

 stripped down and finally implemented from scratch. The result is the

 current B<openpkg lsync>.

 =head1 AUTHOR

  Ralf S. Engelschall

  rse@engelschall.com

  www.engelschall.com

 =cut