diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 173 |
1 files changed, 0 insertions, 173 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index 23ae44d..0000000 --- a/README.md +++ /dev/null @@ -1,173 +0,0 @@ -adeb --------- - -**adeb** (also known as **androdeb**) 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 -adeb. - -Usecases --------- -1. Powerful development environment with all tools ready to go (editors, -compilers, tracers, perl/python etc) for your on-device development. - -2. 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. - -3. 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 -adeb](https://github.com/joelagnel/adeb/blob/master/BCC.md) for more -information on that. - -4. 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 adeb, we can build perf natively -on device without having to cripple it. - -Requirements for running ------------------------- -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](https://github.com/joelagnel/adeb/blob/master/README.md#how-to-use-adeb-for-other-architectures-other-than-arm64) 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. - -Quick Start Instructions ------------------------- -* First clone this repository into adb and cd into it. -``` -cd adeb - -# Add some short cuts: -sudo ln -s $(pwd)/adeb /usr/bin/adeb - -# Cached image downloads result in a huge speed-up. These are automatic if you -# cloned the repository using git. However, if you downloaded the repository -# as a zip file (or you want to host images elsewere), you could set the -# ADEB_REPO_URL environment variable in your bashrc file. -# Disclaimer: Google is not liable for the below URL and this -# is just an example. -export ADEB_REPO_URL="github.com/joelagnel/adeb/" -``` - -* Installing adeb onto your device: -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 -``` - -* Now run adeb shell to enter your new environment!: -``` -adeb shell -``` - -* Once done, hit `CTRL + D` and you will exit out of the shell. -To remove adeb from the device, run: -``` -adeb remove -``` -If you have multiple devices connected, please add `-s <serialnumber>`. -Serial numbers of all devices connected can be obtained by `adb devices`. - -* To update an existing adeb clone on your host, run: -``` -adeb git-pull -``` - -More advanced usage instructions --------------------------------- -### Install kernel headers in addition to preparing adeb device: -``` -adeb prepare --kernelsrc /path/to/kernel-source -``` - -### Update kernel headers onto an already prepared device: - -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). - -### Build and prepare device with a custom rootfs locally: - -The adeb fs will be prepared locally by downloading packages as needed: -``` -adeb prepare --build -``` -This is unlike the default behavior, where the adeb 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 -``` - -### Add kernel headers to device in addition to building locally: -``` -adeb prepare --build --kernelsrc /path/to/kernel-source/ -``` - -### Build/install a base image with BCC: -``` -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. - -### Extract the FS from the device, after its prepared: -``` -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/adeb-fs.tgz`. This -can be used later. - -### Use a previously prepared adeb rootfs tar from local: -``` -adeb prepare --archive /path/adeb-fs.tgz -``` - -### Build a standalone raw EXT4 image out of the FS: -``` -adeb prepare --build-image /path/to/image.img -``` -This can then be passed to Qemu as -hda. Note: This option doesn't need a -device connected. - -### How to use adeb for other Architectures (other than ARM64) -By default adeb 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. - -Common Trouble shooting ------------------ -1. Installing g++ with `apt-get install g++` fails. - -Solution: Run `adeb shell apt-get update` after the `adeb prepare` stage. - -2. It's too slow to use debootstrap to create debian fs - -Solution: Use a local mirror, for example in China you could use -https://mirror.tuna.tsinghua.edu.cn/debian/ instead of debian official website -http://deb.debian.org/debian/ |