1 adeb 2 -------- 3 4 **adeb** (also known as **androdeb**) provides a powerful Linux shell 5 environment where one can run popular and mainstream Linux tracing, compiling, 6 editing and other development tools on an existing Android device. All the 7 commands typically available on a modern Linux system are supported in 8 adeb. 9 10 Usecases 11 -------- 12 1. Powerful development environment with all tools ready to go (editors, 13 compilers, tracers, perl/python etc) for your on-device development. 14 15 2. No more cross-compiler needed: Because it comes with gcc and clang, one can 16 build target packages natively without needing to do any cross compilation. We even 17 ship git, and have support to run apt-get to get any missing development packages 18 from the web. 19 20 3. Using these one can run popular tools such as BCC that are difficult to run 21 in an Android environment due to lack of packages, dependencies and 22 cross-compilation needed for their operation. [Check BCC on Android using 23 adeb](https://github.com/joelagnel/adeb/blob/master/BCC.md) for more 24 information on that. 25 26 4. No more crippled tools: Its often a theme to build a static binary with 27 features disabled, because you couldn't cross-compile the feature's dependencies. One 28 classic example is perf. However, thanks to adeb, we can build perf natively 29 on device without having to cripple it. 30 31 Requirements for running 32 ------------------------ 33 Target: 34 An ARM64 android N or later device which has "adb root" supported. Typically 35 this is a build in a userdebug configuration. Device should have atleast 2 GB 36 free space in the data partition. If you would like to use other architectures, 37 see the [Other Architectures](https://github.com/joelagnel/adeb/blob/master/README.md#how-to-use-adeb-for-other-architectures-other-than-arm64) section. 38 39 Host: 40 A machine running recent Ubuntu or Debian, with 4GB of memory and 4GB free space. 41 Host needs debootstrap and qemu-debootstrap packages. 42 To install it, run `sudo apt-get install qemu-user-static debootstrap`. 43 Other distributions may work but they are not tested. 44 45 Quick Start Instructions 46 ------------------------ 47 * First clone this repository into adb and cd into it. 48 ``` 49 cd adeb 50 51 # Add some short cuts: 52 sudo ln -s $(pwd)/adeb /usr/bin/adeb 53 54 # Cached image downloads result in a huge speed-up. These are automatic if you 55 # cloned the repository using git. However, if you downloaded the repository 56 # as a zip file (or you want to host images elsewere), you could set the 57 # ADEB_REPO_URL environment variable in your bashrc file. 58 # Disclaimer: Google is not liable for the below URL and this 59 # is just an example. 60 export ADEB_REPO_URL="github.com/joelagnel/adeb/" 61 ``` 62 63 * Installing adeb onto your device: 64 First make sure device is connected to system 65 Then run, for the base image: 66 ``` 67 adeb prepare 68 ``` 69 The previous command only downloads and installs the base image. 70 Instead if you want to download and install the full image, do: 71 ``` 72 adeb prepare --full 73 ``` 74 75 * Now run adeb shell to enter your new environment!: 76 ``` 77 adeb shell 78 ``` 79 80 * Once done, hit `CTRL + D` and you will exit out of the shell. 81 To remove adeb from the device, run: 82 ``` 83 adeb remove 84 ``` 85 If you have multiple devices connected, please add `-s <serialnumber>`. 86 Serial numbers of all devices connected can be obtained by `adb devices`. 87 88 * To update an existing adeb clone on your host, run: 89 ``` 90 adeb git-pull 91 ``` 92 93 More advanced usage instructions 94 -------------------------------- 95 ### Install kernel headers in addition to preparing adeb device: 96 ``` 97 adeb prepare --kernelsrc /path/to/kernel-source 98 ``` 99 100 ### Update kernel headers onto an already prepared device: 101 102 If you need to put kernel sources for an existing install, run: 103 ``` 104 adeb prepare --kernelsrc /path/to/kernel-source --skip-install 105 ``` 106 Note: The kernel sources should have been built (atleast build should have started). 107 108 ### Build and prepare device with a custom rootfs locally: 109 110 The adeb fs will be prepared locally by downloading packages as needed: 111 ``` 112 adeb prepare --build 113 ``` 114 This is unlike the default behavior, where the adeb rootfs is itself pulled from the web. 115 116 If you wish to do a full build (that is locally prepare a rootfs with all packages, including bcc, then do): 117 ``` 118 adeb prepare --full --build 119 ``` 120 121 ### Add kernel headers to device in addition to building locally: 122 ``` 123 adeb prepare --build --kernelsrc /path/to/kernel-source/ 124 ``` 125 126 ### Build/install a base image with BCC: 127 ``` 128 adeb prepare --build --bcc --kernelsrc /path/to/kernel-source/ 129 ``` 130 Note: BCC is built from source. Also `--kernelsrc` is recommended for tools to 131 function unless device has them already. 132 133 ### Extract the FS from the device, after its prepared: 134 ``` 135 adeb prepare --buildtar /path/ 136 ``` 137 After device is prepared, it will extract the root fs from it 138 and store it as a tar archive at `/path/adeb-fs.tgz`. This 139 can be used later. 140 141 ### Use a previously prepared adeb rootfs tar from local: 142 ``` 143 adeb prepare --archive /path/adeb-fs.tgz 144 ``` 145 146 ### Build a standalone raw EXT4 image out of the FS: 147 ``` 148 adeb prepare --build-image /path/to/image.img 149 ``` 150 This can then be passed to Qemu as -hda. Note: This option doesn't need a 151 device connected. 152 153 ### How to use adeb for other Architectures (other than ARM64) 154 By default adeb assumes the target Android device is based on ARM64 155 processor architecture. For other architectures, use the --arch option. For 156 example for x86_64 architecture, run: 157 ``` 158 adeb prepare --build --arch amd64 --bcc --kernelsrc /path/to/kernel-source/ 159 ``` 160 Note: The --download option ignores the --arch flag. This is because we only 161 provide pre-built filesystems for ARM64 at the moment. 162 163 Common Trouble shooting 164 ----------------- 165 1. Installing g++ with `apt-get install g++` fails. 166 167 Solution: Run `adeb shell apt-get update` after the `adeb prepare` stage. 168 169 2. It's too slow to use debootstrap to create debian fs 170 171 Solution: Use a local mirror, for example in China you could use 172 https://mirror.tuna.tsinghua.edu.cn/debian/ instead of debian official website 173 http://deb.debian.org/debian/ 174
