root/current/host/trunk/apt-cross/trunk/apt-cross.1.xml

Revision 4249, 26.9 kB (checked in by codehelp, 7 months ago)

Make an interim Emdebian release for further testing.
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
3<!-- generate manpage using
4xsltproc -''-nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl apt-cross.1.xml
5-->
6<book label="apt-cross" status="0.9.2">
7  <bookinfo>
8    <title>apt-cross</title>
9    <date>Fri 20 Jun 2008 07:05:46 BST</date>
10    <releaseinfo>Release: 0.9.2</releaseinfo>
11  </bookinfo>
12  <chapter label="1" id="manpages">
13    <title>APT-CROSS</title>
14    <refentry id="aptcross1">
15      <refentryinfo>
16        <productname>apt-cross</productname>
17        <productnumber>1</productnumber>
18      </refentryinfo>
19      <refmeta>
20        <refentrytitle>APT-CROSS</refentrytitle>
21        <manvolnum>1</manvolnum>
22        <refmiscinfo class="source">apt-cross</refmiscinfo>
23        <refmiscinfo class="manual">apt-cross</refmiscinfo>
24      </refmeta>
25      <refnamediv id="name">
26        <refname>apt-cross</refname>
27        <refpurpose>apt support for cross compiling libraries</refpurpose>
28      </refnamediv>
29      <refsynopsisdiv>
30        <cmdsynopsis>
31          <command>apt-cross</command>
32          <group>
33            <arg>-a</arg>
34            <arg>--arch</arg>
35            <replaceable> ARCH</replaceable>
36          </group>
37          <group>
38            <arg>-S</arg>
39            <arg>--suite</arg>
40            <replaceable> SUITE</replaceable>
41          </group>
42          <group>
43            <arg>-m</arg>
44            <arg>--mirror</arg>
45            <replaceable> MIRROR</replaceable>
46          </group>
47          <group>
48            <arg>-f</arg>
49            <arg>--force</arg>
50          </group>
51          <group>
52            <arg choice="req">-g|--get</arg>
53            <replaceable> PACKAGE</replaceable>
54            <replaceable> ...</replaceable>
55          </group>
56        </cmdsynopsis>
57        <cmdsynopsis>
58          <command>apt-cross</command>
59          <group>
60            <arg>-a</arg>
61            <arg>--arch</arg>
62            <replaceable> ARCH</replaceable>
63          </group>
64          <group>
65            <arg>-S</arg>
66            <arg>--suite</arg>
67            <replaceable> SUITE</replaceable>
68          </group>
69          <group>
70            <arg>-m</arg>
71            <arg>--mirror</arg>
72            <replaceable> MIRROR</replaceable>
73          </group>
74          <group>
75            <arg>-f</arg>
76            <arg>--force</arg>
77          </group>
78          <group>
79            <arg>-x</arg>
80            <arg>--exclude</arg>
81            <replaceable> PACKAGE</replaceable>
82          </group>
83          <arg choice="req">-b|--build</arg>
84          <replaceable> PACKAGE</replaceable>
85          <replaceable> ...</replaceable>
86        </cmdsynopsis>
87        <cmdsynopsis>
88          <command>apt-cross</command>
89          <group>
90            <arg>-a</arg>
91            <arg>--arch</arg>
92            <replaceable> ARCH</replaceable>
93          </group>
94          <group>
95            <arg>-S</arg>
96            <arg>--suite</arg>
97            <replaceable> SUITE</replaceable>
98          </group>
99          <group>
100            <arg>-m</arg>
101            <arg>--mirror</arg>
102            <replaceable> MIRROR</replaceable>
103          </group>
104          <group>
105            <arg>-x</arg>
106            <arg>--exclude</arg>
107            <replaceable> PACKAGE</replaceable>
108          </group>
109          <group>
110            <arg>-k</arg>
111            <arg>--keep-temp</arg>
112          </group>
113          <group>
114            <arg>-n</arg>
115            <arg>--simulate</arg>
116          </group>
117          <arg choice="req">-i|--install</arg>
118          <replaceable> PACKAGE</replaceable>
119          <replaceable> ...</replaceable>
120        </cmdsynopsis>
121        <cmdsynopsis>
122          <command>apt-cross</command>
123          <group>
124            <arg>-a</arg>
125            <arg>--arch</arg>
126            <replaceable> ARCH</replaceable>
127          </group>
128          <arg choice="req">--remove|--purge|-r</arg>
129          <replaceable> PACKAGE</replaceable>
130          <replaceable> ...</replaceable>
131        </cmdsynopsis>
132        <cmdsynopsis>
133          <command>apt-cross</command>
134          <group>
135            <arg>-a</arg>
136            <arg>--arch</arg>
137            <replaceable> ARCH</replaceable>
138          </group>
139          <group>
140            <arg>-S</arg>
141            <arg>--suite</arg>
142            <replaceable> SUITE</replaceable>
143          </group>
144          <group>
145            <arg>-m</arg>
146            <arg>--mirror</arg>
147            <replaceable> MIRROR</replaceable>
148          </group>
149          <arg choice="req">-s|--show</arg>
150          <replaceable> PACKAGE</replaceable>
151          <replaceable> ...</replaceable>
152        </cmdsynopsis>
153        <cmdsynopsis>
154          <command>apt-cross</command>
155          <group>
156            <arg>-a</arg>
157            <arg>--arch</arg>
158            <replaceable> ARCH</replaceable>
159          </group>
160          <group>
161            <arg>-S</arg>
162            <arg>--suite</arg>
163            <replaceable> SUITE</replaceable>
164          </group>
165          <group>
166            <arg>-m</arg>
167            <arg>--mirror</arg>
168            <replaceable> MIRROR</replaceable>
169          </group>
170          <arg choice="req">-l|--list</arg>
171        </cmdsynopsis>
172        <cmdsynopsis>
173          <command>apt-cross</command>
174          <group>
175            <arg>-a</arg>
176            <arg>--arch</arg>
177            <replaceable> ARCH</replaceable>
178          </group>
179          <group>
180            <arg>-S</arg>
181            <arg>--suite</arg>
182            <replaceable> SUITE</replaceable>
183          </group>
184          <group>
185            <arg>-m</arg>
186            <arg>--mirror</arg>
187            <replaceable> MIRROR</replaceable>
188          </group>
189          <arg choice="req">-u|--update</arg>
190        </cmdsynopsis>
191        <cmdsynopsis>
192          <command>apt-cross</command>
193          <group>
194            <arg>-a</arg>
195            <arg>--arch</arg>
196            <replaceable> ARCH</replaceable>
197          </group>
198          <group>
199            <arg>-S</arg>
200            <arg>--suite</arg>
201            <replaceable> SUITE</replaceable>
202          </group>
203          <group>
204            <arg>-m</arg>
205            <arg>--mirror</arg>
206            <replaceable> MIRROR</replaceable>
207          </group>
208          <arg choice="req">--clean-lists</arg>
209        </cmdsynopsis>
210        <cmdsynopsis>
211          <command>apt-cross</command>
212          <group>
213            <arg>-a</arg>
214            <arg>--arch</arg>
215            <replaceable> ARCH</replaceable>
216          </group>
217          <group>
218            <arg>-S</arg>
219            <arg>--suite</arg>
220            <replaceable> SUITE</replaceable>
221          </group>
222          <group>
223            <arg>-m</arg>
224            <arg>--mirror</arg>
225            <replaceable> MIRROR</replaceable>
226          </group>
227          <arg choice="req">-c|--check</arg>
228        </cmdsynopsis>
229        <cmdsynopsis>
230          <command>apt-cross</command>
231          <group>
232            <arg>-?</arg>
233            <arg>-h</arg>
234            <arg>--help</arg>
235            <arg>--version</arg>
236          </group>
237        </cmdsynopsis>
238      </refsynopsisdiv>
239      <refsect1 id="description">
240        <title>DESCRIPTION</title>
241        <para><command>apt-cross</command> provides apt functionality for getting,
242        building and installing libraries and header files for cross-compiling using
243        <command>dpkg-cross</command>. <command>apt-cross</command>
244        <option>-i</option> will search for and download missing dependencies of the
245        requested package before building and installing the requested package and
246        dependencies using <command>dpkg-cross</command> and
247        <command>dpkg -i</command> (sudo required).
248        </para>
249        <para><command>apt-cross</command> is intended to make it easier to locate,
250        download, install and update cross-built libraries, directly from the
251        Debian archives.
252        </para>
253        <para><command>apt-cross</command> is not intended to handle applications
254        or <userinput>Architecture: all</userinput> packages
255        like <filename>foo-common</filename> or <filename>libfoo-common</filename>.
256        <command>apt-cross</command> can download the cross-compiling
257        version of those packages but does not build or install them - this can be done
258        with <command>dpkg-cross</command> <option>-A</option>
259        and <command>dpkg</command> <option>-i</option> if necessary. Note that
260        not all such packages can be installed in that way.
261        </para>
262        <para>Architecture-independent packages do not need to be converted, so
263        <command>apt-cross</command> omits all such packages from the dependency
264        calculations and ensures that <command>dpkg-cross</command> also drops
265        these packages from the dependencies of the generated package. One
266        exception is that <command>apt-cross</command> will process
267        development packages (-dev) that are Architecture: all.
268        </para>
269        <para>By default, <command>apt-cross</command> uses <filename>/etc/apt/sources.list</filename>
270        and <filename>/etc/apt/sources.list.d/*</filename> to find the latest
271        debian package file for the architecture specified (default is
272        the <command>dpkg-cross</command> default) and in the suite
273        specified (default is unstable). Alternatively, specify a different
274        mirror. Downloaded files can be passed directly to dpkg-cross using
275        the <option>-b</option> or <option>-i</option> commands to apt-cross. If the
276        local file is missing or out of date, a new one will be downloaded automatically.
277        </para>
278        <para>If the <command>apt-cross</command> cache for the specified suite and
279        architecture is older than 24hours, it will be updated automatically. If the
280        cache needs to be updated more frequently or if the cache becomes corrupted,
281        use <option>-u</option>|<option>--update</option>.
282        </para>
283        <refsect2>
284          <title>APT-CROSS AND CROSS-COMPILERS</title>
285          <para><command>apt-cross</command> does have limitations and cannot replicate
286        all behaviour associated with <command>apt</command> itself. In particular,
287        <command>apt-cross</command> cannot provide, build, install or download
288        a cross-compiler. Certain parts of the process to build a cross-compiling
289        toolchain do require <command>apt-cross</command> but you must obtain
290        a suitable set of packages from somewhere else or build the toolchain yourself.
291        See the <filename>emdebian-tools</filename> package for assistance with
292        cross-compilers and cross-building toolchains.
293        </para>
294        </refsect2>
295      </refsect1>
296      <refsect1 id="commands">
297        <title>COMMANDS</title>
298        <variablelist remap="TP">
299          <varlistentry>
300            <term><option>--g</option>|<option>--get</option> &lt;packages...&gt;</term>
301            <listitem>
302              <para>Retrieve the architecture-specific package(s) from the Debian
303              mirrors into the current directory. If the package has already been
304              downloaded, <command>apt-cross</command> will skip the download
305              unless <option>--force</option> is used.
306              </para>
307            </listitem>
308          </varlistentry>
309          <varlistentry>
310            <term><option>--b</option>|<option>--build</option> &lt;packages...&gt;</term>
311            <listitem>
312              <para>Retrieve the architecture-specific package(s) from the Debian
313              mirrors into the current directory and pass
314              to <command>dpkg-cross</command> to build a cross-built version.
315              </para>
316              <para>'Architecture: all' dependencies of the requested package are added to
317              the list of dependencies to be excluded from the cross package using
318              <command>dpkg-cross</command> <option>-X</option>.
319              </para>
320              <para><option>--build</option> will always replace any existing cross package
321              file in the same directory. Use <option>--force</option> only to ensure that
322              <command>apt-cross</command> gets a fresh package prior to conversion.
323              </para>
324              <para>Dependencies of the requested package are not processed recursively
325              so the cross package may be uninstallable without other cross packages,
326              see <option>--install</option> for that functionality.
327              </para>
328            </listitem>
329          </varlistentry>
330          <varlistentry>
331            <term><option>--i</option>|<option>--install</option> &lt;packages...&gt;</term>
332            <listitem>
333              <para>Retrieve the architecture-specific package(s) from the Debian
334              mirrors into the current directory. Check for dependencies that are
335              suitable for <command>dpkg-cross</command>, download each dependency
336              and build, then install the package and dependencies
337              using <command>dpkg-cross</command> and <command>dpkg -i</command>.
338              If successfully installed, the temporary downloaded archives are removed.
339              Requires working <command>sudo</command> setup and will prompt for the
340              sudo password if necessary (if sudo is not already cached).</para>
341            </listitem>
342          </varlistentry>
343          <varlistentry>
344            <term><option>-r</option>|<option>--remove</option>|<option>--purge</option>
345            &lt;packages...&gt;
346            </term>
347            <listitem>
348              <para>Remove the cross-built package by calling <command>dpkg</command>.
349              Requires working <command>sudo</command> setup and will prompt for the
350              sudo password if necessary (if sudo is not already cached).
351            </para>
352            </listitem>
353          </varlistentry>
354          <varlistentry>
355            <term><option>-s</option>|<option>--show</option> &lt;packages...&gt;</term>
356            <listitem>
357              <para>Show the package information for the cross-built packages specified.
358              If the package name does not end in -$arch-cross, the correct suffix will
359              be added. The output format is the same as the equivalent
360              <command>apt-cache show</command> output and includes the dependencies
361              of the cross-built package. Note that only the details of
362              cross-built packages (in the repository or installed) are displayed.
363              </para>
364            </listitem>
365          </varlistentry>
366          <varlistentry>
367            <term><option>-l</option>|<option>--list</option></term>
368            <listitem>
369              <para>List all cross-built package names.
370              (Similar to <command>apt-cache pkgnames</command>).
371              </para>
372            </listitem>
373          </varlistentry>
374          <varlistentry>
375            <term><option>-u</option>|<option>--update</option></term>
376            <listitem>
377              <para>Force the user-specific <command>apt-cross</command> cache
378              to be updated. Note that all sources for this suite on the specified
379              architecture will be erased before the package cache is updated.
380              If <filename>/etc/apt/sources.list</filename> or
381              <filename>/etc/apt/sources.list.d/*</filename> does not contain a
382              source for this suite, the updated cache for this suite will be
383              empty. Use <option>-m</option>|<option>--mirror</option> to specify
384              a source to be added to whatever sources are available for this
385              suite in <filename>/etc/apt/sources.list</filename> and
386              <filename>/etc/apt/sources.list.d/*</filename>.
387              </para>
388            </listitem>
389          </varlistentry>
390          <varlistentry>
391            <term>
392              <option>--clean-lists</option>
393            </term>
394            <listitem>
395              <para>Force the user-specific <command>apt-cross</command> package
396              list files to be updated. <command>apt-cross</command> turns off the normal
397              apt default of cleaning up the package lists automatically because
398              apt has a habit of removing the package lists for non-native
399              architectures during the automated clean.
400              </para>
401              <para>This makes it impossible to maintain two sets of package lists
402              from different architectures, requiring a complete update every time
403              the cache switches architecture.</para>
404              <para>Turning the option off, however, can lead to clutter and
405              confusing errors from libcache-apt-perl so this command removes all
406              package list files from the apt-cross directory for the specified
407              or default suite, then runs force_update.
408              </para>
409            </listitem>
410          </varlistentry>
411          <varlistentry>
412            <term><option>-c</option>|<option>--check</option></term>
413            <listitem>
414              <para>Check if the user-specific <command>apt-cross</command> cache
415              needs to be updated and update if necessary.
416              </para>
417            </listitem>
418          </varlistentry>
419        </variablelist>
420      </refsect1>
421      <refsect1 id="options">
422        <title>OPTIONS</title>
423        <variablelist remap="TP">
424          <varlistentry>
425            <term><option>-a</option>|<option>--arch</option> ARCH</term>
426            <listitem>
427              <para>set architecture (default: defined in
428              the <filename>~/.dpkg-cross/cross-compile</filename>
429              configuration file or by the dpkg-cross debconf configuration.)</para>
430            </listitem>
431          </varlistentry>
432          <varlistentry>
433            <term><option>-S</option>|<option>--suite</option> SUITE</term>
434            <listitem>
435              <para>set the Debian suite (stable, testing, unstable [default])</para>
436            </listitem>
437          </varlistentry>
438          <varlistentry>
439            <term><option>-m</option>|<option>--mirror</option> MIRROR</term>
440            <listitem>
441              <para>set the Debian mirror to use to retrieve packages
442              (default: first usable apt source.)</para>
443            </listitem>
444          </varlistentry>
445          <varlistentry>
446            <term><option>-x</option>|<option>--exclude</option></term>
447            <listitem>
448              <para>As from <command>apt-cross</command> v0.1.2,
449              architecture-independent dependencies are <emphasis role="bold">NOT</emphasis>
450              processed. <command>apt-cross</command> also passes options to
451              <command>dpkg-cross</command> to ensure that the cross package omits the
452              same dependencies.
453              If there are additional packages that need to be omitted, this option allows
454              individual packages (e.g. perl-base) to be added to the list.
455              </para>
456              <para>The option is typically used to drop dependencies on packages that are
457              not required within a cross-build environment, e.g. packages containing only
458              executables or architecture independent files.
459              </para>
460            </listitem>
461          </varlistentry>
462          <varlistentry>
463            <term><option>-n</option>|<option>--simulate</option></term>
464            <listitem>
465              <para><emphasis role="bold">Requires -i</emphasis>. Halts the install
466            operation at the point where the dependencies have been calculated
467            and <command>apt-cross</command> prints a summary message indicating
468            how many packages need to be installed as new and how many as upgrades.
469            </para>
470            </listitem>
471          </varlistentry>
472          <varlistentry>
473            <term><option>-k</option>|<option>--keep-temp</option></term>
474            <listitem>
475              <para><emphasis role="bold">Requires -i</emphasis>. Retains the
476              .deb archives downloaded for conversion by <command>dpkg-cross</command>
477              for use in later builds. Normally, these foreign architecture .deb archives
478              are removed after a successful installation. This option is provided
479              mainly for use in a chroot or other situation where the archives need
480              to be copied into the local cache. <command>apt-cross</command> will
481              check <filename>/var/cache/apt/archives/</filename> before trying to
482              download another copy so a chroot process can copy the archives into
483              the chroot apt cache to prevent repeat downloads. Note that
484              <command>apt-cross</command> downloads the archives into the current
485              working directory; if this is a package source directory, consider
486              changing to a temporary directory before starting <command>apt-cross</command>
487              <option>--keep-temp</option> <option>--install</option> <userinput>foo</userinput>
488              or arrange for the chroot process to move the files into the local
489              apt cache before starting the build. (<command>empdebuild</command>
490              from <emphasis>emdebian-tools</emphasis> does this for you.)
491              </para>
492            </listitem>
493          </varlistentry>
494          <varlistentry>
495            <term><option>-f</option>|<option>--force</option></term>
496            <listitem>
497              <para><command>apt-cross</command> will normally skip downloads
498              and rebuilds of cross packages already installed at the latest
499              available version. Use <option>--force</option> to override this
500              behaviour. In <option>--get</option> mode, <option>--force</option>
501              simply downloads another version of the ARCH package. In
502              <option>--build</option> mode, <option>--force</option> downloads
503              a fresh ARCH package and rebuilds the cross version, overwriting
504              a cross package in the same directory.
505              </para>
506            </listitem>
507          </varlistentry>
508          <varlistentry>
509            <term><option>-v</option>|<option>--verbose</option></term>
510            <listitem>
511              <para>be verbose - repeat once for extra verbosity.
512              Repeat twice to see comprehensive debug information.</para>
513            </listitem>
514          </varlistentry>
515          <varlistentry>
516            <term><option>-q</option>|<option>--quiet</option></term>
517            <listitem>
518              <para>be quiet. (default)</para>
519            </listitem>
520          </varlistentry>
521          <varlistentry>
522            <term><option>-?</option>|<option>-h</option>|<option>--help</option>|<option>--version</option></term>
523            <listitem>
524              <para>Print usage and version information and exit.</para>
525            </listitem>
526          </varlistentry>
527        </variablelist>
528      </refsect1>
529      <refsect1 id="chroot">
530        <title>USE IN A CHROOT</title>
531        <para>It is common for a chroot to not provide a Sources URL for apt. This causes
532        problems for <command>apt-cross</command> and when preparing a chroot to
533        use <command>apt-cross</command> a <command>deb-src</command> line will need
534        to be added to whichever sources.list the chroot can use.
535        </para>
536      </refsect1>
537      <refsect1 id="bugs">
538        <title>BUGS</title>
539        <para><command>apt-cross</command> supports various levels of verbose output
540      and <option>-v</option> can be useful in identifying problems. When preparing
541      bug reports, it is often useful to use the debug level of verbose output
542      using <option>-v -v -v</option> and redirecting the output to a file.
543      </para>
544      </refsect1>
545      <refsect1 id="future">
546        <title>Future</title>
547        <para><command>apt-cross</command> has
548      a <emphasis role="bold">very</emphasis> limited future. It is a tool
549      for a particular stage in the process of making Debian cross-building
550      friendly and as such it serves as a means to an end.</para>
551        <para>As more <command>dpkg-cross</command> code migrates into
552        <filename>dpkg-dev</filename>, <command>apt-cross</command> will
553      become less important. Simultaneously, making <command>apt</command> cross-build
554      friendly will become easier. The ultimate aim is therefore to aim for
555      <command>apt</command> to replace <command>apt-cross</command>
556      in a coordinated migration with <command>dpkg-cross</command> and
557      <command>dpkg</command>.
558      </para>
559        <para>Eventually, when the core <command>dpkg-cross</command> functionality
560        is merged into <command>dpkg</command>, <command>apt-cross</command> will
561        be removed from Debian and the relevant versions of <command>dpkg</command>
562        and <command>apt</command> will Replace: and Conflict: with
563        <command>dpkg-cross</command> and <command>apt-cross</command>
564        respectively.</para>
565        <para>Anyone looking at the apt-cross source code needs to be aware that
566      any improvements will only have a limited lifespan.
567      </para>
568      </refsect1>
569      <refsect1 id="files">
570        <title>FILES</title>
571        <variablelist remap="TP">
572          <varlistentry>
573            <term>
574              <filename>~/.apt-cross/</filename>
575            </term>
576            <listitem>
577              <para>Collection of directories and cache files for each suite (unstable, testing,
578              stable etc.).</para>
579            </listitem>
580          </varlistentry>
581          <varlistentry>
582            <term>
583              <filename>~/.apt-cross/sources.*</filename>
584            </term>
585            <listitem>
586              <para>Sources list for each suite.</para>
587            </listitem>
588          </varlistentry>
589        </variablelist>
590      </refsect1>
591      <refsect1 id="seealso">
592        <title>SEE ALSO</title>
593        <para><filename>dpkg-cross</filename> (1), <filename>emdebian-tools</filename> (1)
594         and <ulink url="http://www.emdebian.org/">http://www.emdebian.org/</ulink>.
595         </para>
596      </refsect1>
597      <refsect1 id="author">
598        <title>AUTHOR</title>
599        <para><emphasis remap="I">apt-cross</emphasis>
600        was written by Neil Williams &lt;codehelp@debian.org&gt;.
601        </para>
602        <para>This manual page was written by
603        Neil Williams &lt;codehelp@debian.org&gt;</para>
604      </refsect1>
605      <refsect1 id="copyright">
606        <title>COPYRIGHT</title>
607        <para>This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.</para>
608        <para>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.</para>
609        <para>You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</para>
610      </refsect1>
611    </refentry>
612  </chapter>
613</book>
Note: See TracBrowser for help on using the browser.