michael@13: ##
michael@13: ##  lsync.pod -- Access Layer Synchronization Tool (Manual Page)
michael@13: ##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
michael@13: ##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
michael@13: ##
michael@13: ##  Permission to use, copy, modify, and distribute this software for
michael@13: ##  any purpose with or without fee is hereby granted, provided that
michael@13: ##  the above copyright notice and this permission notice appear in all
michael@13: ##  copies.
michael@13: ##
michael@13: ##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
michael@13: ##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
michael@13: ##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@13: ##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
michael@13: ##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@13: ##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@13: ##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
michael@13: ##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
michael@13: ##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
michael@13: ##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
michael@13: ##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
michael@13: ##  SUCH DAMAGE.
michael@13: ##
michael@13: 
michael@13: =pod
michael@13: 
michael@13: =head1 NAME
michael@13: 
michael@13: B<openpkg lsync> - Access Layer Synchronization Tool
michael@13: 
michael@13: =head1 SYNOPSIS
michael@13: 
michael@13: B<openpkg lsync>
michael@13: [B<--version>|B<-v>]
michael@13: [B<--help>|B<-h>]
michael@13: [B<--init>|B<-i>]
michael@13: [B<--nop>|B<-n>]
michael@13: [B<--quiet>|B<-q>]
michael@13: [B<--trace>|B<-t>]
michael@13: [B<--local>|B<-l>]
michael@13: [B<--uninstall>|B<-u>]
michael@13: [B<--root=>I<root>]
michael@13: [B<--pkgdir=>I<pkgdir>]
michael@13: [B<--subdirs=>I<subdir>[,I<subdir>,...]]
michael@13: 
michael@13: =head1 DESCRIPTION
michael@13: 
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: I<root>/I<pkgdir>/) by managing symbolic links in an access layer
michael@13: (located under I<root>/) corresponding to package installation
michael@13: files (found in I<root>/I<pkgdir>/pkgname/subdir/) which need to be
michael@13: collected in global directories (located under I<root>/subdir/).
michael@13: 
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: 
michael@13: The
michael@13: actual creation of symbolic links is as following ("foo" indicating an
michael@13: arbitrary file; "bar" indicating an arbitrary package name):
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item I<root>B</bin/>foo -> B<../>I<pkgdir>B</>barB</bin/>foo
michael@13: 
michael@13: This activates the user executeable
michael@13: I<root>B</>I<pkgdir>B</>barB</bin>/foo as I<root>B</bin/>foo. It can
michael@13: be found by the shell by placing I<root>B</bin> into the environment
michael@13: variable C<PATH> (B<PATH="..:>I<root>B</bin:..">).
michael@13: 
michael@13: =item I<root>B</sbin/>foo -> B<../>I<pkgdir>B</>barB</sbin/>foo
michael@13: 
michael@13: This activates the system executeable
michael@13: I<root>B</>I<pkgdir>B</>barB</sbin>/foo as I<root>B</sbin/>foo. It can
michael@13: be found by the shell by placing I<root>B</sbin> into the environment
michael@13: variable C<PATH> (B<PATH="..:>I<root>B</sbin:..">).
michael@13: 
michael@13: =item I<root>B</man/man>I<N>B</>foo -> B<../>I<pkgdir>B</>barB</man/man>I<N>B</>foo
michael@13: 
michael@13: This activates the Unix manual page
michael@13: I<root>B</>I<pkgdir>B</>barB</man/man>I<N>B</>foo as
michael@13: I<root>B</man/man>I<N>B</>foo. It can be found by the man(1) tool
michael@13: by placing I<root>B</man> into the environment variable C<MANPATH>
michael@13: (B<MANPATH="..:>I<root>B</man:..">). Keep in mind that B<openpkg lsync>
michael@13: activates any files found in the B<man/manI<N>> sub-directory of the
michael@13: package, but the man(1) tool usually requires the filename scheme
michael@13: fooB<.>I<N> before it can find the file.
michael@13: 
michael@13: =item I<root>B</info/>foo -> B<../>I<pkgdir>B</>barB</info/>foo
michael@13: 
michael@13: This activates the GNU info page I<root>B</>I<pkgdir>B</>barB</info/>foo
michael@13: as I<root>B</info/>foo. It can be found by the info(1) and pinfo(1)
michael@13: tools by placing I<root>B</info> into the environment variable
michael@13: C<INFOPATH> (B<INFOPATH="..:>I<root>B</info:..">). Keep in mind that
michael@13: B<openpkg lsync> activates any files found in the B<info/> sub-directory of the
michael@13: package, but the info(1) and pinfo(1) tools usually require the filename
michael@13: scheme fooB<.info> before it can find the file.
michael@13: 
michael@13: =item I<root>B</include/>foo -> B<../>I<pkgdir>B</>barB</include/>foo
michael@13: 
michael@13: This activates the C header I<root>B</>I<pkgdir>B</>barB</include>/foo
michael@13: as I<root>B</include/>foo. It can be found by the C/C++ compilers
michael@13: by adding I<root>B</include> to their include search path (B<cc ..
michael@13: -I>I<root>B</include> B<...>). Keep in mind that B<openpkg lsync> activates any
michael@13: files found in the B<include/> sub-directory of the package, but the
michael@13: C/C++ compiler usually by convention use the filename scheme fooB<.h>.
michael@13: 
michael@13: =item I<root>B</lib/>foo -> B<../>I<pkgdir>B</>barB</lib/>foo
michael@13: 
michael@13: This activates the C library I<root>B</>I<pkgdir>B</>barB</lib>/foo
michael@13: as I<root>B</lib/>foo. It can be found by the C/C++ compilers (and
michael@13: the linker they use) by adding I<root>B</lib> to their library search
michael@13: path (B<cc .. -L>I<root>B</lib> B<...>). It can be found by the Unix
michael@13: Dynamic Loader by adding I<root>B</lib> to the environment variable
michael@13: C<LD_LIBRARY_PATH> (B<LD_LIBRARY_PATH="..:>I<root>B</lib:..">).
michael@13: Keep in mind that B<openpkg lsync> activates any files found in the B<lib/>
michael@13: sub-directory of the package, but the C/C++ compiler usually require the
michael@13: filename scheme B<lib>fooB<.a> and the Unix Dynamic Loader the filename
michael@13: scheme B<lib>fooB<.so> before they actually can use the file.
michael@13: 
michael@13: =back
michael@13: 
michael@13: It is obvious that more sub-directories in a package installation
michael@13: might exist -- for instance B<share/>, B<var/>, B<libexec/>, etc. But
michael@13: B<openpkg lsync> 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 B<openpkg lsync> only creates the access layer for files where a common area
michael@13: is required for (easy) use.
michael@13: 
michael@13: =head1 SPECIAL FEATURES
michael@13: 
michael@13: There are two special features supported by B<openpkg lsync>:
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item B<Run-Command Files>
michael@13: 
michael@13: B<openpkg lsync> on startup implicitly reads command line options from
michael@13: C<.lsyncrc> 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: 
michael@13: =item B<Multiple Package Versions>
michael@13: 
michael@13: B<openpkg lsync> skips all directories under I<root>/I<pkgdir>/ which contain
michael@13: the pattern "-[0-9]" in their directory name. On the other hand,
michael@13: B<openpkg lsync> follows also symbolic links under I<root>/I<pkgdir>/.
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: "foo" is installed into directory I<root>/I<pkgdir>/foo-1.0,
michael@13: version 1.1 into I<root>/I<pkgdir>/foo-1.1 and version 1.2 into
michael@13: I<root>/I<pkgdir>/foo-1.2, B<openpkg lsync> does skip all three. To enable
michael@13: version 1.1 one just creates a symbolic link I<root>/I<pkgdir>/foo
michael@13: pointing to foo-1.1. Then B<openpkg lsync> picks up the files in
michael@13: I<root>/I<pkgdir>/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: 
michael@13: =item B<Temporarily Deactivated Package>
michael@13: 
michael@13: One can deactivate a package "foo" by going to I<root>/I<pkgdir>/foo/
michael@13: and running "openpkg lsync --local --uninstall", of course. Alternatively
michael@13: one can set the sticky bit on the directory I<root>/I<pkgdir>/foo.
michael@13: Then B<openpkg lsync> also skips the package. Alternatively, assume
michael@13: package "foo" as a whole should not be deactivated, but its
michael@13: I<root>/I<pkgdir>/foo/lib directory (usually because this directory
michael@13: unfortunately contains non-library files), one just sets the sticky bit
michael@13: on I<root>/I<pkgdir>/foo/lib.
michael@13: 
michael@13: =back
michael@13: 
michael@13: =head1 OPTIONS
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item B<--version>, B<-v>
michael@13: 
michael@13: Display program version information only.
michael@13: 
michael@13: =item B<--help>, B<-h>
michael@13: 
michael@13: Display program usage information only.
michael@13: 
michael@13: =item B<--init>, B<-i>
michael@13: 
michael@13: Create an initial access layer hierarchy under I<root>.
michael@13: 
michael@13: =item B<--nop>, B<-n>
michael@13: 
michael@13: No Operation -- causes B<openpkg lsync> to not perform any filesystem
michael@13: operations. In conjunction with B<--trace> you can at least see what
michael@13: would be executed.
michael@13: 
michael@13: =item B<--quiet>, B<-q>
michael@13: 
michael@13: Forces B<openpkg lsync> to perform the operations quietly, i.e., without any
michael@13: verbose messages.
michael@13: 
michael@13: =item B<--trace>, B<-t>
michael@13: 
michael@13: Forces B<openpkg lsync> to show what filesystem operations are performed.
michael@13: 
michael@13: =item B<--local>, B<-l>
michael@13: 
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 I<root>/I<pkgdir>/. For instance, when you are staying in
michael@13: I<root>/I<pkgdir>/bar or I<root>/I<pkgdir>/bar/bin and use B<--local>,
michael@13: all operations are restricted to the package "bar".
michael@13: 
michael@13: =item B<--uninstall>, B<-u>
michael@13: 
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: B<--local> in order to uninstall a particular package without having to
michael@13: remove its files.
michael@13: 
michael@13: =item B<--root=>I<root>
michael@13: 
michael@13: Sets the root directory where the access layer and package subdirectory
michael@13: is located. The default can be determined by running C<openpkg lsync --help>
michael@13: (see section "Current configuration").
michael@13: 
michael@13: =item B<--pkgdir=>I<pkgdir>
michael@13: 
michael@13: Sets the sub-directory under the root directory where packages are
michael@13: located. The default can be determined by running C<openpkg lsync --help> (see
michael@13: section "Current configuration").
michael@13: 
michael@13: =item B<--subdirs=>I<subdirs>[,I<subdir>,...]
michael@13: 
michael@13: Sets one or more sub-directories of the access layer on which B<openpkg lsync>
michael@13: should act. The default can be determined by running C<openpkg lsync --help>
michael@13: (see section "Current configuration").
michael@13: 
michael@13: =back
michael@13: 
michael@13: =head1 RESULTS
michael@13: 
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: 
michael@13: =head1 HISTORY
michael@13: 
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 B<GenOPT>, written by
michael@13: Ralf S. Engelschall for sd&m GmbH & Co KG, 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 C</opt>. B<GenOPT> 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: 
michael@13: For Cable & Wireless, Munich, the old B<GenOPT> principle was again
michael@13: needed to manage the C</cw/local> area on their servers. For this in
michael@13: November 2000 the functionality of B<GenOPT> was revised, heavily
michael@13: stripped down and finally implemented from scratch. The result is the
michael@13: current B<openpkg lsync>.
michael@13: 
michael@13: =head1 AUTHOR
michael@13: 
michael@13:  Ralf S. Engelschall
michael@13:  rse@engelschall.com
michael@13:  www.engelschall.com
michael@13: 
michael@13: =cut
michael@13: