Prepare your workstation

This lesson gets you to a known starting point for later host-side commands. A workstation is the computer on which you type commands; it is not the Android device. You can read this book with only a phone or browser, but terminal, Git, compiler, and emulator exercises require a computer. No host packages are installed by this lesson or by the course automatically: you choose and install them yourself from official sources.

Before you start#

• What is Android? — the platform map and the distinction between reading and implementation evidence.

Learning goals#

You can name your command environment (Linux Bash, macOS shell, or Windows WSL Ubuntu), obtain Git and Android SDK Platform-Tools from official sources, optionally provision the reference Ubuntu host with C/C++, Python, search, and Java tools, make tools discoverable through PATH, and identify a version-check failure without trying random commands.

Choose a route and know its limits#

Reference route: Ubuntu 22.04 LTS, x86_64, Bash. Commands in the next lessons are written for this Linux environment unless a block says otherwise. This is a documented reference configuration, not a claim that the course authors installed or certified it on a host. Different package versions or shell configuration may change output.

• Linux: use a supported x86_64 Linux distribution. Ubuntu 22.04 is the reference. You need permission to install software or access to tools already installed. Do not run commands with administrator privileges unless you understand what they change.
• Windows: use Ubuntu under Windows Subsystem for Linux (WSL), not PowerShell, for the Bash examples. Install WSL/Ubuntu using Microsoft's official instructions. WSL is a Linux environment hosted by Windows; Windows and WSL have separate paths, installed tools, and environment configuration. Keep practice files in the WSL Linux home directory rather than mixing Windows-mounted paths into early exercises. Hardware virtualization and emulator support depend on Windows configuration; see Emulator setup before expecting a virtual device.
• macOS: the reading lessons work without a Mac, and many basic commands work in its Terminal with Bash/Zsh-like syntax. This course does not certify macOS compatibility: /tmp, tool locations, SDK downloads, permissions, and emulator behavior can differ. Follow official vendor installation instructions and stop if an example's assumptions do not match. Do not paste Linux package-manager commands into macOS.
• Phone/browser only: use source-only mode. Read lessons and inspect linked source in the browser; do not pretend a simulated command is a host or device observation. Return to hands-on work when you have a supported workstation.

A terminal is an application showing text input/output. A shell reads commands and starts programs. Bash is a shell; Ubuntu's terminal window is one way to interact with it. A prompt is the shell's invitation for input, not part of the command. Type only text inside a command block, press Enter once, and wait for the prompt to return before entering the next command. Output blocks show examples and must not be typed. If a command appears to be running, wait or use Ctrl+C only when you understand the command; Ctrl+C is not undo. On an error, stop and read it—do not add sudo as a guess.

In Bash, && means “run the next command only if the previous command succeeded.” For example, mkdir "$HOME/android-learning" && cd "$HOME/android-learning" creates a fixed folder and enters it only if creation succeeded. If that folder already exists, mkdir fails and cd does not happen; stop rather than reusing or overwriting its contents. Later, the terminal lesson uses mktemp -d to avoid fixed-name collisions. Do not use mkdir -p for that first practice directory: it succeeds when a directory already exists, so it cannot distinguish a fresh space from old work.

Install Git and Platform-Tools#

Git records local project history. Android SDK Platform-Tools includes adb, the workstation-side client used in a later lesson. Obtain Git from git-scm.com/downloads or your operating system's official package source. Obtain Platform-Tools from Android Developers. Avoid third-party “driver packs” and root bundles.

Optional tools for the Ubuntu reference host

The following is an explicit host system change, not a course action. Only use it on Ubuntu 22.04 (including its WSL Ubuntu environment), when you administer that installation and want the later native-code/search/Java exercises. sudo asks Ubuntu to run the command with administrator privileges; review the command before entering your password. Do not run it on macOS, native Windows, another Linux distribution, a managed computer without permission, or an Android device. If you lack permission or do not want packages installed, use tools already available or continue source-only; no lesson requires you to bypass that limit.

Ubuntu's APT package manager separates refreshing its local package index from installing packages. apt update downloads package metadata from configured repositories (Ubuntu APT manual); it does not install or upgrade the packages in the list below. The next command installs the named packages and required dependencies on the Ubuntu host. Review APT's proposed changes before confirming; it may show package names, download size, and a Do you want to continue? [Y/n] prompt. Enter Y (or press Enter when Y is the default) only if the proposal matches what you intended; enter n then Enter to cancel if uncertain. sudo may ask for your Ubuntu account password; terminal input is normally not echoed as dots or letters while typing. That is expected. If the host, package list, or change summary is unexpected, cancel. If repository/network errors occur, stop and check Ubuntu's official package-source/network guidance; do not add an unknown repository or paste a workaround from a forum.

Host — Ubuntu 22.04 Bash; optional system package installation:

sudo apt update
sudo apt install build-essential git python3 ripgrep openjdk-17-jdk

Package roles: build-essential provides the standard C/C++ build tools such as cc, c++, and make; git provides version control; python3 is the Python 3 interpreter; ripgrep provides the rg text-search command; openjdk-17-jdk provides Java 17 development tools (javac) and runtime (java). ripgrep is the ripgrep project, whose command is rg. Ubuntu repositories and package availability can vary by release/architecture; this exact package set is scoped to the Ubuntu 22.04 x86_64 reference, not a general Linux recipe. The Jammy package pages on Launchpad list these packages in Ubuntu 22.04, and Debian's build-essential package (bookworm) lists its gcc, g++, and make dependencies. Do not add an unrelated PPA to make it work.

Check which commands are available after installation (or if you already had them):

