- initial import of revision 374 from cnc
[apt.git] / contrib / apt-wrapper / apt.1.xml
1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4
5 <!ENTITY % aptent SYSTEM "apt.ent">
6 <!ENTITY rpm "<citerefentry>
7     <refentrytitle><command>rpm</command></refentrytitle>
8     <manvolnum>1</manvolnum>
9   </citerefentry>"
10 >
11
12 %aptent;
13 ]>
14
15 <refentry>
16
17  <refentryinfo>
18    <author>
19     <surname>Debian apt development team</surname>
20    </author>
21    <author>
22     <surname>Conectiva apt-rpm development team</surname>
23    </author>
24    &apt-product;
25    <!-- The last update date -->
26    <date>24 June 2004</date>
27    <copyright>
28     <year>2004</year>
29     <holder>Richard Bos</holder>
30    </copyright>
31  </refentryinfo>
32
33  <refmeta>
34    <refentrytitle>apt</refentrytitle>
35    <manvolnum>1</manvolnum>
36  </refmeta>
37  
38  <!-- Man page title -->
39  <refnamediv>
40     <refname>apt</refname>
41     <refpurpose>Advanced Package Tool</refpurpose>
42  </refnamediv>
43
44  <!-- Arguments -->
45  <refsynopsisdiv>
46    <cmdsynopsis>
47       <command>apt</command>
48       <arg><option><replaceable>options</replaceable></option></arg>
49       <arg><option><replaceable>apt-rpm options</replaceable></option></arg>
50       <arg><option><replaceable>action</replaceable></option></arg>
51       <arg><option><replaceable>packages</replaceable></option></arg>
52    </cmdsynopsis>
53  </refsynopsisdiv>
54
55  <refsect1><title>Description</title>
56    <para>Apt provides a single command line user interface for the following
57     commands: &apt-get;, &apt-cache;, &apt-config;, &apt-cdrom; and
58     the <command>rpm</command> query possibilities.
59     Besides  the  single interface it provides some additional
60     options that are specific to apt in combination with rpm.</para>
61
62    <para>Unless the <option>-h</option>, <option>--help</option>,
63     <option>-v</option>, or <option>--version</option> option is
64     given one of the commands mentioned in the ACTIONS section must be
65     present.</para>
66
67    <para>Detailed information about each apt command and its options
68     can be found in the man pages that belong to the dispatched apt
69     applications.</para>
70
71  </refsect1>
72
73  <refsect1><title>Actions</title>
74   <para>Actions supported by <command>apt</command>:
75   <literal>add</literal>,
76   <literal>autoclean</literal>,
77   <literal>build-dep</literal>,
78   <literal>check</literal>,
79   <literal>clean</literal>,
80   <literal>depends</literal>,
81   <literal>dist-upgrade</literal>,
82   <literal>dotty</literal>,
83   <literal>dump</literal>,
84   <literal>dumpavail</literal>,
85   <literal>gencaches</literal>,
86   <literal>groupinstall</literal>,
87   <literal>groupnames</literal>,
88   <literal>groupremove</literal>,
89   <literal>ident</literal>,
90   <literal>install</literal>,
91   <literal>list-extras</literal>,
92   <literal>list-nodeps</literal>,
93   <literal>moo</literal>,
94   <literal>pkgnames</literal>,
95   <literal>policy</literal>,
96   <literal>query</literal>,
97   <literal>querytags</literal>,
98   <literal>rdepends</literal>.
99   <literal>reinstall</literal>.
100   <literal>remove</literal>,
101   <literal>script</literal>,
102   <literal>search</literal>,
103   <literal>show</literal>,
104   <literal>showgroup</literal>,
105   <literal>showpkg</literal>,
106   <literal>showsrc</literal>,
107   <literal>source</literal>,
108   <literal>stats</literal>,
109   <literal>unmet</literal>,
110   <literal>update</literal>,
111   <literal>upgrade</literal>,
112   <literal>whatdepends</literal>,
113   <literal>xvcg</literal>.</para>
114
115   <variablelist>
116    <varlistentry><term><literal>groupinstall</literal></term>
117     <listitem><para>Install a group (or groups) of packages.  Most often
118      those groups are defined by the distributor.
119      Configuration item: Scripts::Groupinstall::Backend</para></listitem>
120    </varlistentry>
121
122    <varlistentry><term><literal>groupremove</literal></term>
123     <listitem><para>Remove a group (or groups) of packages.  Most often
124      those groups are defined by the distributor.
125      Configuration item: Scripts::Groupinstall::Backend</para></listitem>
126    </varlistentry>
127
128    <varlistentry><term><literal>list-nodeps</literal></term>
129     <listitem><para>list all installed packages that are not required by any other
130      installed package.</para></listitem>
131    </varlistentry>
132
133    <varlistentry><term><literal>list-extras</literal></term>
134     <listitem><para>shows packages not found in any online repositories.
135      These are packages downloaded or build and installed locally. It's useful
136      to review that list and decide if all those packages are still needed.
137      Specifically if the system is used to build packages distributed to other
138      systems.  It's very important to be aware of all installed non-standard
139      packages to avoid dependencies that cannot be satisfied from the standard
140      repository.</para></listitem>
141    </varlistentry>
142
143    <varlistentry><term><literal>list-nodeps</literal></term>
144     <listitem><para>list all installed packages that are not required by any other
145      installed package.</para></listitem>
146    </varlistentry>
147
148    <varlistentry><term><literal>reinstall</literal></term>
149     <listitem><para>installs a package again, even if the package is already
150      installed.</para></listitem>
151    </varlistentry>
152
153    <varlistentry><term><literal>showgroup</literal></term>
154     <listitem><para>Provide information about group (or groups).  Most often
155      those groups are defined by the distributor.
156      Configuration item: Scripts::Groupinstall::Backend</para></listitem>
157    </varlistentry>
158
159    <varlistentry><term><literal>groupnames</literal></term>
160     <listitem><para>Show available groups.  Most often those groups are defined
161      by the distributor.  Configuration item:
162      Scripts::Groupinstall::Backend</para></listitem>
163    </varlistentry>
164   </variablelist>
165
166   <para>The functionality of the remaining actions are provided by other
167   apt tools.  The actions listed by their respective command:</para>
168   <variablelist>
169    <varlistentry><term><command>apt-get</command></term>
170     <listitem><para><literal>autoclean</literal>,
171      <literal>build-dep</literal>,
172      <literal>check</literal>,
173      <literal>clean</literal>,
174      <literal>dist-upgrade</literal>,
175      <literal>install</literal>,
176      <literal>moo</literal>,
177      <literal>remove</literal>,
178      <literal>reinstall</literal>.
179      <literal>script</literal>,
180      <literal>source</literal>,
181      <literal>update</literal>,
182      <literal>upgrade</literal>.</para>
183     </listitem>
184    </varlistentry>
185   </variablelist>
186
187   <variablelist>
188    <varlistentry><term><command>apt-cache</command></term>
189     <listitem><para><literal>add</literal>,
190      <literal>depends</literal>,
191      <literal>dotty</literal>,
192      <literal>dump</literal>,
193      <literal>dumpavail</literal>,
194      <literal>gencaches</literal>,
195      <literal>pkgnames</literal>,
196      <literal>policy</literal>,
197      <literal>rdepends</literal>.
198      <literal>search</literal>,
199      <literal>show</literal>,
200      <literal>showpkg</literal>,
201      <literal>showsrc</literal>,
202      <literal>stats</literal>,
203      <literal>unmet</literal>,
204      <literal>whatdepends</literal>,
205      <literal>xvcg</literal>.</para>
206     </listitem>
207    </varlistentry>
208   </variablelist>
209
210   <variablelist>
211    <varlistentry><term><command>apt-config</command></term>
212     <listitem><para><literal>shell</literal>,
213      <literal>dump</literal>.</para>
214     </listitem>
215    </varlistentry>
216   </variablelist>
217
218   <variablelist>
219    <varlistentry><term><command>apt-cdrom</command></term>
220     <listitem><para><literal>add</literal>,
221      <literal>ident</literal>.</para>
222     </listitem>
223    </varlistentry>
224   </variablelist>
225
226  </refsect1>
227
228  <refsect1><title>Options</title>
229
230    <variablelist>
231      <varlistentry><term><option>--checksig</option></term>
232      <listitem><para>checks the integrity and origin of the candidate packages to
233       be installed.  If the check fails for 1 or more packages non of the candidate
234       packages will be installed!  In case the signature check fails use the --hold
235       argument to keep back the offending package(s) or use the --no-checksig argument
236       to skip the package integrity check.  More about package checking can be
237       found in the rpm manual.
238       Configuration item: <literal>RPM::GPG-Check</literal>.
239       </para>
240      </listitem>
241      </varlistentry>
242
243      <varlistentry><term><option>--hold</option></term>
244      <listitem><para>puts a package on hold.  A package on hold won't be upgraded
245       unless overruled with the <literal>install</literal> action.  Repeat this option
246       if multiple packages must be kept from upgrading.  This option
247       uses regular expressions to find the package to be put on hold.
248       E.g. in case the package "at" must be hold, it must be specified
249       as --hold ^at$, if not done like this a package like
250       <literal>attr</literal> will be put on hold as well.  In any case
251       it is better to put packages on hold with the
252       <literal>rpm::hold</literal> variable in the file
253       <filename>apt.conf</filename>!</para>
254      </listitem>
255      </varlistentry>
256
257      <varlistentry><term><option>--no-checksig</option></term>
258      <listitem><para>Do not check the integrity of the packages to be installed.
259       It can be used if the integrity check fails for 1 or more packages, but
260       the packages have been obtained from a save origin.
261       Configuration item: <literal>RPM::GPG-Check</literal>.
262       </para>
263      </listitem>
264      </varlistentry>
265
266      <varlistentry><term><option>--no-postscript</option></term>
267      <listitem><para>Do not run a postscript after packages have been upgraded,
268       degraded, removed or installed.
269       Configuration item: <literal>Scripts::Options::RunPostScript</literal>.
270       </para>
271      </listitem>
272      </varlistentry>
273
274      <varlistentry><term><option>--postscript</option></term>
275      <listitem><para>Run a postscript after packages have been upgraded, degraded, removed or
276       installed.  The script to use is specified with configuration item:
277       <literal>Scripts::PM::Post::</literal>.  With this option it is possible to run
278       for example <literal>ldconfig</literal> or a distribution specific configuration
279       script.
280       Configuration item: <literal>Scripts::Options::RunPostScript</literal>.
281       </para>
282      </listitem>
283      </varlistentry>
284
285      <varlistentry><term><option>--show-rpm-command</option></term>
286      <listitem><para>Shows the exact rpm command to be performed, during
287       <literal>install</literal>, <literal>upgrade</literal> or
288       <literal>dist-upgrade</literal> actions.  The action itself
289       will not be performed.</para>
290      </listitem>
291      </varlistentry>
292
293      <varlistentry><term><option>--sourceslist</option></term>
294      <listitem><para>Select the sourceslist file to be used
295       (default is <filename>/etc/apt/sources.list</filename>).</para>
296      </listitem>
297      </varlistentry>
298
299      &apt-commonoptions;
300    </variablelist>
301
302  </refsect1>
303
304  <refsect1><title>Rpm options</title>
305    <para>Options handed over to <command>rpm</command>, see rpm man page
306     for their functionality.</para>
307
308    <variablelist>
309      <varlistentry><term><option>--test</option></term>
310      <listitem><para><command>Rpm</command> option
311       <literal>--test</literal>.</para>
312      </listitem>
313      </varlistentry>
314    </variablelist>
315
316    <variablelist>
317      <varlistentry><term><option>--force-rpm</option></term>
318      <listitem><para><command>Rpm</command> option
319       <literal>--force</literal>.</para>
320      </listitem>
321      </varlistentry>
322    </variablelist>
323
324  </refsect1>
325
326  <refsect1><title>Files</title>
327    <variablelist>
328      <varlistentry><term><filename>/usr/lib/apt/scripts</filename></term>
329      <listitem><para>APT lua scripts.
330      Configuration item: <literal>Dir::Bin::scripts</literal>.</para></listitem>
331      </varlistentry>
332    </variablelist>
333
334  </refsect1>
335
336  <refsect1><title>Environment</title>
337    <variablelist>
338      <varlistentry><term><option>APT_VERBOSE</option></term>
339      <listitem><para>If <literal>APT_VERBOSE</literal> is defined <command>apt</command>
340       will show which application is being dispatched.</para>
341      </listitem>
342      </varlistentry>
343    </variablelist>
344  </refsect1>
345
346  <refsect1><title>Caveats</title>
347    <para>There are 2 apt actions, <literal>add</literal> and
348     <literal>dump</literal>, that are used by several apt commands.
349     The action <literal>add</literal> is used by
350     <command>apt-cdrom</command> and <command>apt-cache</command>.
351     <command>apt</command> uses <literal>add</literal> from <command>apt-cdrom.</command>
352     The action <literal>dump</literal> is used by <command>apt-config</command> and
353     <command>apt-cache</command>.  <command>apt</command> uses <literal>dump</literal> from
354     <command>apt-config</command>.</para>
355  </refsect1>
356
357  <refsect1><title>See Also</title>
358    <para>&apt-get;, &apt-cache;, &apt-config;, &apt-cdrom;, &rpm;</para>
359  </refsect1>
360
361  <refsect1><title>Diagnostics</title>
362    <para><command>apt</command> returns zero on normal operation, decimal 100 on error.
363    </para>
364  </refsect1>
365
366  <refsect1><title>Bugs</title>
367    <para>Report bugs to
368    <email>apt-rpm@distro2.conectiva.com.br</email></para>
369  </refsect1>
370
371 </refentry>
372