The lunch Command

Why 'make' is Never Enough

Typing the build command into a fresh terminal immediately aborts the process. The Android Open Source Project source tree contains code for thousands of different devices, architectures, and chipsets. You cannot compile blindly without providing hardware context. Think of an auto manufacturing plant. Shouting at the workers to build a car fails because they need to know if you want a truck, a sedan, or left-hand drive. The build system requires this exact same blueprint.

We can demonstrate this failure by running the standard compilation tool without configuration. This execution proves that compilation cannot start without a selected hardware profile. You will see the terminal output a severe error about missing targets.

m

Warning: Beginners often assume the lunch command triggers the compilation process. This tool only prepares your terminal environment and compiles absolutely nothing.

To give the build system this blueprint, we use a specific string format.

Decoding the Target String

Hardware targets and security rules require a highly structured naming convention. We need a way to tell the build system exactly what hardware to target and what security rules to apply. Google solves this by enforcing a strict two-part formula. You construct a target by joining a product name and a build variant with a hyphen. The first half defines the hardware product, specifying the board, chip, and device codename. The second half defines the variant, dictating the security boundaries and debugging privileges.

This visual breakdown reveals how the build system processes your input. Follow these steps to understand the string parsing:

1. The input command receives the full target string.
2. The parser splits the string at the hyphen character.
3. The system extracts the product and variant halves.

The parser cleanly separates the hardware target from the security profile. You can also view all available standard targets by running the utility without arguments.

Typing the base command by itself provides an interactive menu. The shell will display a numbered list of predefined devices directly to standard output.

lunch

Many developers blindly guess product codenames instead of consulting this printed menu.

Tip: Google uses the aosp_ prefix for standard open-source targets. Physical devices use codenames like aosp_coral, while emulators use generic names like aosp_arm64.

While the hardware product is self-explanatory, the second half of that string fundamentally changes how Android behaves.

The Three Faces of Android: eng, userdebug, and user

Developers require access to internal system logs that retail users should never see. Choosing the wrong security profile will either lock you out of your own code or hide critical permissions crashes. AOSP solves this tension by offering three distinct build variants. Retail phones use the user variant, representing a locked-down console with strict SELinux enforcement and no root access. Developers rely on the userdebug variant for production behavior with unlocked root privileges. An eng variant resembles a bare circuit board on a workbench, granting root by default and relaxing SELinux rules for initial hardware bring-up.

An app developer tracking a framework bug should use a userdebug build to pull logs hidden in a user build.

Common Mistake: Engineers frequently use eng builds for framework development. This masks real-world permission issues because SELinux is relaxed. Always use userdebug unless you are actively bringing up new hardware components.

These standard targets cover Google's devices, but custom hardware developers need a way to plug into this menu.

Teaching lunch About Your Custom Board

How do you make your company's custom tablet show up in the menu? The standard AOSP tree knows nothing about your proprietary silicon. You must inject your custom device into the official build system. The menu generates dynamically by scanning device directories for specific configuration files. You expose custom targets by creating a file named AndroidProducts.mk inside your vendor board directory. Defining a variable called COMMON_LUNCH_CHOICES inside this file registers your target.

Modifying this file allows you to append custom hardware definitions. This prevents the need to manually configure complex hardware flags every time you build. Your device will immediately appear in the interactive list.

# device/mycompany/med-tablet/AndroidProducts.mk
COMMON_LUNCH_CHOICES += med_tablet-userdebug

Engineers often update this file and wonder why the utility fails to show the new target. They forget to re-run source build/envsetup.sh to refresh the build scripts.

Behind the interactive menu and target strings, the configuration process does one very simple thing to your terminal environment.

What Actually Happens to Your Shell

Selecting a target feels like a complex build operation, but the reality is much simpler. System files and source code remain untouched during this configuration step. The tool operates purely by modifying your current bash session state. It evaluates your choice and exports a series of critical environment variables. Two important variables are TARGET_PRODUCT and TARGET_BUILD_VARIANT. These exported strings lock the shell to the target hardware.

We can map this state transformation to see how the shell changes. Follow these steps to trace the environment injection:

1. The empty shell receives the lunch command.
2. The utility calculates the required configuration.
3. The system injects variables directly into the active session.

This visual flow demonstrates how a single command reads your target string and updates your active session. The shell absorbs the newly exported text, securely locking your terminal onto that specific hardware target.

Running printconfig proves that the terminal state changed successfully. This diagnostic command outputs a summary of the active build variables. You will see a table showing your chosen product, variant, and target architecture.

printconfig

Engineers often close their terminal and assume these exported variables persist.

Tip: Exported variables vanish when you open a new terminal tab. You must run envsetup.sh and lunch again in any new window before compiling.

The configuration tool builds a bridge between raw source code and hardware configuration by exporting shell variables. You construct a target with a product and variant, or expose custom ones via device makefiles. Your shell is loaded with macros, and your environment variables are perfectly locked. All that is left is to tell the build system to actually start compiling with m.