NAME
apt-cross - apt support for cross compiling libraries
SYNOPSIS
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] [[-f] | [--force]] [{-g|--get} PACKAGE
...]
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] [[-f] | [--force]] [[-x] | [--exclude]
PACKAGE] {-b|--build} PACKAGE ...
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] [[-x] | [--exclude] PACKAGE] [[-k] |
[--keep-temp]] [[-n] | [--simulate]] {-i|--install} PACKAGE
...
apt-cross [[-a] | [--arch] ARCH] {--remove|--purge|-r} PACKAGE ...
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] {-s|--show} PACKAGE ...
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] {-l|--list}
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] {-u|--update}
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] {--clean-lists}
apt-cross [[-a] | [--arch] ARCH] [[-S] | [--suite] SUITE] [[-m] |
[--mirror] MIRROR] {-c|--check}
apt-cross [[-?] | [-h] | [--help] | [--version]]
DESCRIPTION
apt-cross provides apt functionality for getting, building and
installing libraries and header files for cross-compiling using
dpkg-cross. apt-cross -i will search for and download missing
dependencies of the requested package before building and installing
the requested package and dependencies using dpkg-cross and dpkg -i
(sudo required).
apt-cross is intended to make it easier to locate, download, install
and update cross-built libraries, directly from the Debian archives.
apt-cross is not intended to handle applications or Architecture: all
packages like foo-common or libfoo-common. apt-cross can download the
cross-compiling version of those packages but does not build or install
them - this can be done with dpkg-cross -A and dpkg -i if necessary.
Note that not all such packages can be installed in that way.
Architecture-independent packages do not need to be converted, so
apt-cross omits all such packages from the dependency calculations and
ensures that dpkg-cross also drops these packages from the dependencies
of the generated package. One exception is that apt-cross will process
development packages (-dev) that are Architecture: all.
By default, apt-cross uses /etc/apt/sources.list and
/etc/apt/sources.list.d/* to find the latest debian package file for
the architecture specified (default is the dpkg-cross default) and in
the suite specified (default is unstable). Alternatively, specify a
different mirror. Downloaded files can be passed directly to dpkg-cross
using the -b or -i commands to apt-cross. If the local file is missing
or out of date, a new one will be downloaded automatically.
If the apt-cross cache for the specified suite and architecture is
older than 24hours, it will be updated automatically. If the cache
needs to be updated more frequently or if the cache becomes corrupted,
use -u|--update.
APT-CROSS AND CROSS-COMPILERS
apt-cross does have limitations and cannot replicate all behaviour
associated with apt itself. In particular, apt-cross cannot provide,
build, install or download a cross-compiler. Certain parts of the
process to build a cross-compiling toolchain do require apt-cross but
you must obtain a suitable set of packages from somewhere else or build
the toolchain yourself. See the emdebian-tools package for assistance
with cross-compilers and cross-building toolchains.
COMMANDS
--g|--get <packages...>
Retrieve the architecture-specific package(s) from the Debian
mirrors into the current directory. If the package has already been
downloaded, apt-cross will skip the download unless --force is
used.
--b|--build <packages...>
Retrieve the architecture-specific package(s) from the Debian
mirrors into the current directory and pass to dpkg-cross to build
a cross-built version.
'Architecture: all' dependencies of the requested package are added
to the list of dependencies to be excluded from the cross package
using dpkg-cross -X.
--build will always replace any existing cross package file in the
same directory. Use --force only to ensure that apt-cross gets a
fresh package prior to conversion.
Dependencies of the requested package are not processed recursively
so the cross package may be uninstallable without other cross
packages, see --install for that functionality.
--i|--install <packages...>
Retrieve the architecture-specific package(s) from the Debian
mirrors into the current directory. Check for dependencies that are
suitable for dpkg-cross, download each dependency and build, then
install the package and dependencies using dpkg-cross and dpkg -i.
If successfully installed, the temporary downloaded archives are
removed. Requires working sudo setup and will prompt for the sudo
password if necessary (if sudo is not already cached).
-r|--remove|--purge <packages...>
Remove the cross-built package by calling dpkg. Requires working
sudo setup and will prompt for the sudo password if necessary (if
sudo is not already cached).
-s|--show <packages...>
Show the package information for the cross-built packages
specified. If the package name does not end in -$arch-cross, the
correct suffix will be added. The output format is the same as the
equivalent apt-cache show output and includes the dependencies of
the cross-built package. Note that only the details of cross-built
packages (in the repository or installed) are displayed.
-l|--list
List all cross-built package names. (Similar to apt-cache
pkgnames).
-u|--update
Force the user-specific apt-cross cache to be updated. Note that
all sources for this suite on the specified architecture will be
erased before the package cache is updated. If
/etc/apt/sources.list or /etc/apt/sources.list.d/* does not contain
a source for this suite, the updated cache for this suite will be
empty. Use -m|--mirror to specify a source to be added to whatever
sources are available for this suite in /etc/apt/sources.list and
/etc/apt/sources.list.d/*.
--clean-lists
Force the user-specific apt-cross package list files to be updated.
apt-cross turns off the normal apt default of cleaning up the
package lists automatically because apt has a habit of removing the
package lists for non-native architectures during the automated
clean.
This makes it impossible to maintain two sets of package lists from
different architectures, requiring a complete update every time the
cache switches architecture.
Turning the option off, however, can lead to clutter and confusing
errors from libcache-apt-perl so this command removes all package
list files from the apt-cross directory for the specified or
default suite, then runs force_update.
-c|--check
Check if the user-specific apt-cross cache needs to be updated and
update if necessary.
OPTIONS
-a|--arch ARCH
set architecture (default: defined in the
~/.dpkg-cross/cross-compile configuration file or by the dpkg-cross
debconf configuration.)
-S|--suite SUITE
Set the Debian suite (stable, testing, unstable [default]). Only
apt sources that already list this suite name in your apt sources
lists will be updated. The suite specified must already be in your
existing apt sources unless --mirror is also used (in which case
the specified mirror must support the requested suite or apt will
return errors).
-m|--mirror MIRROR
set the Debian mirror to use to retrieve packages instead of the
default of using your existing apt sources.
-x|--exclude
As from apt-cross v0.1.2, architecture-independent dependencies are
NOT processed. apt-cross also passes options to dpkg-cross to
ensure that the cross package omits the same dependencies. If there
are additional packages that need to be omitted, this option allows
individual packages (e.g. perl-base) to be added to the list.
The option is typically used to drop dependencies on packages that
are not required within a cross-build environment, e.g. packages
containing only executables or architecture independent files.
-n|--simulate
Requires -i. Halts the install operation at the point where the
dependencies have been calculated and apt-cross prints a summary
message indicating how many packages need to be installed as new
and how many as upgrades.
-k|--keep-temp
Requires -i. Retains the .deb archives downloaded for conversion by
dpkg-cross for use in later builds. Normally, these foreign
architecture .deb archives are removed after a successful
installation. This option is provided mainly for use in a chroot or
other situation where the archives need to be copied into the local
cache. apt-cross will check /var/cache/apt/archives/ before trying
to download another copy so a chroot process can copy the archives
into the chroot apt cache to prevent repeat downloads. Note that
apt-cross downloads the archives into the current working
directory; if this is a package source directory, consider changing
to a temporary directory before starting apt-cross --keep-temp
--install foo or arrange for the chroot process to move the files
into the local apt cache before starting the build. (empdebuild
from emdebian-tools does this for you.)
-f|--force
apt-cross will normally skip downloads and rebuilds of cross
packages already installed at the latest available version. Use
--force to override this behaviour. In --get mode, --force simply
downloads another version of the ARCH package. In --build mode,
--force downloads a fresh ARCH package and rebuilds the cross
version, overwriting a cross package in the same directory.
-v|--verbose
be verbose - repeat once for extra verbosity. Repeat twice to see
comprehensive debug information.
-q|--quiet
be quiet. (default)
-?|-h|--help|--version
Print usage and version information and exit.
USE IN A CHROOT
It is common for a chroot to not provide a Sources URL for apt. This
causes problems for apt-cross and when preparing a chroot to use
apt-cross a deb-src line will need to be added to whichever
sources.list the chroot can use.
BUGS
apt-cross supports various levels of verbose output and -v can be
useful in identifying problems. When preparing bug reports, it is often
useful to use the debug level of verbose output using -v -v -v and
redirecting the output to a file.
PROXIES
apt-cross uses apt for the majority of the downloads, then uses the LWP
perl module for the file download. Therefore, all proxy support needs
to be configured to support these tools - apt-cross does not interact
with any proxy (or any other network service) directly.
The precise configuration of any specific proxy is beyond the scope of
this manpage but it is important that the correct environment variable
is used for the type of apt source being used. If the apt source uses
the http:// prefix, the http_proxy variable must be set. (This is
case-sensitive.) If the apt source uses the ftp:// prefix, the
ftp_proxy environment variable must be set. (This is also
case-sensitive). It does not appear to matter which prefix is used for
the proxy itself.
FUTURE
apt-cross has a very limited future. It is a tool for a particular
stage in the process of making Debian cross-building friendly and as
such it serves as a means to an end.
As more dpkg-cross code migrates into dpkg-dev, apt-cross will become
less important. Simultaneously, making apt cross-build friendly will
become easier. The ultimate aim is therefore to aim for apt to replace
apt-cross in a coordinated migration with dpkg-cross and dpkg.
Eventually, when the core dpkg-cross functionality is merged into dpkg,
apt-cross will be removed from Debian and the relevant versions of dpkg
and apt will Replace: and Conflict: with dpkg-cross and apt-cross
respectively.
Anyone looking at the apt-cross source code needs to be aware that any
improvements will only have a limited lifespan.
FILES
~/.apt-cross/
Collection of directories and cache files for each suite (unstable,
testing, stable etc.).
~/.apt-cross/sources.*
Sources list for each suite.
SEE ALSO
dpkg-cross (1), emdebian-tools (1) and http://www.emdebian.org/.
AUTHOR
apt-cross was written by Neil Williams <codehelp@debian.org>.
This manual page was written by Neil Williams <codehelp@debian.org>
COPYRIGHT
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.
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.
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.