1=head1 NAME 2 3XStow, replacement for GNU Stow 4 5=head1 SYNOPSIS 6 7xstow [OPTION ...] PACKAGE 8 9#ifdef ENABLE_STATIC 10xstow-static [OPTION ...] PACKAGE 11 12xstow-stow [OPTION ...] PACKAGE 13#endif 14 15=head1 DESCRIPTION 16 17XStow is a replacement of GNU Stow (B<stow>) written in C++. It 18supports all features of Stow with some extensions. 19 20XStow as GNU Stow, are programs for managing the installation of software 21packages, keeping them separate (/usr/local/stow/emacs 22vs. /usr/local/stow/perl, for example) while making them appear to be 23installed in the same place (/usr/local). 24 25#ifdef ENABLE_STATIC 26By default 3 versions of XStow will be compiled 27 28=over 29 30=item B<xstow> 31 32The default binary (dynamically linked) 33 34=item B<xstow-static> 35 36A static version with all enabled features except the ncurses support 37 38=item B<xstow-stow> 39 40A static version with few extensions, which results in a smaller binary. 41All features that will blow up the binary and not required for being 42compatible to GNU Stow are disabled. 43 44=back 45#endif 46=head1 USAGE 47 48xstow [OPTION ...] PACKAGE 49 50Install a package 51 52 xstow foobar 53 54Uninstall package 55 56 xstow -D foobar 57 58 59=head1 OPTIONS 60 61=over 62 63=item B<-dl -debug-level> INT 64 65Set's the debug level. An unsigned integer is accepted. The 66default value is 0. 67 68=item B<-dm -debug-module> [ALL|ARG|MAIN|TREE|CPPDIR] 69 70Filter messages from a specific module. 71 72 73=item B<-h -help> 74 75Shows a help screen. 76 77=item B<-V -Version> 78 79Displays XStows version number and supported features. 80 81=item B<-n -no> 82 83Do not actually make changes 84 85=item B<-c -conflicts> 86 87Scan for conflicts, implies B<-n>. 88 89=item B<-s -simulate> 90 91Simulate installation. If this option is set permission problems will 92be ignored and B<-verbose> will be set to 1. 93 94=item B<-d -dir> DIR 95 96Set stow dir to DIR. The default is the current directory. 97 98=item B<-d -target> DIR 99 100Set target to DIR. The default is the parent of the stow directory. 101 102=item B<-v -verbose> [0|1|2|3] 103 104Increase verboseness. Possible levels are 0,1,2 or 3. Simple setting 105B<-v> or B<-verbose> adds 1. 106 107=item B<-D -delete> 108 109Unstow instead of stow. Deinstall the package. 110 111=item B<-R -restow> 112 113The same like B<-delete> followed by an reinstall. 114 115=item B<-ap -absolute-path> 116 117Create symlinks with absolute path names. XStow can always handle 118packages which were installed with this option. Installing one package 119with absolute path names and one without is no problem. Only the 120creation of the symlinks will be affected by this option. This will 121cause that if one package is installed with this option and one 122without, some of the symlinks of the first package, when they have to 123be recreated will be recreated as relative ones. It is not good idea 124doing this, even XStow does not have any problems with it. 125I<Warning:> Breaks compatibility with Stow! 126 127=item B<-tr -traversable> LINKS 128 129A list of links pointing to directories, that can be ignored. 130eg.: /usr/local/man is a link to /usr/local/share/man 131I<Warning:> Breaks compatibility with Stow! 132 133=item B<-tkt -tr-keep-targets> 134 135Add the list of traversable links also to the keep targets list. This 136prevents the targets of the links from being removed by XStow, which 137would cause that the traversable link becomes a dead link. 138 139#ifdef ENABLE_FNMATCH 140=item B<-tre -tr-auto> PATTERN 141 142Automatically add links which target matches this pattern. 143#endif 144 145#ifdef ENABLE_REGEX 146=item B<-tre -tr-auto-regex> REGEX 147 148Automatically add links which target matches this pattern. 149#endif 150 151=item B<-kd -keep-dirs> DIR 152 153A list of directories, that should not be removed when a package will be 154removed. I<Warning:> Breaks compatibility with Stow! 155 156#ifdef ENABLE_FNMATCH 157=item B<-i -ignore> PATTERN 158 159Ignore files that matches this pattern. 160#endif 161 162#ifdef ENABLE_REGEX 163=item B<-ire -ignore-regex> REGEX 164 165Ignore files that matches this expression. 166#endif 167 168#ifdef ENABLE_NIGNORE 169=item B<-ni -nignore> PATTERN 170 171Ignore everything except file and directories matching this 172expression. eg: "systree/bintree systree/headertree". 173For using nignore support fnmatch and configration file 174support has to be enabled. For more details see xstow.ini(5). 175#endif 176 177#ifdef ENABLE_FNMATCH 178=item B<-cp -copy> PATTERN 179 180Copy files or directories that matching this pattern. 181#endif 182 183#ifdef ENABLE_REGEX 184=item B<-cre -copy-regex> REGEX 185 186Copy files or directories that matching this expression. 187#endif 188 189=item B<-ifd -i-file-in-dir> DIR/FILE 190 191Ignore this file in this directory. (Relative to the package dir.) 192 193=item B<-cfd -c-file-in-dir> DIR/FILE 194 195Copy this file in this directory. (Relative to the package dir.) 196 197=item B<-sd -stow-dirs> DIR 198 199A list of other stow dirs, that xstow is allowed change 200 201#ifdef ENABLE_FNMATCH 202=item B<-sda -sd-auto> PATTERN 203 204Automatically add directories to the list when matching this 205expression. 206#endif 207 208#ifdef ENABLE_REGEX 209=item B<-sde -sd-auto-regex> REGEX 210 211Automatically add directories to the list when matching this 212expression. 213#endif 214 215=item B<-pd -protect-dirs> DIR 216 217A list of other dirs, that xstow is not allowed change 218 219#ifdef ENABLE_FNMATCH 220=item B<-pda -pd-auto> PATTERN 221 222Automatically add directories to the list when matching this 223expression. 224#endif 225 226#ifdef ENABLE_REGEX 227=item B<-pde -pd-auto-regex> REGEX 228 229Automatically add directories to the list when matching this 230expression. 231#endif 232 233=item B<-pdt -pd-targets> DIRS 234 235A list of dirs, xstow is allowed to change. 236 237=item B<-pta -pdt-add-traversable> DIRS 238 239Automatically add the targets of traversable links to the targets list. 240 241=item B<-f -force> 242 243Skip conflicts if possible. 244 245#ifdef ENABLE_CURSES 246=item B<-C -no-curses> 247 248Do not detect the terminal width by using curses. 249There is more description at the environment variable section. 250#endif 251 252#ifdef ENABLE_INI 253=item B<-F file> 254 255Read this configuration file too. 256#endif 257 258=back 259 260=head1 RETURN VALUES 261 262=over 263 264=item B<0> 265 266On success. 267 268=item B<1> 269 270On a missspelled call of xstow. 271 272=item B<2> 273 274If an internal error occoured. 275 276=item B<3> 277 278Installing the package failed of some reason. All the prechecking was 279ok, but the execution of the exec list failed. 280 281=item B<4> 282 283Installing a package failed. 284 285=back 286 287=head1 ENVIRONMENT VARIABLES 288 289Since the debugging of the command line parsing can be hard if the 290debugging level is set by the command line there are two evironment 291variables: 292 293=over 294 295=item B<XSTOW_DEBUG_LEVEL> 296 297Same as the B<-debug-level> option. 298 299=item B<XSTOW_DEBUG_MODULE> 300 301Same as the B<-debug-module> option. 302 303Both values will be overwritten by the settings of the command line, 304after the command line was parsed. 305 306#ifdef ENABLE_INI 307=item B<XSTOW_USE_CURSES> 308 309Same as the B<-no-curses> option. 310 311In later versions xstow tried detecting the terminal width and height, 312by default at the startup routine. Even if this value is only used by 313the help screen. The result was: 314 315 $ TERM="" xstow 316 Error opening terminal: unknown. 317 318The error message is reported by the ncurses lib. This can cause problems 319if you wan't start xstow as a cron job. 320Now xstow tries detecting the terminal width not in it's startup, but 321when the help screen is printed out. As an extra option you can set 322the environment variable B<XSTOW_USE_CURSES>="0" this will tell xstow 323not using curses anyway. 324#endif 325 326=back 327 328#ifdef ENABLE_INI 329=head1 COFIGURATION FILES 330 331The configuration file xstow.ini can be located in /etc and/or in the 332current stow directory. For possible settings and syntax 333of this file see xstow.ini(5) 334 335In this manpage there are some detailed informations of some special 336settings of XStow too. Please read it! 337#endif 338 339=head1 EXAMPLES 340 341=head2 Common Usage 342 343As an example we install the ixlib library into the /usr/local/ tree. 344 345 tar xvfz ixlib-0.96.2.tar.gz 346 cd ixlib-0.96.2 347 ./configure 348 make 349 350So far, this was business as usual. 351 352I<Note:> by default the configure script prepares the application for 353being installed into /usr/local/. Have a look at configure --help for 354more info. 355 356Now installation is done by not installing ixlib directly into 357/usr/local/, we install it into /usr/local/stow/ixlib-0.96.2/. 358 359 make install prefix=/usr/local/stow/ixlib-0.96.2/ 360 361The last point is creating all necessare symlinks so that ixlib's 362include files can be found by the compiler in 363/usr/local/include. Therefore we are using xstow. 364 365 cd /usr/local/stow 366 xstow ixlib-0.96.2 367 368And all symlinks will be created. 369 370=head2 Installing XStow by using XStow 371 372After calling the configure script and make, XStow is installed into 373the stow directory as I showed it in the upper example. 374 375 make install prefix=/usr/local/stow/xstow-0.1.0 376 377Then you switch to the stow directory and call XStow 378 379 cd /usr/local/stow 380 xstow-0.1.0/bin/xstow xstow-0.1.0 381 382That is it. 383 384=head1 COMPATIBLE 385 386=head2 Link Creation 387 388By default XStow is fully Stow compatible. The usage of some of the 389advanced features can cause that Stow cannot handle the tree any 390more. 391 392=head2 Command Line Options 393 394XStow supports all command line options of Stow. Even it's 395format. 396 397Eg.: 398 xstow --verbose=2 foobar 399 400 401=head1 BUGS 402 403There are some nitty gritty cases, but no known bugs. 404 405=head1 WHY 406 407Stow requires Perl. But what's on systems where no Perl is available, 408or not yet installed? I tried compiling Stow with B<perlcc>, but it 409failed. 410 411=head1 AUTHORS 412 413XStow was written by Martin Oberzalek <kingleo@gmx.at>. 414 415=head1 COPYING 416 417XStow a replacement of GNU Stow written in C++. 418 419Copyright (C) 2002-2005 by Martin Oberzalek <kingleo@gmx.at> 420 421This program is free software; you can redistribute it and/or modify 422it under the terms of the GNU General Public License as published by 423the Free Software Foundation; either version 2 of the License, or 424(at your option) any later version. 425 426This program is distributed in the hope that it will be useful, 427but WITHOUT ANY WARRANTY; without even the implied warranty of 428MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 429GNU General Public License for more details. 430 431You should have received a copy of the GNU General Public License 432along with this program; if not, write to the Free Software 433Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 434 435=head1 SEE ALSO 436 437#ifdef ENABLE_INI 438xstow.ini(5) merge-info(1) stow(1) 439#else 440xstow(1) merge-info(1) stow(1) 441#endif 442 443GNU Stow has an excelent documentation. Have a look at the manual. 444http://www.gnu.org/software/stow/ 445