Your first app: build and install it

An icon on your home screen, made by you

This is the lesson everything else is built on.

By the end of it there will be an icon on your home screen that was not there this morning. Tapping it will open an app that says something you chose. It will be a real Android app — the same kind of file people download from Google Play — sitting on your phone because you made it.

You will not understand every line yet. That is completely fine and completely deliberate. Lesson 0.4 takes the whole thing apart afterwards, and it lands far better once you have the app in your hand.

One promise before we start: the first build is slow. Several minutes, possibly close to ten. It looks like nothing is happening. Nothing is broken. This lesson tells you exactly what you will see while you wait, so you never once wonder whether it has frozen.

Before you tap anything

Thirty seconds of preparation that prevents the two most common first-build failures.

• Storage. Free up about 3 GB. The Android build tools and the libraries Gradle fetches are genuinely large. Old videos are usually the fastest win.
• Power. Plug the phone in, or start above 50%. Compiling is real work and the battery notices.
• Network. You need Wi-Fi for this one build. After today you can build on a train with aeroplane mode on.
• Heat. If the phone is warm from gaming, give it two minutes. A hot phone slows itself down deliberately, and a slow build is a build you will be tempted to interrupt.

Step 1 — Make the project

Open Pocket Studio and tap Projects, then New Project.

You will be asked to choose a template. Pick the one for an Empty Compose Activity — the name may be shortened to Empty Activity or Compose. It is the one that produces a project with a single screen and nothing else, which is exactly what you want.

Then four fields. Here is what each one actually means.

Replace yourname in the package with something of your own — your first name, your initials, anything. com.amara.hellopocket is fine. Lower case, no spaces, no dashes.

That package becomes your app's application ID. Android uses it to tell your app apart from every other app on Earth. Two apps with the same ID cannot both be installed, which is why nobody sensible ships com.example.myapp.

Minimum SDK 26 means Android 8.0 and newer. That is around 95% of phones in use, and it saves you configuring workarounds for old versions you will never test on.

Now tap Create.

Step 2 — What you are looking at

Pocket Studio makes a folder full of files and opens it. Do not read them all. Lesson 0.4 does that properly. For now, exactly one file matters:

app/src/main/java/com/yourname/hellopocket/MainActivity.kt

Find it in the project tree — tap app, then src, then main, then java, then your package folders, then MainActivity.kt. Tap the file name to open it in the Editor.

Here is the whole file. Yours may have a couple of extra lines depending on the template version — that is normal, and none of them get in the way.

Step 3 — Make it yours

Tap on line 23, between the quotation marks, and change the words. Use your own name:

1@Composable
2fun Greeting() {
3  Text("Hello, Amara")
4}

Two rules, and they are the whole reason people's first build fails:

• Keep both quote marks. "Hello, Amara" — one at each end. Delete one and the compiler stops dead.
• Type real text, not a name from the code. Anything human is fine. Emoji work too.

Now save. Pocket Studio usually saves as you type, but if there is a Save action, use it.

Step 4 — Press Run, then read this while you wait

Go to the Build tab and tap the Run triangle ▶.

Then leave the phone alone. Do not lock the screen, do not switch apps, do not tap Run a second time. Read the next two pages instead — they describe, in order, exactly what is about to scroll past.

What the wall of text means

1Downloading gradle-8.11.1-bin.zip
2.........10%.........20%.........30%
3Starting a Gradle Daemon
4> Configure project :app
5> Task :app:preBuild UP-TO-DATE
6> Task :app:generateDebugResValues
7> Task :app:processDebugMainManifest
8> Task :app:mergeDebugResources
9> Task :app:processDebugResources
10> Task :app:compileDebugKotlin
11> Task :app:dexBuilderDebug
12> Task :app:mergeExtDexDebug
13> Task :app:packageDebug
14> Task :app:assembleDebug
15
16BUILD SUCCESSFUL in 6m 41s
1734 actionable tasks: 34 executed

Some things you may also see, all of them normal:

• Percentages that stall at 40% for a while, then jump. That is the network, not a bug.
• Note: Some input files use unchecked or unsafe operations — a note, not an error. Notes and warnings never stop a build.
• A line beginning w: — a warning from Kotlin. Also harmless. Lesson 0.6 explains the difference between w: and e: properly.

Step 5 — Android asks permission to install

When BUILD SUCCESSFUL appears, Android takes over and shows a system dialog. Depending on your phone, you may see one or two of these.

"For your security, your phone is not allowed to install unknown apps from this source." This is the install unknown apps setting. Android only lets an app install other apps if you have said it may. Tap Settings in that dialog, turn on Allow from this source for Pocket Studio, then press Back. You do this once.

"Do you want to install this application?" Tap Install. A few seconds later: App installed. Tap Open.

"Send app to Google for scanning?" — Play Protect being cautious about an app that did not come from the Play Store. Install anyway or Send are both fine. It is your app; you watched it being made.

Step 6 — It is running

Your words. On your screen. In an app you built.

Plain, isn't it. That is worth sitting with for a second, because plain is the point: there is no trick in it. A blank screen with one line of text, and every pixel of it came from the file you just read.

Now press the home button and find the new icon. It says Hello Pocket under a default green Android robot. Tap it. It opens without Pocket Studio being involved at all — it is a normal installed app now. Turn on aeroplane mode and it still opens, because everything it needs is already on the phone.

What you actually did

Four things, in about ten minutes:

1. Created an Android project — a folder with your code and its build settings.
2. Edited one string of text inside a composable function.
3. Ran Gradle, which compiled your Kotlin and packaged it into app-debug.apk.
4. Installed that APK on a real phone.

That is not a beginner's version of app development. That is app development. Every remaining lesson in this course is the same four steps with more interesting things in step 2.