SCons/Tool/tar.xml

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