Android: Create the first project

2. Create the first project

The Hello World application is probably the most beaten down piece of sample code. Some developers look down on it because it is (already) downright nauseating. This poor example though, still has merits. It is the tiniest step one can take towards programming in unfamiliar territory and as such, the simplest.

There is no shame in taking baby steps. Knowing (well) how to construct and run the simplest programs goes a long way. Having said that, let's do the Hello World app in Android.

The Hello World of JSE (Java Standard Edition) is markedly different on the Android platform. It is not a simple case of sending a bunch of characters to the stdout (STDIO's standard out). Android is a platform for rich user interfaces. The Hello World in Android is way more involved than simply creating a simple class, defining static main() and invoking the out.println(). You will need to create and Activity object, override its onCreate() method, invoke the ant build tool, define an AVD (Android Virtual Device) and install the .apk (Android Package) either into the AVD or a physical Android Device--now, I hope you have a new found respect for the Hello World application. Let's get started.

If you have installed and configured the Android SDK, you should be ready to dive into code. If you haven't, go back to the section above, item 1 of Part 1 (Getting Started on setups). The Android SDK comes equipped with scripts that will assist in creating, debugging, deploying and testing our projects.

1.   Choose a working directory for your project. Open a terminal (Terminal.app on OSX, cmd on Windows and xterm, gnome-terminal etc on Linux)

2.   You might want to put this project under source control. This is completely optional at this point, but I encourage you to start getting into the habit of putting your dev works under source control, it will save you a lot of heartaches in the future. You can still proceed with the tutorial even if you don't have source control though

3.   Use the android create project command to setup the project. On the terminal, type

android create project --target 8 path helloworld --activity Hello --package com.thelogbox

The android create project command is available if you have properly setup your PATH variables. If you get an error such as "Bad command or filename" or "command not found" or something to that effect, that is your just OS telling you that the android executable is not properly setup. Go back to Getting started on setups.

There's quite a bit going on in here, so let's slow down and take look what those flags mean.

--target expects an integer value. This value stands for a unique API level for a specific android version. In our example above, level 8 was specified because I intend to target android 2.2 (Froyo). Gingerbread will have a different value, Honeycomb will have a different one as well. If you want to see all the possible targets, you can type android list targets

--path specifies the name of top level folder for your project. Think of it as a project folder. It will be the root directory of your project

--activitity will cause our project to create a class that extends from the the Activity class. An Activity is commonly used if we need a user-facing class. Think of it as UI 2 mechanism in android. In our example, --activity Hello means that our project will have class named Hello and is a child class of the base class Activity

--package an android project will be comprised of various XML files, resource files and Java source files. The Java source files will be stored using the package directive that we specify in the option. The package directive will only affect the location of Java source files, it will not affect the location and storage of the other android resources (i.e. XML files)

If the command completed successfully, you are supposed to have a directory similar to this one

What the android create project generated

├── AndroidManifest.xml

├── ant.properties

├── bin

├── build.xml

├── libs

├── local.properties

├── proguard-project.txt

├── project.properties

├── res

│   ├── layout

│   │   └── main.xml

│   └── values

│       └── strings.xml

└── src

   └── com

       └── thelogbox

           └── Hello.java

It's quite a mouthful and probably enough to stop a beginning programmer to his tracks and pack up, but don't do that. We will explore each and everyone of those files and folders. You can safely ignore them for now. We are just trying to get a feel of how to create a project---remember?

For now, just play around the project. Open the generated files--don't worry, they are all text files--see what they look like. They might fly over your head at this point, that's okay.

The android create project script actually generated a Java class source file for us, the Hello.java. This is an Activity class, for now just think of an Activity as some sort of window---it is more than that actually, but for now just think of it like a window so we don't have to deal with the complications. You would normally use an Activity class if you want "the user to do something". In this case, we want him to see a simple 

"Hello World" message.

You don't have to change the codes at this point. The "Hello World" is actually written for you when we created the project. If you are curious, the Hello message is inside main.xml file--we will explain that in a little while.

There are a lot of files generated by create project script becauase Android apps needs quite a bit of infrastructure code, unlike simple JSE (Java Standard Edition) programs. This is one reason why thecreate script includes a build file (build.xml), so that we dont' have muck around whipping up our own compilation scripts.

The build.xml contains instructions on how to compile and deploy your app source code into a working .apk.

1.   If you haven't closed the terminal yet, go to it. If you have closed it, open the terminal again and navigate to the root folder of the android project

2.   Try typing ant on the terminal. It should echo a bunch of possible targets. We will use the debug target to build our android app.

We will use the debug target so that we can side step android's requirement to setup security keys and signing our applications with that key. Let's deal with the application signing later on when we get to deploying and releasing our mobile app in the wild.

If we use the debug target, ant will generate a debug key that will serve as the security key for our app. This is good enough for now because we are just fooling around. Compile the app by typing

$ ant debug

You should see a bunch of scrolling echo messages in the terminal. Look for a message (right towards the end) that says something like BUILD SUCCESSFUL. It should be successful for now because we haven't messed around with it yet. There is no reason at this point for the build to fail.

.

├── AndroidManifest.xml

├── ant.properties

├── bin

│   ├── AndroidManifest.xml

│   ├── AndroidManifest.xml.d

│   ├── Hello-debug-unaligned.apk

│   ├── Hello-debug-unaligned.apk.d

│   ├── Hello-debug.apk

│   ├── Hello.ap_

│   ├── Hello.ap_.d

│   ├── build.prop

│   ├── classes

│   │   └── com

│   │       └── thelogbox

│   │           ├── BuildConfig.class

│   │           ├── Hello.class

│   │           ├── R$attr.class

│   │           ├── R$layout.class

│   │           ├── R$string.class

│   │           └── R.class

│   ├── classes.dex

│   ├── classes.dex.d

│   ├── jarlist.cache

│   ├── proguard.txt

│   └── res

├── build.xml

├── gen

│   ├── R.java.d

│   └── com

│       └── thelogbox

│           ├── BuildConfig.java

│           └── R.java

├── libs

├── local.properties

├── proguard-project.txt

├── project.properties

├── res

│   ├── layout

│   │   └── main.xml

│   └── values

│       └── strings.xml

└── src

    └── com

       └── thelogbox

            └── Hello.java

15 directories, 30 files

Right after the compilation process, there are lots of changes within our project directory. Quite noticeably, there are now lots of files inside the bin and gen folders. Somewhere in these jungle lies the executables that we can actually deploy to a real device---but save that for later. Right now, the goal is to just be comfortable with the compilation process. In case you encounter a "Cannot find build.xml" error, take a look at your SDK setup. This is usually a config error on the local.propertiesfile. Look here for details of the error

Testing the app. At this point, what we have done is simply compile an .apk, we haven't deployed it yet, either to a physical device or to an AVD. To see and appreciate your app in action, you need to deploy it either to an AVD (Android Virtual Device) or a physical device.

The AVD is an emulator. You need to create and configure an AVD using the android SDK manager;

1.   On a command line terminal, type android

2.   Wait for the SDK manager window to appear, then go Tools then AVD

3.   Click New to create an AVD.The next screen will ask you a bunch of questions on the technical details of the AVD that want to create. Fill it up with what is applicable to you (screen resolutions, amount of RAM to dedicate etc)

4.   Launch the AVD when you are done

NOTE: The AVD is terribly slow. If you are serious in developing android apps, I urge you to invest (even) on a cheap physical android device because the wait time on deployment using an AVD is counter productive and a gross misuse of developer (your) time.

If you will use a physical device for testing, you need to just a few things.

1.   Before you connect the device via a USB, you need to check some settings on the device.

2.   Go to Settings, then Applications then Development. You need to enable USB debugging

3.   Now you can connect the device to the development machine

Deploying the app. To deploy the app, either you invoke ant debug install or adb install bin/Hello-debug.apk. Either one of these commands needs to be typed from the root of the android project folder.