SCons/Tool/tar.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 __COPYRIGHT__
   4
   5 This file is processed by the bin/SConsDoc.py module.
   6 See its __doc__ string for a discussion of the format.
   7 -->
   8
   9 <!DOCTYPE sconsdoc [
  10 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  11 %scons;
  12 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  13 %builders-mod;
  14 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  15 %functions-mod;
  16 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  17 %tools-mod;
  18 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  19 %variables-mod;
  20 ]>
  21
  22 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  23           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  24           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  25
  26 <tool name="tar">
  27 <summary>
  28 <para>
  29 Sets construction variables for the &tar; archiver.
  30 </para>
  31 </summary>
  32 <sets>
  33 <item>TAR</item>
  34 <item>TARFLAGS</item>
  35 <item>TARCOM</item>
  36 <item>TARSUFFIX</item>
  37 </sets>
  38 <uses>
  39 <item>TARCOMSTR</item>
  40 </uses>
  41 </tool>
  42
  43 <builder name="Tar">
  44 <summary>
  45 <para>
  46 Builds a tar archive of the specified files
  47 and/or directories.
  48 Unlike most builder methods,
  49 the
  50 &b-Tar;
  51 builder method may be called multiple times
  52 for a given target;
  53 each additional call
  54 adds to the list of entries
  55 that will be built into the archive.
  56 Any source directories will
  57 be scanned for changes to
  58 any on-disk files,
  59 regardless of whether or not
  60 &scons;
  61 knows about them from other Builder or function calls.
  62 </para>
  63
  64 <example_commands>
  65 env.Tar('src.tar', 'src')
  66
  67 # Create the stuff.tar file.
  68 env.Tar('stuff', ['subdir1', 'subdir2'])
  69 # Also add "another" to the stuff.tar file.
  70 env.Tar('stuff', 'another')
  71
  72 # Set TARFLAGS to create a gzip-filtered archive.
  73 env = Environment(TARFLAGS = '-c -z')
  74 env.Tar('foo.tar.gz', 'foo')
  75
  76 # Also set the suffix to .tgz.
  77 env = Environment(TARFLAGS = '-c -z',
  78                   TARSUFFIX = '.tgz')
  79 env.Tar('foo')
  80 </example_commands>
  81 </summary>
  82 </builder>
  83
  84 <cvar name="TAR">
  85 <summary>
  86 <para>
  87 The tar archiver.
  88 </para>
  89 </summary>
  90 </cvar>
  91
  92 <cvar name="TARCOM">
  93 <summary>
  94 <para>
  95 The command line used to call the tar archiver.
  96 </para>
  97 </summary>
  98 </cvar>
  99
 100 <cvar name="TARCOMSTR">
 101 <summary>
 102 <para>
 103 The string displayed when archiving files
 104 using the tar archiver.
 105 If this is not set, then &cv-link-TARCOM; (the command line) is displayed.
 106 </para>
 107
 108 <example_commands>
 109 env = Environment(TARCOMSTR = "Archiving $TARGET")
 110 </example_commands>
 111 </summary>
 112 </cvar>
 113
 114 <cvar name="TARFLAGS">
 115 <summary>
 116 <para>
 117 General options passed to the tar archiver.
 118 </para>
 119 </summary>
 120 </cvar>
 121
 122 <cvar name="TARSUFFIX">
 123 <summary>
 124 <para>
 125 The suffix used for tar file names.
 126 </para>
 127 </summary>
 128 </cvar>
 129
 130 </sconsdoc>