summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Tool/zip.xml
blob: 9d3494e181f0499207eb3734fef37d1a6af4d197 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2001 - 2016 The SCons Foundation

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="zip">
<summary>
<para>
Sets construction variables for the &zip; archiver.
</para>
</summary>
<sets>
<item>ZIP</item>
<item>ZIPFLAGS</item>
<item>ZIPCOM</item>
<item>ZIPCOMPRESSION</item>
<item>ZIPSUFFIX</item>
</sets>
<uses>
<item>ZIPCOMSTR</item>
</uses>
</tool>

<builder name="Zip">
<summary>
<para>
Builds a zip archive of the specified files
and/or directories.
Unlike most builder methods,
the
&b-Zip;
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
&scons;
knows about them from other Builder or function calls.
</para>

<example_commands>
env.Zip('src.zip', 'src')

# Create the stuff.zip file.
env.Zip('stuff', ['subdir1', 'subdir2'])
# Also add "another" to the stuff.tar file.
env.Zip('stuff', 'another')
</example_commands>
</summary>
</builder>

<cvar name="ZIP">
<summary>
<para>
The zip compression and file packaging utility.
</para>
</summary>
</cvar>

<cvar name="ZIPCOM">
<summary>
<para>
The command line used to call the zip utility,
or the internal Python function used to create a
zip archive.
</para>
</summary>
</cvar>

<cvar name="ZIPCOMSTR">
<summary>
<para>
The string displayed when archiving files
using the zip utility.
If this is not set, then &cv-link-ZIPCOM;
(the command line or internal Python function) is displayed.
</para>

<example_commands>
env = Environment(ZIPCOMSTR = "Zipping $TARGET")
</example_commands>
</summary>
</cvar>

<cvar name="ZIPCOMPRESSION">
<summary>
<para>
The
<varname>compression</varname>
flag
from the Python
<filename>zipfile</filename>
module used by the internal Python function
to control whether the zip archive
is compressed or not.
The default value is
<literal>zipfile.ZIP_DEFLATED</literal>,
which creates a compressed zip archive.
This value has no effect if the
<literal>zipfile</literal>
module is unavailable.
</para>
</summary>
</cvar>

<cvar name="ZIPFLAGS">
<summary>
<para>
General options passed to the zip utility.
</para>
</summary>
</cvar>

<cvar name="ZIPSUFFIX">
<summary>
<para>
The suffix used for zip file names.
</para>
</summary>
</cvar>

<cvar name="ZIPROOT">
<summary>
<para>
An optional zip root directory (default empty).  The filenames stored
in the zip file will be relative to this directory, if given.
Otherwise the filenames are relative to the current directory of the
command.
For instance:
</para>
<example_commands>
env = Environment()
env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
</example_commands>
<para>
will produce a zip file <literal>foo.zip</literal>
containing a file with the name
<literal>subdir2/file1</literal> rather than
<literal>subdir1/subdir2/file1</literal>.
</para>
</summary>
</cvar>
</sconsdoc>