comparison: openpkg/lsync.pod
openpkg/lsync.pod
- changeset 100
- 67744e0f53cc
- child 428
- f880f219c566
equal
deleted
inserted
replaced
| -1:000000000000 | 0:7c420f3c5af7 |
|---|---|
| 1 ## | |
| 2 ## lsync.pod -- Access Layer Synchronization Tool (Manual Page) | |
| 3 ## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/> | |
| 4 ## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/> | |
| 5 ## | |
| 6 ## Permission to use, copy, modify, and distribute this software for | |
| 7 ## any purpose with or without fee is hereby granted, provided that | |
| 8 ## the above copyright notice and this permission notice appear in all | |
| 9 ## copies. | |
| 10 ## | |
| 11 ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED | |
| 12 ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| 13 ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |
| 14 ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR | |
| 15 ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| 16 ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
| 17 ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF | |
| 18 ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
| 19 ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
| 20 ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
| 21 ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
| 22 ## SUCH DAMAGE. | |
| 23 ## | |
| 24 | |
| 25 =pod | |
| 26 | |
| 27 =head1 NAME | |
| 28 | |
| 29 B<openpkg lsync> - Access Layer Synchronization Tool | |
| 30 | |
| 31 =head1 SYNOPSIS | |
| 32 | |
| 33 B<openpkg lsync> | |
| 34 [B<--version>|B<-v>] | |
| 35 [B<--help>|B<-h>] | |
| 36 [B<--init>|B<-i>] | |
| 37 [B<--nop>|B<-n>] | |
| 38 [B<--quiet>|B<-q>] | |
| 39 [B<--trace>|B<-t>] | |
| 40 [B<--local>|B<-l>] | |
| 41 [B<--uninstall>|B<-u>] | |
| 42 [B<--root=>I<root>] | |
| 43 [B<--pkgdir=>I<pkgdir>] | |
| 44 [B<--subdirs=>I<subdir>[,I<subdir>,...]] | |
| 45 | |
| 46 =head1 DESCRIPTION | |
| 47 | |
| 48 This program activates software packages which were locally | |
| 49 installed in a sub-directory of a package hierarchy (located under | |
| 50 I<root>/I<pkgdir>/) by managing symbolic links in an access layer | |
| 51 (located under I<root>/) corresponding to package installation | |
| 52 files (found in I<root>/I<pkgdir>/pkgname/subdir/) which need to be | |
| 53 collected in global directories (located under I<root>/subdir/). | |
| 54 | |
| 55 The purpose of this is that individual packages can be installed and | |
| 56 deinstalled seperately without interfering with other packages while | |
| 57 all packages as a whole still can be treated like a single package | |
| 58 (installed into the access layer). | |
| 59 | |
| 60 The | |
| 61 actual creation of symbolic links is as following ("foo" indicating an | |
| 62 arbitrary file; "bar" indicating an arbitrary package name): | |
| 63 | |
| 64 =over 4 | |
| 65 | |
| 66 =item I<root>B</bin/>foo -> B<../>I<pkgdir>B</>barB</bin/>foo | |
| 67 | |
| 68 This activates the user executeable | |
| 69 I<root>B</>I<pkgdir>B</>barB</bin>/foo as I<root>B</bin/>foo. It can | |
| 70 be found by the shell by placing I<root>B</bin> into the environment | |
| 71 variable C<PATH> (B<PATH="..:>I<root>B</bin:..">). | |
| 72 | |
| 73 =item I<root>B</sbin/>foo -> B<../>I<pkgdir>B</>barB</sbin/>foo | |
| 74 | |
| 75 This activates the system executeable | |
| 76 I<root>B</>I<pkgdir>B</>barB</sbin>/foo as I<root>B</sbin/>foo. It can | |
| 77 be found by the shell by placing I<root>B</sbin> into the environment | |
| 78 variable C<PATH> (B<PATH="..:>I<root>B</sbin:..">). | |
| 79 | |
| 80 =item I<root>B</man/man>I<N>B</>foo -> B<../>I<pkgdir>B</>barB</man/man>I<N>B</>foo | |
| 81 | |
| 82 This activates the Unix manual page | |
| 83 I<root>B</>I<pkgdir>B</>barB</man/man>I<N>B</>foo as | |
| 84 I<root>B</man/man>I<N>B</>foo. It can be found by the man(1) tool | |
| 85 by placing I<root>B</man> into the environment variable C<MANPATH> | |
| 86 (B<MANPATH="..:>I<root>B</man:..">). Keep in mind that B<openpkg lsync> | |
| 87 activates any files found in the B<man/manI<N>> sub-directory of the | |
| 88 package, but the man(1) tool usually requires the filename scheme | |
| 89 fooB<.>I<N> before it can find the file. | |
| 90 | |
| 91 =item I<root>B</info/>foo -> B<../>I<pkgdir>B</>barB</info/>foo | |
| 92 | |
| 93 This activates the GNU info page I<root>B</>I<pkgdir>B</>barB</info/>foo | |
| 94 as I<root>B</info/>foo. It can be found by the info(1) and pinfo(1) | |
| 95 tools by placing I<root>B</info> into the environment variable | |
| 96 C<INFOPATH> (B<INFOPATH="..:>I<root>B</info:..">). Keep in mind that | |
| 97 B<openpkg lsync> activates any files found in the B<info/> sub-directory of the | |
| 98 package, but the info(1) and pinfo(1) tools usually require the filename | |
| 99 scheme fooB<.info> before it can find the file. | |
| 100 | |
| 101 =item I<root>B</include/>foo -> B<../>I<pkgdir>B</>barB</include/>foo | |
| 102 | |
| 103 This activates the C header I<root>B</>I<pkgdir>B</>barB</include>/foo | |
| 104 as I<root>B</include/>foo. It can be found by the C/C++ compilers | |
| 105 by adding I<root>B</include> to their include search path (B<cc .. | |
| 106 -I>I<root>B</include> B<...>). Keep in mind that B<openpkg lsync> activates any | |
| 107 files found in the B<include/> sub-directory of the package, but the | |
| 108 C/C++ compiler usually by convention use the filename scheme fooB<.h>. | |
| 109 | |
| 110 =item I<root>B</lib/>foo -> B<../>I<pkgdir>B</>barB</lib/>foo | |
| 111 | |
| 112 This activates the C library I<root>B</>I<pkgdir>B</>barB</lib>/foo | |
| 113 as I<root>B</lib/>foo. It can be found by the C/C++ compilers (and | |
| 114 the linker they use) by adding I<root>B</lib> to their library search | |
| 115 path (B<cc .. -L>I<root>B</lib> B<...>). It can be found by the Unix | |
| 116 Dynamic Loader by adding I<root>B</lib> to the environment variable | |
| 117 C<LD_LIBRARY_PATH> (B<LD_LIBRARY_PATH="..:>I<root>B</lib:..">). | |
| 118 Keep in mind that B<openpkg lsync> activates any files found in the B<lib/> | |
| 119 sub-directory of the package, but the C/C++ compiler usually require the | |
| 120 filename scheme B<lib>fooB<.a> and the Unix Dynamic Loader the filename | |
| 121 scheme B<lib>fooB<.so> before they actually can use the file. | |
| 122 | |
| 123 =back | |
| 124 | |
| 125 It is obvious that more sub-directories in a package installation | |
| 126 might exist -- for instance B<share/>, B<var/>, B<libexec/>, etc. But | |
| 127 B<openpkg lsync> intentionally does not link files in those directories into | |
| 128 corresponding directories of the access layer, because those files do | |
| 129 not require that they are located in a global area in order to be used. | |
| 130 So B<openpkg lsync> only creates the access layer for files where a common area | |
| 131 is required for (easy) use. | |
| 132 | |
| 133 =head1 SPECIAL FEATURES | |
| 134 | |
| 135 There are two special features supported by B<openpkg lsync>: | |
| 136 | |
| 137 =over 4 | |
| 138 | |
| 139 =item B<Run-Command Files> | |
| 140 | |
| 141 B<openpkg lsync> on startup implicitly reads command line options from | |
| 142 C<.lsyncrc> files. They are searched in all parent directories and in | |
| 143 the callers home directory. Their contents is prepended to the list of | |
| 144 given command line options. | |
| 145 | |
| 146 =item B<Multiple Package Versions> | |
| 147 | |
| 148 B<openpkg lsync> skips all directories under I<root>/I<pkgdir>/ which contain | |
| 149 the pattern "-[0-9]" in their directory name. On the other hand, | |
| 150 B<openpkg lsync> follows also symbolic links under I<root>/I<pkgdir>/. | |
| 151 This can be used for installing multiple versions of a package and | |
| 152 switching between them. For instance, if version 1.0 of package | |
| 153 "foo" is installed into directory I<root>/I<pkgdir>/foo-1.0, | |
| 154 version 1.1 into I<root>/I<pkgdir>/foo-1.1 and version 1.2 into | |
| 155 I<root>/I<pkgdir>/foo-1.2, B<openpkg lsync> does skip all three. To enable | |
| 156 version 1.1 one just creates a symbolic link I<root>/I<pkgdir>/foo | |
| 157 pointing to foo-1.1. Then B<openpkg lsync> picks up the files in | |
| 158 I<root>/I<pkgdir>/foo-1.1. If you want to temporarily upgrade to | |
| 159 foo-1.2, all you have to do is to change the symlink pointing from | |
| 160 foo-1.1 to foo-1.2. | |
| 161 | |
| 162 =item B<Temporarily Deactivated Package> | |
| 163 | |
| 164 One can deactivate a package "foo" by going to I<root>/I<pkgdir>/foo/ | |
| 165 and running "openpkg lsync --local --uninstall", of course. Alternatively | |
| 166 one can set the sticky bit on the directory I<root>/I<pkgdir>/foo. | |
| 167 Then B<openpkg lsync> also skips the package. Alternatively, assume | |
| 168 package "foo" as a whole should not be deactivated, but its | |
| 169 I<root>/I<pkgdir>/foo/lib directory (usually because this directory | |
| 170 unfortunately contains non-library files), one just sets the sticky bit | |
| 171 on I<root>/I<pkgdir>/foo/lib. | |
| 172 | |
| 173 =back | |
| 174 | |
| 175 =head1 OPTIONS | |
| 176 | |
| 177 =over 4 | |
| 178 | |
| 179 =item B<--version>, B<-v> | |
| 180 | |
| 181 Display program version information only. | |
| 182 | |
| 183 =item B<--help>, B<-h> | |
| 184 | |
| 185 Display program usage information only. | |
| 186 | |
| 187 =item B<--init>, B<-i> | |
| 188 | |
| 189 Create an initial access layer hierarchy under I<root>. | |
| 190 | |
| 191 =item B<--nop>, B<-n> | |
| 192 | |
| 193 No Operation -- causes B<openpkg lsync> to not perform any filesystem | |
| 194 operations. In conjunction with B<--trace> you can at least see what | |
| 195 would be executed. | |
| 196 | |
| 197 =item B<--quiet>, B<-q> | |
| 198 | |
| 199 Forces B<openpkg lsync> to perform the operations quietly, i.e., without any | |
| 200 verbose messages. | |
| 201 | |
| 202 =item B<--trace>, B<-t> | |
| 203 | |
| 204 Forces B<openpkg lsync> to show what filesystem operations are performed. | |
| 205 | |
| 206 =item B<--local>, B<-l> | |
| 207 | |
| 208 This restricts the operations to a local package area. This option can | |
| 209 only be used if you are physically staying below a package sub-directory | |
| 210 under I<root>/I<pkgdir>/. For instance, when you are staying in | |
| 211 I<root>/I<pkgdir>/bar or I<root>/I<pkgdir>/bar/bin and use B<--local>, | |
| 212 all operations are restricted to the package "bar". | |
| 213 | |
| 214 =item B<--uninstall>, B<-u> | |
| 215 | |
| 216 This performs only package uninstallation operations, i.e., only | |
| 217 symbolic links are removed. This can be used to completely empty the | |
| 218 access layer. Additionally it is very useful in combination with | |
| 219 B<--local> in order to uninstall a particular package without having to | |
| 220 remove its files. | |
| 221 | |
| 222 =item B<--root=>I<root> | |
| 223 | |
| 224 Sets the root directory where the access layer and package subdirectory | |
| 225 is located. The default can be determined by running C<openpkg lsync --help> | |
| 226 (see section "Current configuration"). | |
| 227 | |
| 228 =item B<--pkgdir=>I<pkgdir> | |
| 229 | |
| 230 Sets the sub-directory under the root directory where packages are | |
| 231 located. The default can be determined by running C<openpkg lsync --help> (see | |
| 232 section "Current configuration"). | |
| 233 | |
| 234 =item B<--subdirs=>I<subdirs>[,I<subdir>,...] | |
| 235 | |
| 236 Sets one or more sub-directories of the access layer on which B<openpkg lsync> | |
| 237 should act. The default can be determined by running C<openpkg lsync --help> | |
| 238 (see section "Current configuration"). | |
| 239 | |
| 240 =back | |
| 241 | |
| 242 =head1 RESULTS | |
| 243 | |
| 244 This program uses the following return codes on exit: 0 (operation | |
| 245 successful), 1 (system error), 2 (command line error) and 3 (other user | |
| 246 error). | |
| 247 | |
| 248 =head1 HISTORY | |
| 249 | |
| 250 The idea of filesystem access layers consisting of symbolic links | |
| 251 pointing to actual package installation areas is a rather old one. It | |
| 252 dates back to the early days of Unix and was implemented many times over | |
| 253 the last decades. One of many implementation was B<GenOPT>, written by | |
| 254 Ralf S. Engelschall for sd&m GmbH & Co KG, Munich in 1992. The name | |
| 255 indicates the programs purpose: to generate symbolic links in an access | |
| 256 layer which was located under C</opt>. B<GenOPT> was very flexible, but | |
| 257 hence also very complex. Because of lack of documentation it was never | |
| 258 released and so only used at sd&m and on all machines which were under | |
| 259 control of Ralf S. Engelschall. | |
| 260 | |
| 261 For Cable & Wireless, Munich, the old B<GenOPT> principle was again | |
| 262 needed to manage the C</cw/local> area on their servers. For this in | |
| 263 November 2000 the functionality of B<GenOPT> was revised, heavily | |
| 264 stripped down and finally implemented from scratch. The result is the | |
| 265 current B<openpkg lsync>. | |
| 266 | |
| 267 =head1 AUTHOR | |
| 268 | |
| 269 Ralf S. Engelschall | |
| 270 rse@engelschall.com | |
| 271 www.engelschall.com | |
| 272 | |
| 273 =cut | |
| 274 |
