1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/lsync.pod Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,274 @@
1.4 +##
1.5 +## lsync.pod -- Access Layer Synchronization Tool (Manual Page)
1.6 +## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
1.7 +## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
1.8 +##
1.9 +## Permission to use, copy, modify, and distribute this software for
1.10 +## any purpose with or without fee is hereby granted, provided that
1.11 +## the above copyright notice and this permission notice appear in all
1.12 +## copies.
1.13 +##
1.14 +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1.15 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.16 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.17 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.18 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.19 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.20 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.21 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.22 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.23 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.24 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.25 +## SUCH DAMAGE.
1.26 +##
1.27 +
1.28 +=pod
1.29 +
1.30 +=head1 NAME
1.31 +
1.32 +B<openpkg lsync> - Access Layer Synchronization Tool
1.33 +
1.34 +=head1 SYNOPSIS
1.35 +
1.36 +B<openpkg lsync>
1.37 +[B<--version>|B<-v>]
1.38 +[B<--help>|B<-h>]
1.39 +[B<--init>|B<-i>]
1.40 +[B<--nop>|B<-n>]
1.41 +[B<--quiet>|B<-q>]
1.42 +[B<--trace>|B<-t>]
1.43 +[B<--local>|B<-l>]
1.44 +[B<--uninstall>|B<-u>]
1.45 +[B<--root=>I<root>]
1.46 +[B<--pkgdir=>I<pkgdir>]
1.47 +[B<--subdirs=>I<subdir>[,I<subdir>,...]]
1.48 +
1.49 +=head1 DESCRIPTION
1.50 +
1.51 +This program activates software packages which were locally
1.52 +installed in a sub-directory of a package hierarchy (located under
1.53 +I<root>/I<pkgdir>/) by managing symbolic links in an access layer
1.54 +(located under I<root>/) corresponding to package installation
1.55 +files (found in I<root>/I<pkgdir>/pkgname/subdir/) which need to be
1.56 +collected in global directories (located under I<root>/subdir/).
1.57 +
1.58 +The purpose of this is that individual packages can be installed and
1.59 +deinstalled seperately without interfering with other packages while
1.60 +all packages as a whole still can be treated like a single package
1.61 +(installed into the access layer).
1.62 +
1.63 +The
1.64 +actual creation of symbolic links is as following ("foo" indicating an
1.65 +arbitrary file; "bar" indicating an arbitrary package name):
1.66 +
1.67 +=over 4
1.68 +
1.69 +=item I<root>B</bin/>foo -> B<../>I<pkgdir>B</>barB</bin/>foo
1.70 +
1.71 +This activates the user executeable
1.72 +I<root>B</>I<pkgdir>B</>barB</bin>/foo as I<root>B</bin/>foo. It can
1.73 +be found by the shell by placing I<root>B</bin> into the environment
1.74 +variable C<PATH> (B<PATH="..:>I<root>B</bin:..">).
1.75 +
1.76 +=item I<root>B</sbin/>foo -> B<../>I<pkgdir>B</>barB</sbin/>foo
1.77 +
1.78 +This activates the system executeable
1.79 +I<root>B</>I<pkgdir>B</>barB</sbin>/foo as I<root>B</sbin/>foo. It can
1.80 +be found by the shell by placing I<root>B</sbin> into the environment
1.81 +variable C<PATH> (B<PATH="..:>I<root>B</sbin:..">).
1.82 +
1.83 +=item I<root>B</man/man>I<N>B</>foo -> B<../>I<pkgdir>B</>barB</man/man>I<N>B</>foo
1.84 +
1.85 +This activates the Unix manual page
1.86 +I<root>B</>I<pkgdir>B</>barB</man/man>I<N>B</>foo as
1.87 +I<root>B</man/man>I<N>B</>foo. It can be found by the man(1) tool
1.88 +by placing I<root>B</man> into the environment variable C<MANPATH>
1.89 +(B<MANPATH="..:>I<root>B</man:..">). Keep in mind that B<openpkg lsync>
1.90 +activates any files found in the B<man/manI<N>> sub-directory of the
1.91 +package, but the man(1) tool usually requires the filename scheme
1.92 +fooB<.>I<N> before it can find the file.
1.93 +
1.94 +=item I<root>B</info/>foo -> B<../>I<pkgdir>B</>barB</info/>foo
1.95 +
1.96 +This activates the GNU info page I<root>B</>I<pkgdir>B</>barB</info/>foo
1.97 +as I<root>B</info/>foo. It can be found by the info(1) and pinfo(1)
1.98 +tools by placing I<root>B</info> into the environment variable
1.99 +C<INFOPATH> (B<INFOPATH="..:>I<root>B</info:..">). Keep in mind that
1.100 +B<openpkg lsync> activates any files found in the B<info/> sub-directory of the
1.101 +package, but the info(1) and pinfo(1) tools usually require the filename
1.102 +scheme fooB<.info> before it can find the file.
1.103 +
1.104 +=item I<root>B</include/>foo -> B<../>I<pkgdir>B</>barB</include/>foo
1.105 +
1.106 +This activates the C header I<root>B</>I<pkgdir>B</>barB</include>/foo
1.107 +as I<root>B</include/>foo. It can be found by the C/C++ compilers
1.108 +by adding I<root>B</include> to their include search path (B<cc ..
1.109 +-I>I<root>B</include> B<...>). Keep in mind that B<openpkg lsync> activates any
1.110 +files found in the B<include/> sub-directory of the package, but the
1.111 +C/C++ compiler usually by convention use the filename scheme fooB<.h>.
1.112 +
1.113 +=item I<root>B</lib/>foo -> B<../>I<pkgdir>B</>barB</lib/>foo
1.114 +
1.115 +This activates the C library I<root>B</>I<pkgdir>B</>barB</lib>/foo
1.116 +as I<root>B</lib/>foo. It can be found by the C/C++ compilers (and
1.117 +the linker they use) by adding I<root>B</lib> to their library search
1.118 +path (B<cc .. -L>I<root>B</lib> B<...>). It can be found by the Unix
1.119 +Dynamic Loader by adding I<root>B</lib> to the environment variable
1.120 +C<LD_LIBRARY_PATH> (B<LD_LIBRARY_PATH="..:>I<root>B</lib:..">).
1.121 +Keep in mind that B<openpkg lsync> activates any files found in the B<lib/>
1.122 +sub-directory of the package, but the C/C++ compiler usually require the
1.123 +filename scheme B<lib>fooB<.a> and the Unix Dynamic Loader the filename
1.124 +scheme B<lib>fooB<.so> before they actually can use the file.
1.125 +
1.126 +=back
1.127 +
1.128 +It is obvious that more sub-directories in a package installation
1.129 +might exist -- for instance B<share/>, B<var/>, B<libexec/>, etc. But
1.130 +B<openpkg lsync> intentionally does not link files in those directories into
1.131 +corresponding directories of the access layer, because those files do
1.132 +not require that they are located in a global area in order to be used.
1.133 +So B<openpkg lsync> only creates the access layer for files where a common area
1.134 +is required for (easy) use.
1.135 +
1.136 +=head1 SPECIAL FEATURES
1.137 +
1.138 +There are two special features supported by B<openpkg lsync>:
1.139 +
1.140 +=over 4
1.141 +
1.142 +=item B<Run-Command Files>
1.143 +
1.144 +B<openpkg lsync> on startup implicitly reads command line options from
1.145 +C<.lsyncrc> files. They are searched in all parent directories and in
1.146 +the callers home directory. Their contents is prepended to the list of
1.147 +given command line options.
1.148 +
1.149 +=item B<Multiple Package Versions>
1.150 +
1.151 +B<openpkg lsync> skips all directories under I<root>/I<pkgdir>/ which contain
1.152 +the pattern "-[0-9]" in their directory name. On the other hand,
1.153 +B<openpkg lsync> follows also symbolic links under I<root>/I<pkgdir>/.
1.154 +This can be used for installing multiple versions of a package and
1.155 +switching between them. For instance, if version 1.0 of package
1.156 +"foo" is installed into directory I<root>/I<pkgdir>/foo-1.0,
1.157 +version 1.1 into I<root>/I<pkgdir>/foo-1.1 and version 1.2 into
1.158 +I<root>/I<pkgdir>/foo-1.2, B<openpkg lsync> does skip all three. To enable
1.159 +version 1.1 one just creates a symbolic link I<root>/I<pkgdir>/foo
1.160 +pointing to foo-1.1. Then B<openpkg lsync> picks up the files in
1.161 +I<root>/I<pkgdir>/foo-1.1. If you want to temporarily upgrade to
1.162 +foo-1.2, all you have to do is to change the symlink pointing from
1.163 +foo-1.1 to foo-1.2.
1.164 +
1.165 +=item B<Temporarily Deactivated Package>
1.166 +
1.167 +One can deactivate a package "foo" by going to I<root>/I<pkgdir>/foo/
1.168 +and running "openpkg lsync --local --uninstall", of course. Alternatively
1.169 +one can set the sticky bit on the directory I<root>/I<pkgdir>/foo.
1.170 +Then B<openpkg lsync> also skips the package. Alternatively, assume
1.171 +package "foo" as a whole should not be deactivated, but its
1.172 +I<root>/I<pkgdir>/foo/lib directory (usually because this directory
1.173 +unfortunately contains non-library files), one just sets the sticky bit
1.174 +on I<root>/I<pkgdir>/foo/lib.
1.175 +
1.176 +=back
1.177 +
1.178 +=head1 OPTIONS
1.179 +
1.180 +=over 4
1.181 +
1.182 +=item B<--version>, B<-v>
1.183 +
1.184 +Display program version information only.
1.185 +
1.186 +=item B<--help>, B<-h>
1.187 +
1.188 +Display program usage information only.
1.189 +
1.190 +=item B<--init>, B<-i>
1.191 +
1.192 +Create an initial access layer hierarchy under I<root>.
1.193 +
1.194 +=item B<--nop>, B<-n>
1.195 +
1.196 +No Operation -- causes B<openpkg lsync> to not perform any filesystem
1.197 +operations. In conjunction with B<--trace> you can at least see what
1.198 +would be executed.
1.199 +
1.200 +=item B<--quiet>, B<-q>
1.201 +
1.202 +Forces B<openpkg lsync> to perform the operations quietly, i.e., without any
1.203 +verbose messages.
1.204 +
1.205 +=item B<--trace>, B<-t>
1.206 +
1.207 +Forces B<openpkg lsync> to show what filesystem operations are performed.
1.208 +
1.209 +=item B<--local>, B<-l>
1.210 +
1.211 +This restricts the operations to a local package area. This option can
1.212 +only be used if you are physically staying below a package sub-directory
1.213 +under I<root>/I<pkgdir>/. For instance, when you are staying in
1.214 +I<root>/I<pkgdir>/bar or I<root>/I<pkgdir>/bar/bin and use B<--local>,
1.215 +all operations are restricted to the package "bar".
1.216 +
1.217 +=item B<--uninstall>, B<-u>
1.218 +
1.219 +This performs only package uninstallation operations, i.e., only
1.220 +symbolic links are removed. This can be used to completely empty the
1.221 +access layer. Additionally it is very useful in combination with
1.222 +B<--local> in order to uninstall a particular package without having to
1.223 +remove its files.
1.224 +
1.225 +=item B<--root=>I<root>
1.226 +
1.227 +Sets the root directory where the access layer and package subdirectory
1.228 +is located. The default can be determined by running C<openpkg lsync --help>
1.229 +(see section "Current configuration").
1.230 +
1.231 +=item B<--pkgdir=>I<pkgdir>
1.232 +
1.233 +Sets the sub-directory under the root directory where packages are
1.234 +located. The default can be determined by running C<openpkg lsync --help> (see
1.235 +section "Current configuration").
1.236 +
1.237 +=item B<--subdirs=>I<subdirs>[,I<subdir>,...]
1.238 +
1.239 +Sets one or more sub-directories of the access layer on which B<openpkg lsync>
1.240 +should act. The default can be determined by running C<openpkg lsync --help>
1.241 +(see section "Current configuration").
1.242 +
1.243 +=back
1.244 +
1.245 +=head1 RESULTS
1.246 +
1.247 +This program uses the following return codes on exit: 0 (operation
1.248 +successful), 1 (system error), 2 (command line error) and 3 (other user
1.249 +error).
1.250 +
1.251 +=head1 HISTORY
1.252 +
1.253 +The idea of filesystem access layers consisting of symbolic links
1.254 +pointing to actual package installation areas is a rather old one. It
1.255 +dates back to the early days of Unix and was implemented many times over
1.256 +the last decades. One of many implementation was B<GenOPT>, written by
1.257 +Ralf S. Engelschall for sd&m GmbH & Co KG, Munich in 1992. The name
1.258 +indicates the programs purpose: to generate symbolic links in an access
1.259 +layer which was located under C</opt>. B<GenOPT> was very flexible, but
1.260 +hence also very complex. Because of lack of documentation it was never
1.261 +released and so only used at sd&m and on all machines which were under
1.262 +control of Ralf S. Engelschall.
1.263 +
1.264 +For Cable & Wireless, Munich, the old B<GenOPT> principle was again
1.265 +needed to manage the C</cw/local> area on their servers. For this in
1.266 +November 2000 the functionality of B<GenOPT> was revised, heavily
1.267 +stripped down and finally implemented from scratch. The result is the
1.268 +current B<openpkg lsync>.
1.269 +
1.270 +=head1 AUTHOR
1.271 +
1.272 + Ralf S. Engelschall
1.273 + rse@engelschall.com
1.274 + www.engelschall.com
1.275 +
1.276 +=cut
1.277 +
