LSYNC(1)

NAME
lsync - Access Layer Synchronization Tool

SYNOPSIS
lsync [--version|-v] [--help|-h] [--init|-i] [--nop|-n] [--quiet|-q] [--trace|-t] [--local|-l] [--uninstall|-u] [--root=root] [--pkgdir=pkgdir] [--subdirs=subdir[,subdir,...]]

DESCRIPTION
This program activates software packages which were locally installed in a sub-directory of a package hierarchy (located under root/pkgdir/) by managing symbolic links in an access layer (located under root/) corresponding to package installation files (found in root/pkgdir/pkgname/subdir/) which need to be collected in global directories (located under 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):

root/bin/foo -> ../pkgdir/bar/bin/foo
    This activates the user executeable root/pkgdir/bar/bin/foo as root/bin/foo. It can be found by the shell by placing root/bin into the environment variable PATH (PATH="..:root/bin:..").

root/sbin/foo -> ../pkgdir/bar/sbin/foo
    This activates the system executeable root/pkgdir/bar/sbin/foo as root/sbin/foo. It can be found by the shell by placing root/sbin into the environment variable PATH (PATH="..:root/sbin:..").

root/man/manN/foo -> ../pkgdir/bar/man/manN/foo
    This activates the Unix manual page root/pkgdir/bar/man/manN/foo as root/man/manN/foo. It can be found by the man(1) tool by placing root/man into the environment variable MANPATH (MANPATH="..:root/man:.."). Keep in mind that lsync(1) activates any files found in the man/manN sub-directory of the package, but the man(1) tool usually requires the filename scheme foo.N before it can find the file.

root/info/foo -> ../pkgdir/bar/info/foo
    This activates the GNU info page root/pkgdir/bar/info/foo as root/info/foo. It can be found by the info(1) and pinfo(1) tools by placing root/info into the environment variable INFOPATH (INFOPATH="..:root/info:.."). Keep in mind that lsync(1) activates any files found in the info/ sub-directory of the package, but the info(1) and pinfo(1) tools usually require the filename scheme foo.info before it can find the file.

root/include/foo -> ../pkgdir/bar/include/foo
    This activates the C header root/pkgdir/bar/include/foo as root/include/foo. It can be found by the C/C++ compilers by adding root/include to their include search path (cc .. -Iroot/include ...). Keep in mind that lsync(1) activates any files found in the include/ sub-directory of the package, but the C/C++ compiler usually by convention use the filename scheme foo.h.

root/lib/foo -> ../pkgdir/bar/lib/foo
    This activates the C library root/pkgdir/bar/lib/foo as root/lib/foo. It can be found by the C/C++ compilers (and the linker they use) by adding root/lib to their library search path (cc .. -Lroot/lib ...). It can be found by the Unix Dynamic Loader by adding root/lib to the environment variable LD_LIBRARY_PATH (LD_LIBRARY_PATH="..:root/lib:.."). Keep in mind that lsync(1) activates any files found in the lib/ sub-directory of the package, but the C/C++ compiler usually require the filename scheme libfoo.a and the Unix Dynamic Loader the filename scheme libfoo.so before they actually can use the file.

It is obvious that more sub-directories in a package installation might exist -- for instance share/, var/, libexec/, etc. But lsync(1) 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 lsync(1) only creates the access layer for files where a common area is required for (easy) use.

SPECIAL FEATURES
There are two special features supported by lsync(1):

Run-Command Files
    lsync(1) on startup implicitly reads command line options from .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.

Multiple Package Versions
    lsync(1) skips all directories under root/pkgdir/ which contain the pattern "-[0-9]" in their directory name. On the other hand, lsync(1) follows also symbolic links under root/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 root/pkgdir/foo-1.0, version 1.1 into root/pkgdir/foo-1.1 and version 1.2 into root/pkgdir/foo-1.2, lsync(1) does skip all three. To enable version 1.1 one just creates a symbolic link root/pkgdir/foo pointing to foo-1.1. Then lsync(1) picks up the files in root/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.

Temporarily Deactivated Package
    One can deactivate a package "foo" by going to root/pkgdir/foo/ and running "lsync --local --uninstall", of course. Alternatively one can set the sticky bit on the directory root/pkgdir/foo. Then lsync(1) also skips the package. Alternatively, assume package "foo" as a whole should not be deactivated, but its root/pkgdir/foo/lib directory (usually because this directory unfortunately contains non-library files), one just sets the sticky bit on root/pkgdir/foo/lib.

OPTIONS

--version, -v
    Display program version information only.

--help, -h
    Display program usage information only.

--init, -i
    Create an initial access layer hierarchy under root.

--nop, -n
    No Operation -- causes lsync(1) to not perform any filesystem operations. In conjunction with --trace you can at least see what would be executed.

--quiet, -q
    Forces lsync(1) to perform the operations quietly, i.e., without any verbose messages.

--trace, -t
    Forces lsync(1) to show what filesystem operations are performed.

--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 root/pkgdir/. For instance, when you are staying in root/pkgdir/bar or root/pkgdir/bar/bin and use --local, all operations are restricted to the package "bar".

--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 --local in order to uninstall a particular package without having to remove its files.

--root=root
    Sets the root directory where the access layer and package subdirectory is located. The default can be determined by running lsync --help (see section "Current configuration").

--pkgdir=pkgdir
    Sets the sub-directory under the root directory where packages are located. The default can be determined by running lsync --help (see section "Current configuration").

--subdirs=subdirs[,subdir,...]
    Sets one or more sub-directories of the access layer on which lsync(1) should act. The default can be determined by running lsync --help (see section "Current configuration").

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

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 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 /opt. 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 Deutschland GmbH, Munich, the old GenOPT principle was again needed to manage the /cw/local area on their servers. For this in November 2000 the functionality of GenOPT was revised, heavily stripped down and finally implemented from scratch. The result is the current LSync.

AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com