|author||Joel Fernandes <firstname.lastname@example.org>||Wed Jul 11 20:56:39 2018 -0700|
|committer||Joel Fernandes <email@example.com>||Wed Jul 11 20:56:39 2018 -0700|
update README Signed-off-by: Joel Fernandes <firstname.lastname@example.org>
androdeb (also known as adeb) provides a powerful Linux shell environment where one can run popular and mainstream Linux tracing, compiling, editing and other development tools on an existing Android device. All the commands typically available on a modern Linux system are supported in androdeb.
Powerful development environment with all tools ready to go (editors, compilers, tracers, perl/python etc) for your on-device development.
No more cross-compiler needed: Because it comes with gcc and clang, one can build target packages natively without needing to do any cross compilation. We even ship git, and have support to run apt-get to get any missing development packages from the web.
Using these one can run popular tools such as BCC that are difficult to run in an Android environment due to lack of packages, dependencies and cross-compilation needed for their operation. Check BCC on Android using androdeb for more information on that.
No more crippled tools: Its often a theme to build a static binary with features disabled, because you couldn‘t cross-compile the feature’s dependencies. One classic example is perf. However, thanks to androdeb, we can build perf natively on device without having to cripple it.
Target: An ARM64 android N or later device which has “adb root” supported. Typically this is a build in a userdebug configuration. Device should have atleast 2 GB free space in the data partition. If you would like to use other architectures, see the Other Architectures section.
Host: A machine running recent Ubuntu or Debian, with 4GB of memory and 4GB free space. Host needs debootstrap and qemu-debootstrap packages. To install it, run
sudo apt-get install qemu-user-static debootstrap. Other distributions may work but they are not tested.
git clone https://github.com/joelagnel/androdeb.git cd androdeb # Add some short cuts: sudo ln -s $(pwd)/adeb /usr/bin/adeb sudo ln -s $(pwd)/androdeb /usr/bin/androdeb
# First make sure device is connected to system # Then run, for the base image: adeb prepare
The previous command only downloads and installs the base image. Instead if you want to download and install the full image, do:
adeb prepare --full
CTRL + Dand you will exit out of the shell. To remove androdeb from the device, run:
If you have multiple devices connected, please add
-s <serialnumber>. Serial numbers of all devices connected can be obtained by
To update an existing androdeb clone on your host, run:
adeb prepare --kernelsrc /path/to/kernel-source
If you need to put kernel sources for an existing install, run:
adeb prepare --kernelsrc /path/to/kernel-source --skip-install
Note: The kernel sources should have been built (atleast build should have started).
The androdeb fs will be prepared locally by downloading packages as needed:
adeb prepare --build
This is unlike the default behavior, where the androdeb rootfs is itself pulled from the web.
If you wish to do a full build (that is locally prepare a rootfs with all packages, including bcc, then do):
adeb prepare --full --build
adeb prepare --build --kernelsrc /path/to/kernel-source/
adeb prepare --build --bcc --kernelsrc /path/to/kernel-source/
Note: BCC is built from source. Also
--kernelsrc is recommended for tools to function unless device has them already.
adeb prepare --buildtar /path/
After device is prepared, it will extract the root fs from it and store it as a tar archive at
/path/androdeb-fs.tgz. This can be used later.
adeb prepare --archive /path/androdeb-fs.tgz
adeb prepare --buildimage /path/to/image.img
This can then be passed to Qemu as -hda. Note: This option doesn't need a device connected.
By default androdeb assumes the target Android device is based on ARM64 processor architecture. For other architectures, use the --arch option. For example for x86_64 architecture, run:
adeb prepare --build --arch amd64 --bcc --kernelsrc /path/to/kernel-source/
Note: The --download option ignores the --arch flag. This is because we only provide pre-built filesystems for ARM64 at the moment.