TODO

   1 FIXME:
   2  update web page and links etc
   3 ---
   4
   5
   6 when repacking archives, don't specify '.'. Instead specify each extracted file or
   7 directory. (Jens Schleusener)
   8
   9 ---
  10
  11 FIXME: implement -O fully! also, use if for compression only! or?
  12
  13 ---
  14
  15 $ arepack today.log.bz2 today.log.sz            [today.log.bz2 exists, today.log.sz doesn't]
  16 arepack: today.log.sz: no such file and cannot identify format from extension
  17 Use of uninitialized value $fmt2 in string eq at /home/usel/sys/bin/arepack line 354.
  18 today.log.bz2: extracted to `Unpack-4162/today.log'
  19 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1348.
  20 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1349.
  21 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1350.
  22 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1351.
  23 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1352.
  24 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1353.
  25 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1354.
  26 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1355.
  27 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1356.
  28 Use of uninitialized value $fmt in string eq at /home/usel/sys/bin/arepack line 1357.
  29 arepack: ../today.log.sz: no such file and cannot identify format from extension
  30
  31 ---
  32
  33 From Francois Marier: omit_garbage option, do not unpack
  34   Thumbs.db
  35   __MACOSX/
  36   ._filename
  37   .Trashes
  38   .DS_Store
  39 See also: http://unmac.rubyforge.org/
  40           http://github.com/fxn/unmac/blob/HEAD/lib/unmacer.rb
  41
  42
  43 add compression level control arguments: store (0) or 1-9
  44 allow user to add customer parameters to each archiver??
  45
  46 make use of modern tar options, like '--use-compress-program=prog'
  47 cfg_use_tar_compress_option?
  48
  49 if making RPM, then upload SRPM as well!
  50
  51 improve messages printed from arepack. sometimes prints unnecessary messages like "data.tar.gz: extracted to `Unpack-2962/data'"
  52
  53 cat mode is not supported for lzop, because it won't write to standard out
  54 unless we give it the -f option. Because of this we use lzop as if -c was
  55 not supported. This should be fixed in the future.
  56
  57 --no-umask option from Reuben to fix permissions of extracted files. perhaps change owner etc.
  58
  59 aunpack -e is default - or perhaps with option to make it default?
  60
  61 aremove tool
  62   how it should work:
  63     unpack archive to a separate directory
  64     for each unpacked file, check if it exists and is the same in the current directory.
  65     if yes, remove that file in the current directory, and (optionally) from unpacked directory as well.
  66     if no, remove that file from the unpacked directory
  67
  68 From Francois Marier <francois@debian.org>: check if pbzip2 is in the path and use it
  69
  70 rewrite atool implement extract_archive that is sensitive or not
  71
  72 add option to assume format with -F in some situations (like tar.gz)?
  73 add option to always assume -e? and add some option for the reverse (-s, --single)
  74 assume -e when passing a single directory as argument?
  75
  76 change back error messages to:
  77    cannot foo `bar': No such file or directory
  78   make function to format error message?
  79
  80 have autoconf generate files in debian subdir as well?
  81
  82 in readconfig, add datatype checking to options (bool/str/int/..)
  83
  84 add 'atest': test archive integrity
  85 make sure atool has non-zero rc when acat can't find a file (.arc files and possibly other)
  86
  87 improve error message when some program doesn't exist (now gets unnecessary lines)
  88
  89   arepack -F.tar.bz2 foo.tar.gz   would only gunzip then bzip2. tar not involved!
  90
  91 tests:
  92   does gzip support --?
  93   does tar support -z?
  94   does tar support -I?
  95   does tar support --?
  96   does zip treat *?[]\ chars in filenames specially?
  97
  98 use "--" with gzip and others?
  99
 100 Reasons to rewrite in C:
 101   - use manual ZIP code so that we can extract archive with '../foo' files too!
 102     tar fails entirely when the archive contains '../xxx' members.
 103   - the option --save-outdir in extract-to mode could be implemented
 104     easier.
 105   - multiple commands per action more easily (same with perl tho)
 106   - always identify format using magic values, ignoring extension (fast!)
 107   - i18n much easier (and faster)
 108
 109 Bugs
 110   implement list command for single compressed archives? only gzip supports -l
 111   consider:
 112       apack dummy.tar.gz /etc/hostname
 113       mkdir etc
 114       aunpack dummy.tar.gz
 115     Archive is now extracted with file as dummy/etc/hostname
 116     Should it be dummy/hostname or etc-1/hostname instead?
 117
 118 Other formats
 119   add support for SEA arc.
 120   add support for szip (hard because its interface is different from gzip)
 121   make an ACE archive (using winace stuff), test ACE extraction!
 122   add support for DEB files
 123      list:      dpkg-deb -c FILE.deb
 124      extract:   dpkg-deb -x FILE.deb $outdir/CONTENTS
 125                 dpkg-deb -e FILE.deb $outdir/DEBIAN
 126   JAR/ZIP:
 127     Implement 'use_jar_for_zip' - use jar for zip archives (fastjar) - test
 128     Rename 'use_zip_for_jar' - use zip for jar archives - test
 129     Enable add command for jar archives!
 130
 131
 132 Other features
 133   make a script to detect system settings and configure atool appropriately
 134   Make it possible to send additional arguments to RAR etc. engine configurable via command line?
 135     especially adiff diff -ruN (note the N) option
 136
 137 --------------------------------------------------------------------------------
 138
 139 libarchive:
 140   OpenArchive(fd)->archive
 141   CloseArchive(archive)
 142   GetType(archive)
 143
 144   BeginJob(archive)->job
 145   PerformJob(job)
 146   EndJob(job)
 147
 148   GetError(job)
 149   ErrorManger(job,callback)
 150   ProgressManager(job,callback)
 151
 152   CreateArchive(file)->archive
 153
 154   FileDescriptor
 155     close()
 156     read(data,amount)
 157     write(data,amount)
 158     seek(pos,whence)
 159
 160   FileIterator(job,fileselector,filecallback)
 161
 162   DeleteFile(job,fh)
 163   ExtractFile(job,fh,outfd)
 164   ReplaceFile(job,fh,infile)
 165
 166   AddFile(job,filename,extfile)
 167
 168 ---
 169
 170 verbosity levels:
 171   0 default, quiet
 172   1 verbose, print filenames
 173   2 very verbose, print long list format
 174
 175 extract: what to when local file exists, only when archive contains one file
 176 (and not in interactive mode)
 177   * (m)ove to subdirectory
 178   * (r)ename
 179   * move files to subdir, rename directory
 180   * for interactive mode only: (o)verwrite
 181
 182 how to extract single compressed file
 183   * delete original file afterwards
 184   * keep original file
 185   * don't extract at all (refuse)
 186
 187 add:
 188   * apack: create new archive (refuse if existing exists)
 189   * apack -a: add to existing archives (create if necessary)
 190
 191 ---
 192
 193 MAJOR options:
 194
 195   aunpack       -X      -x [DIR]        extract to dir
 196   apack         -A      -a              add files to archive (or create)
 197   apack         -C      -c              create only
 198   als           -L      -l              list files in archive
 199   acat          -P      -c/-p           print file (to standard out) in archive
 200
 201   adiff         -D      -d              print difference between two archives
 202   afind         -F      -f              find files in archive (emulate find)            [?]
 203
 204   arepack       -R      -r              extract and pack archives
 205
 206
 207
 208 als ARCHIVE1..
 209   -l            -l (long) like ls
 210   -f            -f (classify) like ls
 211   -m[TYPE]      from all archives, list only files matching (remaining args are matches)
 212
 213 prev: als -e *.tar              now:  als *.tar
 214 prev: als foo.tar f*            now:  als foo.tar -m f*
 215
 216 aunpack ARCHIVE1..
 217   -X DIR        where to extract to (otherwise be smart)
 218   -m[TYPE]      from all archives, extract only files matching (remaining args are matches)
 219
 220 apack ARCHIVE FILE1..
 221   -a            add files if archive already exists (without -a, refuse to overwrite existing)
 222   -e            all arguments are files (or dirs) to compress individually
 223   -F FORMAT     force file format
 224
 225   -f            allow overwriting of archives (clobber). NOTE: for safety, this implies
 226
 227
 228 --------------------------------------------------------------------------------
 229
 230 New rules format:
 231
 232 # This document shows how a future rules file format for atool could look. It
 233 # was written to outline what was necessary for such a format. It is quite
 234 # possible this format will never become a reality due to its complexity.
 235
 236 # use ; to separate commands!
 237
 238 # rules and configuration files are the same
 239
 240 noinclude               # don't include default rules/configuration file!
 241                         # (otherwise /etc/atool.rules will be included first)
 242                         # useful if you want to make your own rules completely
 243
 244 set path_zip "foobar"   # example of variable set in a configuration file
 245                         # (can only be done after option declared in format)
 246
 247 # the extract command defined here also handles extract-in (only outdir changes)
 248 # the create command refuses to create an existing archive
 249 # the add command will turn into a create command if the archive doesn't exist
 250 # the print command outputs a file in the archive to standard out
 251
 252 # variable namespace:
 253 #   read-only variables - $outdir, $archive, $args
 254 #   format-local variables - declared with 'variable'
 255 #   options - declared with option
 256
 257 # FIXME: what about about special exit codes (zip)? CHECK atool
 258
 259 format {
 260   name { zip jar }              # a name for users to use in -F option (force format)
 261   extension { .zip .jar }       # possible file extensions (ignored?)
 262   magic     { PK\003\004 }      # magic bytes (kinda regex?)
 263   option string path_zip "zip"
 264   option string path_unzip "unzip"
 265   command extract    { $path_unzip "-d" $outdir $archive $args }
 266   command add,create { $path_zip "-r" $archive $args }
 267   command print      { $path_unzip "-p" $archive $args }
 268   command list       { $path_unzip "-l" $archive $args }
 269   command common  {
 270     [ $verbosity >  1 ] "-v"            # this format means: add "-v" only if $verbosity > 1
 271     [ $verbosity <  0 ] "-qq"           # (the first string after [] applies, or block if { } )
 272     [ $verbosity == 0 ] "-q"
 273   }
 274   multiarchive true     # specifies that this archive may contain multiple files
 275   needs_cwd false       # specifies that this archive doesn't need to cwd to outdir on extract
 276                         # (technically we could autodetect this by seeing of $outdir is referenced
 277                         # in the extract command)
 278 }
 279
 280 format {
 281   name          { lha lzh }
 282   extension     { .lha .lzh }
 283   magic         { "..-lh[01234567 d]-" "..-lz[45s]-" }  # what about >20 byte x ; 2 string -lh6-
 284   option string path_lha "lha"
 285   command common { $path_lha }
 286   command extract { "x" $archive $args $outdirslash }   # outdirslash = outdir that ends in slash
 287   command add,create { "a" $archive $args }
 288   command print { "p" $archive $args }
 289   command list {
 290     "a"
 291     [ $verbosity >= 3 ] "v"
 292     [ $verbosity =  2 ] "l"
 293     [ $verbosity <= 1 ] "lq"
 294   }
 295   multiarchive true
 296   needs_cwd false
 297 }
 298
 299 format {
 300   name          { tar[+.]gz(ip)? }
 301   extension     { .tgz .tar.gz }
 302   option string path_tar "tar"                          # this one assume tar supports -z
 303   variable string opts
 304   command common { $path_tar [ $verbosity >= 1 ] [ $opts = "v" ] }      # a conditional
 305   command print { xO ++ $opts ++ zf }                   # ++ means concatenate
 306   command extract { x ++ $opts ++ zf -C $outdir }       # -C works on Sun too
 307   command list { t ++ $opts ++ zf }
 308   command create { c ++ $opts ++ zf }                   # tar can append (-r), but not tar+gz
 309   command common { $archive $args }
 310   multiarchive true
 311   needs_cwd false
 312 }
 313
 314 format {
 315   disabled                                              # do not use this format at all
 316   name          { tar[+.]gz(ip)? }
 317   extension     { .tgz .tar.gz }
 318   option string path_tar "tar"                          # this one does NOT assume tar supports -z
 319   option string path_gzip "gzip"
 320   variable string opts
 321   command common { [ $verbosity >= 1 ] [ $opts = "v" ] }
 322   command print { $path_gzip -cd $archive | $path_tar xO ++ $opts $args }
 323   command extract { $path_gzip -cd $archive | $path_tar x ++ $opts $args }
 324   command list { $path_gzip -cd $archive | $path_tar t ++ $opts $args }
 325   command create { $path_tar c ++ $opts $args | $path_gzip > $archive }
 326   multiarchive true
 327   needs_cwd false
 328   create_only true                                      # FIXME: maybe not necessary? (see create/add above)
 329 }
 330
 331
 332 --------
 333
 334 TODO.v2:
 335
 336 better extraction semantics, cleaner code
 337
 338  * always use change to directory for extraction, never specify dir on cmd command-line?
 339    use ../for instead of absolute dir
 340    merges extract-to and extract
 341
 342  * core support for multiple commands per mode (think debian)
 343
 344  * better control of user arguments to external command (@args)
 345
 346  * better solution than multiarchivecmd - cleaned up
 347
 348  * more general commands:
 349      test
 350
 351  * more general options
 352      compression level
 353
 354  * stripext only based on format! (e.g. unpack gz then strip .gz, not .tar.gz)
 355
 356 want aunpack -e to be default!
 357 remove dir: failure to remove a single file is fatal. chmod error isn't.
 358 chmod errors should be ignored altogheter?
 359
 360 always chdir on extract?
 361
 362 unified handling of single & non-single (wrt extract etc)
 363
 364 acat  displays *all* files or just first?
 365 apack creating a single archive with many files = ERROR
 366 extract-logic with -S:
 367   tar xvfz ...
 368   content-move DIR   or  atool --handle-extracted DIR
 369
 370 does unlink_dir handle . and .. (i.e. cur and up)?
 371 write safety check for those
 372
 373 use File::Spec abs2rel
 374
 375
 376
 377 ---
 378
 379 COMMANDS
 380
 381 apack   - create a new archive
 382 aunpack - extract files from an archive
 383 als     - list archive like ls
 384 afind   - list archive like find
 385 acat    - extract files from an archive to standard out
 386 aless   - extract files from an archive and pipe into a pager
 387 amore   - extract files from an archive and pipe into a pager
 388 adiff   - compare archives using diff
 389 agrep   - search files for a regular expression using grep
 390 aegrep  - search files for a regular expression using egrep
 391 afgrep  - search files for a regular expression using fgrep
 392 arepack - extract archives of one type and create archives of another
 393 acmp    - compare archives using cmp
 394 aadd    - add files to an existing archive (may require unpacking)
 395 atest   - test archive integrity (may unpack)
 396 amcfs   - midnight commander virtual file system (extfs)
 397
 398 OPTIONS
 399
 400 -F,--format     major format
 401 --format-in     format of files being read
 402 --format-out    format of files being created
 403 -f,--files      hereafter comes files (not archives)
 404 -o,--options    hereafter comes options for archiver programs
 405 -X,--extract-to
 406 -E,--explain
 407 -S,--simulate
 408 -q,--quiet      display no regular output
 409 -v,--verbose    display a little more output
 410 -z,--compression-level  compression level for gzip, bzip2, "1" to "9"
 411
 412 ERRORS
 413
 414 display at max two errors: one detailed ($!), one general ("command failed")
 415
 416 LOCALIZATION
 417
 418 FORMATS
 419
 420 add SEA arc
 421 add szip