[
  {
    "path": "README.md",
    "content": "# Android Tools\n\nThis repository contains public guides and scripts tailored for custom Android Development. The scripts have comments throughout\nthem telling you what you need to edit but you are required to have functional knowledge of terminal.\n\n## Contents:\n\n- [AOSP Building Guide](guides/building_aosp.txt)\n- [Bug Reporting](guides/proper_bug_reporting.txt)\n"
  },
  {
    "path": "guides/building_aosp.txt",
    "content": "###########################\n#                         #\n#   MAY 31, 2021 UPDATE   #\n#                         #\n###########################\n\nThis guide is no longer being actively maintained or updated, as I have not\nbuilt an Android ROM since 2017 or even used an Android device as my daily\ndriver since 2019. I am leaving it up as it has been useful for many but you\nmight want to check out some more updated guides, such as those below:\n\nhttps://source.android.com/setup/build/building\nhttps://wiki.archlinux.org/title/Android#Building\nhttps://wiki.lineageos.org/build_guides.html\n\n\n####################################\n#                                  #\n#   BUILDING ANDROID FROM SOURCE   #\n#                                  #\n####################################\n\nIn this guide, I will go over how to build Android on your Linux machine.\nThis particular tutorial will focus on Ubuntu flavors but this should work with\nany version of Linux; I include a reference for Arch users that is already done.\nYour version MUST be 64-bit however. I will leave the installation of that up\nto you, Google is a wonderful resource. If you don't have a good computer but\nstill want to build, check out this thread on XDA:\nhttp://forum.xda-developers.com/chef-central/android/guide-how-to-build-rom-google-cloud-t3360430\n\nFormatting!!!\nIf something has a $ in front of it, that is a command you need to run in your\nterminal window. Don't include the $ or the space that follows it.\n\n\n#######################################\n#  Step One: set up your environment  #\n#######################################\n\nYou have two options here, the lazy way or the non-lazy way.\n\nAutomatic way (recommended!):\n-- Grab a repo with some useful scripts, and run the needed one\n$ sudo apt-get install git-core\n$ git clone https://github.com/akhilnarang/scripts\n$ cd scripts\n$ ls\n$ bash setup/<script-name>\n\nRun the script corresponding to your Linux Distribution:\narch-manjaro.sh - Arch based distros\nandroid_build_env.sh - Ubuntu 14, Ubuntu 16, Ubuntu 18, Mint 19\n\nManual way:\n-- Grab Java 8:\n$ sudo apt-get update\n$ sudo apt-get install openjdk-8-jdk\n$ sudo apt-get install openjdk-8-jre\n\n-- Install build tools\n$ sudo apt-get install bc bison build-essential ccache curl flex \\\ng++-multilib gcc-multilib git-core gnupg gperf imagemagick lib32ncurses5-dev \\\nlib32z-dev libc6-dev-i386 libgl1-mesa-dev libssl-dev libx11-dev \\\nlibxml2-utils unzip x11proto-core-dev xsltproc zip zlib1g-dev\n\nNOTE: Arch Linux users, use the Arch wiki page to install your packages then\ncome back here: https://wiki.archlinux.org/index.php/Android#Building_Android\n\n\n######################################\n#  Step Two: Configure Repo and Git  #\n######################################\n\nNOTE: If you have any problems with the below commands, try running as root:\n$ sudo -s\n\nGit is an open source version control system which is incredibly robust for\ntracking changes across repositories. Repo is Google's tool for working with Git\nin the context of Android. More reading if you are interested:\nhttps://source.android.com/source/developing.html\n\nRun these commands to get repo all working (only needed if you did the manual\nmethod of setup above):\n$ curl https://storage.googleapis.com/git-repo-downloads/repo > repo\n$ chmod a+x repo\n$ sudo install repo /usr/local/bin\n$ rm repo\n\nThen run these commands to get git all working:\n$ git config --global user.name \"Your Name\"\n$ git config --global user.email \"you@example.com\"\n\n\n#####################################\n#  Step Three: Download the source  #\n#####################################\n\nFirst, create a folder for your source:\n$ mkdir ~/<foldername> (eg. mkdir ~/DU or ~/PN-Layers)\n$ cd ~/<foldername>\n\nWhen you go to build a ROM, you must download its source. All, if not most,\nROMs will have their source code available on Github. To properly download the\nsource, follow these steps:\n-- Go to your ROM's Github (e.g. http://github.com/DirtyUnicorns)\n-- Search for a manifest (usually called manifest or android_manifest).\n-- Go into the repo and make sure you are in the right branch (located right\n   under the Commits tab).\n-- Go into the README and search for a repo init command. If one exists, copy\n   and paste it into the terminal and hit enter.\n-- If one does not exist, you can make one with this formula:\n   repo init -u <url_of_manifest_repo>.git -b <branch_you_want_to_build>.\n   For example:\n      $ repo init -u https://github.com/DirtyUnicorns/android_manifest.git -b o8x\n-- After the repo has been initialized, run this command to download the source:\n   $ repo sync --force-sync -j$( nproc --all )\n-- This process can take a while depending on your internet connection.\n\n\n##########################\n#  Step Four: Build it!  #\n##########################\n\nHere's the moment of truth... time to build the ROM! This process could take\n15 minutes to many hours depending on the speed of your PC but assuming that\nyou have followed the instructions so far, it should be smooth sailing.\n\nBefore you compile, you may also consider setting up ccache if you can spare\nabout 50GB. If not, skip this section. ccache is a compiler cache, which keeps\npreviously compiled code stored so it can be easily reused. This speeds up\nbuild times DRASTICALLY.\n\nOpen your bashrc or equivalent:\n$ nano ~/.bashrc\n- Append export USE_CCACHE=1 to the end of this file\n   then hit ctrl-X, Y, and enter.\n$ source ~/.bashrc\n\nAfter that, run this command if you used the manual method of setup above\n$ prebuilts/misc/linux-x86/ccache/ccache -M 50G (or however much you want).\nRun this command if you used the automatic method of setup above\n$ ccache -M 50G\n\nSince Android 10, the way of using ccache has changed:\n$ export USE_CCACHE=1\n$ export CCACHE_EXEC=$(command -v ccache)\n\nAfter this, load up the compilation commands:\n$ . build/envsetup.sh\n\nThen, tell it which device you want to make and let it roll:\n$ breakfast <device> OR lunch\n$ mka bacon\n\nNOTE: Some ROMs may use their own bacon command, read their manifest as they\nwill usually outline this.\nOthers may not use mka, use make -j$( nproc --all )\n\n\nIf you get an error here, make sure that you have downloaded all of the\nproper vendor files from your ROM's repository.\n\nOnce you tell it mka bacon, the computer will start building. You\nwill know that it is done when you see a message saying make completed and\ntelling you where your flashable zip is located.\n\nWhenever you build again, make sure you run a clean build every time by placing\nthis command in between the other two:\n$ make clobber\n\nThat's it! You successfully compiled a ROM from scratch :) By doing this, you\ncontrol when you get the new features, which means as soon as they are available\non Github. After this, you may even want to start contributing, one of the\ngreatest things about Android and open source software in general.\n\n\n#################\n#  Jack issues  #\n#################\n\nFor those of you who are having jack issues (like saying you ran out of memory),\nfollow these steps.\n\nType this into your terminal, substituting the # with how many GBs of RAM\nyou have:\n$ export JACK_SERVER_VM_ARGUMENTS=\"-Dfile.encoding=UTF-8 -XX:+TieredCompilation -Xmx#g\"\n\nThen go into the root of the source folder and type the following:\n$ ./prebuilts/sdk/tools/jack-admin kill-server\n$ ./prebuilts/sdk/tools/jack-admin start-server\n\nThis will restart the jack server to reflect your new heap limit.\n\n\n#############\n#  Support  #\n#############\n\nIf you run into any issues while building, you can use the following chat room for assistance\n(be sure to read the rules): https://t.me/AndroidBuildersHelp\nThis chat is only for build errors or to get the build to compile.\n\nAfter you have successfully built the ROM, for any required assistance, use this chat\n https://t.me/AndroidBringup\n\n####################\n#  Special thanks  #\n####################\n\n@Mazda-- for spearheading the Dirty Unicorns project, his dedication to\nopen source, and helping me out at random points during compilation.\n\n@BeansTown106 for the various advice and guidance he has provided plus\nhis contributions to the open source community through the Pure Nexus Project.\n\n@akhilnarang for his build environment scripts.\n\n@npjohnson for the Ubuntu 16.04 Java 7 instructions.\n"
  },
  {
    "path": "guides/proper_bug_reporting.txt",
    "content": "\n###############################\n#                             #\n#  PROPER AOSP BUG REPORTING  #\n#                             #\n###############################\n\nMany times when using a custom ROM or kernel, you may experience an issue. The\ndeveloper may want something called a logcat or dmesg to look into this but you\nmay not know how to do that. There are a couple of ways to do so and that is\nwhat I am going to explain now. This is valid for themers, ROM developers, and\nkernel developers.\n\nA logcat is useful for debugging crashes or other weird behaviors with apps or\nthemes. A radio logcat details what's going on in the phone's actual phone\nfunctionality. It tells you any errors that occured while trying to call.\nA dmesg is a kernel log, detailing what each subsystem is doing.\nA ramoops is the previous dmesg, which will detail why a phone force restarted.\nA ramoops is also known as last-kmsg or pstore, and can be retrieved from a\ncustom recovery as well as from a booted device.\n\n\n###################\n# 1. USING AN APP #\n###################\n\n1. Getting a logcat:\n    a. Download a logcat app from the Play Store (I will be using Matlog for\n       the rest of this tutorial).\n    b. Open the app and grant it root permissions (if you are not rooted and\n       do not want to be, you will need to use ADB below).\n    c. Clear the buffer but clicking the three dot menu and hitting clear.\n    d. Click on the three dot menu, choose Settings, then Log Buffer(s). \n    e. Tick either radio, main or both depending on the type of bug.\n    f. Click on the three dot menu, choose File, then Record.\n    g. Duplicate your crash/issue.\n    h. Go back into Matlog and hit the stop button in the lower righthand corner.\n    i. Send the generated file to your developer/themer following the etiquette\n       below.\n\n2. Getting a dmesg:\n    a. Either download a dmesg app and follow similar steps as above OR download\n       a terminal emulator and continue on.\n    b. Open your terminal emulator and type su to enter as the root user.\n    c. Type dmesg > /sdcard/test.log\n    d. Send the generated file (located in the head folder of your internal\n       storage partition) to your developer, following the etiquette below.\n\n3(a). Getting a ramoops via system:\n    a. Open a file manager and navigate to /sys/fs/pstore and copy the file\n       named console-ramoops or console-ramoops1 to your sdcard folder.\n    b. Send that file to your kernel developer following the etiquette below.\n3(b). Getting a ramoops via recovery:\n    a. Ensure your device has TWRP installed from fastboot, search XDA for help\n    b. Immediately after the device reboots, force it to recovery by holding\n       volume buttons.\n    c. Click [Advanced] and then [File Manager]. Navigate to /sys/fs/pstore\n       and copy the file named console-ramoops or console-ramoops1 to /sdcard.\n       Send that file to your kernel developer or whoever caused the bug\n       following the etiquette below\n\n\n################\n# 2. USING ADB #\n################\n\n1.  Download the latest tools from Google:\n    https://dl.google.com/android/repository/platform-tools-latest-linux.zip\n    https://dl.google.com/android/repository/platform-tools-latest-darwin.zip\n    https://dl.google.com/android/repository/platform-tools-latest-windows.zip\n\n2.  Extract those to a folder and move into that folder:\n    $ cd <folder_location>\n\n3.  Plug in your device and accept the debugging prompt (turn on ADB in\n    Settings > Developer Options if you don't see it).\n\n4.  Verify your device is recognized.\n    $ adb devices or $ ./adb devices\n\n5.  Clear the logcat buffer.\n    $ adb logcat -c or $ ./adb logcat -c\n\n6.  Take your log:\n    Logcat: $ adb logcat -d > test.log or $ ./adb logcat -d > test.log\n    dmesg: $ adb shell dmesg > test.log or $ ./adb shell dmesg > test.log\n\n7.  Give that log to the appropriate party with a proper report, following the\n    etiquette below.\n\n\n##################################\n# PROPER BUG REPORTING ETIQUETTE #\n##################################\n\n1.  First and foremost, understand that for the vast majority of people, this is\n    a hobby, not a job. It may take some time for your issue to be resolved.\n    Being a jerk or bossy is likely to get you banned or at the least have your\n    issue dismissed.\n\n2.  Write in clear, concise manner what the issue is with steps to reproduce\n\n    Bad: My phone is broken, help!\n    Good: Whenever I open YouTube after a clean flash, it force closes.\n\n3.  Explain what you have done. A developer should not have to ask what has\n    already been attempted.\n\n4.  Provide any scenarios/ROMs where it did work (was it working in a previous\n    update, etc.)\n\n5.  If you are technically inclined, provide commits that are either the issue\n    or will resolve the issue. Developers love having a solution presented for\n    them.\n"
  },
  {
    "path": "scripts/bldgcc",
    "content": "#!/usr/bin/env bash\n# SPDX-License-Identifier: MIT\n#\n# Copyright (C) 2021 Nathan Chancellor\n#\n# The shebang is just for shellcheck auditing; this script needs to be sourced and\n# called by the function name otherwise it literally does nothing. It works in\n# bash and zsh.\n#\n# Builds GCC and binutils for exclusively building kernels\n#\n# This can be downloaded and sourced without any of the other scripts in this repo.\n#\n# $ curl -LSsO https://github.com/nathanchance/android-tools/raw/main/scripts/bldgcc\n#\n# Open the bldgcc file to make sure it matches this one.\n#\n# $ source bldgcc\n#\n# Usage:\n# $ bldgcc arm arm64\n#\n# By default, the script will contain everything to a 'gcc' folder in ${PWD}.\n# To change where that gcc folder is, either 'export GCC_TC_FOLDER=<value>' or\n# 'GCC_TC_FOLDER=<value> bldgcc'.\n#\n# By default, the GCC and binutils versions will be the latest available.\n# To change the versions, either 'export GCC_VERSION=<value> BINUTILS_VERSION=<value>'\n# or 'GCC_VERSION=<value> BINUTILS_VERSION=<value> bldgcc'.\n#\n# The possible versions can be found here:\n# https://mirrors.kernel.org/gnu/gcc/\n# https://mirrors.kernel.org/gnu/binutils/\n#\n# This script is designed to build release versions of this software, not development\n# versions. If you want to do that, it's not hard to modify this script to do that or\n# use https://github.com/USBhost/build-tools-gcc\nfunction bldgcc() { (\n    BLD_OPTS=(--toolchain)\n    TARGETS=()\n\n    # Get parameters\n    [[ ${#} -eq 0 ]] && {\n        echo \"ERROR: This function needs targets!\" >&2\n        echo \"Some of the possible options (can provide more than one):\" >&2\n        echo \"      arm, arm64, m68k, mips, mipsel, powerpc, powerpc64, powerpc64le, riscv64, s390x, x86_64\" >&2\n        exit 1\n    }\n    while ((${#})); do\n        case ${1} in\n            --binutils | --gcc | --toolchain) BLD_OPTS=(\"${1}\") ;;\n            all) TARGETS=(arm arm64 m68k mips mipsel powerpc powerpc64 powerpc64le riscv64 s390x x86_64) ;;\n            *) TARGETS+=(\"${1}\") ;;\n        esac\n        shift\n    done\n\n    # Create folders\n    GCC_BLD=${GCC_TC_FOLDER:=${PWD}/gcc}/build\n    mkdir -p \"${GCC_TC_FOLDER}\"\n    [[ ! -d ${GCC_BLD} ]] && git -C \"${GCC_TC_FOLDER}\" clone https://github.com/nathanchance/buildall build\n    cd \"${GCC_BLD}\" || {\n        echo \"buildall clone failed!\" >&2\n        exit 1\n    }\n\n    # Download GCC\n    [[ -z ${GCC_VERSION} ]] && GCC_VERSION=11.2.0\n    GCC_SOURCE=gcc-${GCC_VERSION}\n    [[ ! -d ${GCC_SOURCE} ]] && curl -LSs https://mirrors.kernel.org/gnu/gcc/${GCC_SOURCE}/${GCC_SOURCE}.tar.xz | tar -xJf -\n\n    # Download binutils\n    [[ -z ${BINUTILS_VERSION} ]] && BINUTILS_VERSION=2.37\n    BINUTILS_SOURCE=binutils-${BINUTILS_VERSION}\n    [[ ! -d ${BINUTILS_SOURCE} ]] && curl -LSs https://mirrors.kernel.org/gnu/binutils/${BINUTILS_SOURCE}.tar.xz | tar -xJf -\n\n    # Create timert\n    [[ ! -f timert ]] && make -j\"$(nproc)\"\n\n    # Create config\n    cat <<EOF >config\nBINUTILS_SRC=${PWD}/${BINUTILS_SOURCE}\nCHECKING=release\nECHO=/bin/echo\nGCC_SRC=${PWD}/${GCC_SOURCE}\nMAKEOPTS=-j$(nproc)\nPREFIX=${PREFIX:-${GCC_TC_FOLDER}/${GCC_VERSION}}\nEOF\n\n    # Build the toolchains\n    for TARGET in \"${TARGETS[@]}\"; do\n        # Clean up previous artifacts, can cause a false failure\n        rm -rf \"${TARGET}\"\n        PATH=${PATH%%:\\/mnt\\/c\\/*} ./build \"${BLD_OPTS[@]}\" \"${TARGET}\"\n    done\n); }\n"
  },
  {
    "path": "scripts/haste",
    "content": "#!/usr/bin/env bash\n# SPDX-License-Identifier: MIT\n#\n# Copyright (C) 2021 Nathan Chancellor\n#\n# Function to upload to a haste-server (points to https://paste.myself5.de/ by default)\n#\n# This can be downloaded and sourced without any of the other scripts in this repo.\n#\n# $ curl -LSsO https://github.com/nathanchance/android-tools/raw/main/scripts/haste\n#\n# Open the haste file to make sure it matches this one.\n#\n# $ source haste\n#\n# Usage:\n# $ haste <file>\n# $ command |& haste\nfunction haste() { (\n    for BINARY in curl jq; do\n        command -v ${BINARY} &>/dev/null || {\n            echo \"ERROR: ${BINARY} is not installed\" >&2\n            exit 1\n        }\n    done\n    [[ -z ${HASTE_URL} ]] && HASTE_URL=https://paste.myself5.de\n    RESULT=$(curl -sf --data-binary @\"${1:--}\" \"${HASTE_URL}\"/documents) || {\n        echo \"ERROR: failed to post document, ca-certificates might need to be installed\" >&2\n        exit 1\n    }\n    echo \"${HASTE_URL}/raw/$(jq -r .key <<<\"${RESULT}\")\"\n); }\n"
  }
]