git --version
cc --version
c++ --version
python3 --version
rg --version
javac -version
java -version

Expected: each prints a version and returns to the prompt. javac -version and java -version may format their output differently from the other tools. If one says command not found, note which one; check whether the appropriate package is installed and whether the current shell can find its executable. Do not install every package merely because the check was listed: C/C++ exercises need the compiler, search exercises need rg, and Java exercises need a JDK. A JDK includes the Java runtime needed to run Java programs.

This host-side Java 17 JDK is for a small local Java/source-reading exercise only. It is not a promise that it is the correct JDK for every Android platform build. The AOSP requirements page says the latest release branch comes with prebuilt OpenJDK, Make, and Python 3, so build instructions may use a repository-provided JDK or specify a version tied to a branch. Follow the build lesson's version-specific instructions; do not change system Java or assume this JDK replaces AOSP's toolchain.

On Ubuntu, use the official page's Linux Platform-Tools archive. In the browser's Downloads view, open the containing folder, then use the file manager's Extract Here or Extract to… action and choose a directory you control. For the example below, extract so the archive's platform-tools directory is at $HOME/Android/platform-tools (the directory contains the adb executable). Do not run an executable from inside an untrusted download/archive. If the file manager creates a nested platform-tools/platform-tools directory, use the actual directory containing adb instead. For this simple Ubuntu Bash reference setup, add the directory for this terminal session only with:

export PATH="$HOME/Android/platform-tools:$PATH"

This prepends the directory while preserving the existing PATH. It does not install ADB and does not persist after you close the shell. If you extracted elsewhere, do not paste this path unchanged: use the actual folder. To persist a change, follow your OS/shell's official environment-variable instructions; editing shell startup files is outside this first check. Never replace the whole PATH with one folder, since ordinary commands may stop resolving. On macOS or Windows, use the platform-specific directions rather than assuming this Bash command changes the right environment.

Git installation is OS-specific: use the official Git downloads page to choose the installer or documented package source for your environment. The course does not prescribe a system package command because distributions and permissions differ. If a managed computer blocks installation, ask its administrator or use source-only mode; do not use sudo or bypass organizational controls. Platform-Tools and Git may be installed independently. A successful Git check does not say anything about ADB, and vice versa.

Host — Ubuntu Bash (verification only):

git --version
adb version

Expected: each prints a version identification and exits back to the shell prompt. Exact version and formatting vary. adb version may report a client version and installation location; it does not mean a device is connected. If you see command not found, stop: Git is not installed/discoverable, or Platform-Tools is not on PATH. Revisit the correct official installation instructions, verify the executable is in the named directory, update PATH using that OS's instructions, and open a new terminal. Do not “fix” it by downloading a similarly named executable from a random site.

On Windows WSL, run these checks inside the Ubuntu/WSL terminal, not PowerShell. WSL's PATH and Windows PATH can interact, but the location and behavior of Windows executables differ from Linux executables; do not assume that finding a Windows adb.exe is the same as installing Linux Platform-Tools in Ubuntu. Keep this course's later commands within one environment. On macOS, use Terminal and the official Platform-Tools installation directions; output may differ. A successful check means only that the host can launch the tool. It does not test USB drivers, emulator setup, ADB authorization, or an Android runtime.

Practice#

Context: host setup, no Android device changes. Choose one route and record the OS/environment name, git --version result, and adb version result. Redact usernames or local paths before sharing. If you have no workstation, mark this source-only and continue reading; no command is required. If either command fails, follow the failure branch above and record the exact error without credentials. Do not install system packages by copying commands from an unrelated distribution.

Knowledge check#

1. You run adb version and it prints a version, but adb devices -l later has no entries. What does the version result prove—and not prove?
2. A Windows tutorial shows Bash syntax, but your prompt is PowerShell. What should you do?
3. A setup page tells you to replace PATH with the Platform-Tools folder. Why is that unsafe?

Answers#

1. The workstation can find and start the ADB client. It does not prove any device is connected, authorized, or booted.
2. Use the documented WSL Ubuntu route for this course, or stay in source-only mode. Do not assume Bash commands are PowerShell commands.
3. PATH needs existing system and user program directories as well as Platform-Tools. Replacing it can make other commands unavailable; follow OS-specific instructions to add a directory safely.

Checkpoint#

Artifact: record the environment and both tool version checks (or write “source-only; no workstation”). Ready: both host commands resolve and you can explain why this does not prove a device exists. Revise: if a command is missing, follow the official-source/PATH steps and retry in a new shell. Not yet evidenced: you cannot distinguish host installation from device connection; reread “Install Git and Platform-Tools” and proceed to ADB & a safe lab only after the separate emulator setup. This lesson has not certified a particular host.

Sources#

• Git downloads — official Git installation entry point; select instructions for your OS.
• Android SDK Platform-Tools — official ADB/fastboot package downloads and release notes.
• Ubuntu 22.04 APT manual — Ubuntu's reference for apt update (refresh package metadata) versus apt install (install named packages).
• Launchpad: Ubuntu Jammy build-essential, git, python3, ripgrep, openjdk-17-jdk — Ubuntu 22.04 package names; availability can vary by architecture/repository state.
• Debian: build-essential (bookworm) — corroborates the gcc, g++, and make dependencies; a different release, not the Ubuntu 22.04 package page.
• ripgrep — upstream project; describes the rg command.
• AOSP build environment — consult the branch-specific build setup; the local Java 17 package above is not a replacement for an AOSP-selected toolchain.
• Microsoft: Install WSL — official Windows-hosted Linux setup; requirements can change with Windows releases.
• Bash manual: environment — Bash environment variables, including PATH context.

Next: Terminal and Git.