Android command line program

Building Android programs on the command line

Version 1.0, June 2011
Geotechnical Software Services
Copyright © 2011

This guideline shows how to build Android programs (apps) using a command line environment only.

Even though the Eclipse IDE (among others) can be a powerful development environment for Android programmers, there are several reasons why you could benefit from utilizing simple command line utilities and build scripts instead. Actually understanding what’s going on is one of them.

Using the stepwise approach outlined below might seem overwhelming, but there is a great educational value in performing these steps, and the information present is essential if you are setting up a build system based on make, SCons, Ant, or similar tools.

The setup below depends on a few environment variables identifying directory paths on the local system. The exact procedure for setting and accessing environment variables differs between operating systems and command shells. In the present guideline the simplest possible notation is being used. In practice these variables needs to be accessed using special notation like %JAVA_HOME%, $ or even "$" if the path contains spaces. In addition, commands are listed over multiple lines to improve readability. In practice commands must be written on a single line or separated by proper line delimiters. Note also that the forward slash character ("/") is consistently used as directory delimiter even though the backslash ("\") is still used on some systems.

Color coding is used in the commands in order to easily indicate where local replacements needs to take place.

All commands are self-contained meaning that they can be executed from any directory.

1. Download Java

Default installation location will vary between Java versions and OS platforms, so create a pointer to its location:

JAVA_HOME = C:/Program Files/Java/jdk1.6.0_26

2. Download Android

The Android Software Development Kit (Android SDK) is available from Google at http://developer.android.com/sdk.

Default installation location will vary between Android versions and OS platforms, so create a pointer to its location:

ANDROID_HOME = C:/Program Files/Android/android-sdk

The download includes the core parts of Android. In addition you need SDK(s) for the specific Android platforms you will develop for and test on. Launch the SDK manager GUI, select Available packages and open the Android Repository:

ANDROID_HOME/tools/android

Select the required platform/tool packages (all is fine) and hit the Install Selected button. After installation, the platform/ and platform-tools/ directories of ANDROID_HOME should have been populated.

3. Choose project name

At some disk location create a project directory that will hold the code, libraries and other files that constitutes the Android project. Create a pointer to this location:

DEV_HOME = C:/Users/johnd/dev/ AndroidTest

The project name in this context is simply a convenience in order to consistently name directories and files related to the application being created.

In the example AndroidTest is used as the project name. The term has been emphasized below so that it can be easily replaced.

4. Create development area

Beneath the project directory create sub directories as follows:

The src/ directory will hold java code and other source files in a package structure common for java projects. Using the reverse domain name system (Reverse DNS) for package names is optional but recommended.
The res/ directory will hold user provided resources like text strings, images, menues, layouts etc. The res/ sub directories have predefined names according to the Android resource documentation.
The obj/ directory will contain .class files and other secondary files produced by the Java tools as explained below.
The lib/ directory should hold 3rd-party .jar files the project depends on.
The bin/ directory will hold intermediate and final executables produced by the Android tools.
The docs/ directory will hold javadoc HTML documents for the project. If generated, the docs/index.html file will be the entry point.

5. Create manifest

The Android manifest file is used to specify application settings like name and version, as well as what permissions the application requires to run and what components it is comprised of. The file contains a single application tag inside the root manifest tag.

Put the manifest file in the project root directory: DEV_HOME/AndroidManifest.xml. Note that the file must be called AndroidManifest.xml and nothing else.

A typical manifest file is shown below:

The package attribute identifies the application and is also the destination location of the generated R.java file (see below). versionCode is a numeric version value for managing application updates. versionName is the application version in a human readable form.

The application tag contains the activities of the program, one of which should contain the main launcher activity as shown.

6. Select target platform

The different Android OS versions are known through target names like android-3, android-4, android-5 etc. All available platforms can be listed by the following command:

ANDROID_HOME/tools/android list target

For the examples below we use android-7 (Android OS 2.1) consistently. Replace this with a different target as required.

7. Define virtual device

An Android Virtual Device (AVD) defines the main characteristics of the target Android device. AVDs are used only when testing an Android program in the Android emulator. The typical approach is to define several AVDs in order to verify that a program behave correct across hardware platforms and OS versions.

Use the android tool to create AVDs:

This will create an AVD with the specified name and with a 1 GB memory card disk image. When the command is executed you are asked if you want to specify a custom hardware profile. By this the AVD can be tailored to a specific hardware device by identifying properties for features like screen, camera, memory, battery, audio, accelerometer, wi-fi, bluetooth, GPS, keyboard and so on.

If no longer needed, an AVD can be deleted as follows:

The actual AVD profiles are stored within the HOME/.android/avd/ directory.

8. Create keystore

A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. An Android program must be signed in order to execute on a device, and the program is signed by using a key from a keystore.

Use the keytool program to create a keystore:

Replace the distinguished name (dname) information with your own. Make sure to specify passwords as indicated. The key is accessed through the specified alias which can be any string.

The output of the command will be the DEV_HOME/ AndroidTest .keystore file which contains one key identified by the supplied alias.

9. Write code

Define a suitable package structure and put the Java code within the src/ tree of the project area.

The following minimal class can serve as an example. It should be located in DEV_HOME/src/ com/mycompany/package1/HelloAndroid .java:

The Android API documentation contains a complete reference to the Android packages and classes, including the ones provided by the Java SE.

10. Provide resources

Android programmers are advised to keep all non-logic data (text strings, images, animations, colors, layouts etc.) within the designated res/ directory of the project area. The res/ directory consists of a predefined set of sub directories with a naming structure that will simplify application localization and adoption to different hardware types.

The following minimal text resource can serve as an example. It should be located in DEV_HOME/res/values/strings.xml:

The manifest file refers to the myApplicationName entry, while the java class above refers to the helloText entry. The example manifest file above also refers to the drawable resource mylogo which is the icon image for the program. Put an image file in the res/ directory to serve this purpose: DEV_HOME/res/drawable/ mylogo .png.

11. Create R.java

In order for the application source code to be able to access the resources within the res/ directory, a class called R.java (for Resources) is created.

The destination location of R.java within the src/ tree is determined by the package attribute of the manifest file.

12. Compile code

Use the javac tool to compile java source code in a package:

The command must be applied for each existing package. 3rd-party .jar files from the lib/ directory must be listed in the -classpath entry. Note that on UNIX-like operating systems the classpath entry delimiter should be a colon («:»).

The output of the command is .class files in the obj/ tree.

Non-java files within the src/ tree must be copied to the associated location in the obj/ tree.

13. Create DEX file

DEX («Dalvik Executable») is the specific bytecode format understood by the Dalvik virtual machine (VM) present in all Android devices.

Use the dx tool to bundle the content of the obj/ directory as well as 3rd-party .jar files from the lib/ directory into a single .dex file:

This will create the classes.dex file in the bin/ directory. The content of a .dex file can be inspected using the ANDROID_HOME/platform-tools/dexdump tool.

14. Create APK file

The Android package format (APK) is the .jar equivalent for Android. The package contains the manifest file, the resources and the classes.dex file.

Use the aapt tool to create the .apk file:

This will create the AndroidTest .unsigned.apk file in the bin/ directory. Note that APK is an ordinary archive format that can be inspected by tools like WinZip or unzip -l.

15. Sign APK file

In order to execute on an Android device, the Android package needs to be signed.

Use the jarsigner tool and the key from the keystore created above to create a signed version of the package:

The signing process adds the META-INF/ directory to the APK archive including the signature (.SF) file and the associated PKSC file (.RSA).

The signed APK is stored as AndroidTest .signed.apk file in the bin/ directory.

16. Zip-align APK file

zipalign is an archive alignment tool that provides important optimization to Android packages. This step is optional, but recommended:

This will create the AndroidTest .apk which is the final product delivered in one self-contained unit.

17. Start emulator

In order to test the application, start the Android emulator and specify the virtual device (AVD) to use:

This will launch the emulator GUI. The wipe-data option ensures the emulator starts up clean. The initialization process may take some time, so don’t proceed until the emulator is ready.

18. Install in emulator

When the emulator is ready, use the Android Debug Bridge (adb) tool to install the Android package in the running emulator:

The program should eventually show up in the emulator and can be executed by selecting it.

The application can be uninstalled as follows:

Note that inside the emulator or device the APK is stored using its main package name (from the package attribute of the manifest file) with an .apk extension.

19. Install on device

Attach the Android device to the computer and install the program using the adb command:

The program should be ready for execution on the target device.

20. Create documentation

7Every well managed project should have up-to-date documentation available at any time. This step is of course optional, but strongly recommended.

Use the javadoc tool to create HTML documentation as follows:

Source from additional packages should be added to the last argument using «:» or «;» as delimiter (depending on platform).

Источник

Prerequisites

To properly follow this material, you must have the following in place:

(1) You have installed the latest Java Development Kit (JDK) from Oracle. (java.com/download)

(2) You must have installed Android SDK. If you have not done so yet, you can download the Android SDK here: developer.android.com/sdk

(The Android SDK can be downloaded separately as a stand alone installer, or as part of the bigger Android Studio installer)

The Android SDK and the associated commands work roughly exactly the same way on Windows, Mac OS X and Linux. Therefore, the instructions given here should be applicable regardless of your operating system.

The «android» command

If you have the Android SDK in place, you can locate the «android» command inside the tools directory. To try it, open up your command line, and issue the following kind of command (obviously replacing the beginning with the complete path to the actual directory where you have installed the SDK files):

Then press ENTER. By default, the Android SDK Manager will be displayed:

The Android SDK Manager lets you download and install, uninstall, and update necessary packages (SDK tools and platforms) that you need to develop an Android app. Full information about this GUI tool can be found on the Android developer site:

Going back to the command line, to list some of the things that can be done with the android tool, try this:

You should see commands with corresponding descriptions like the following below:

List Targets

To display the list of available Android target(s) / SDK versions that are available on the current system, try this:

You should see available targets like the following:

(Followed by other targets, if available)

Take note of the «id» line in this list, as that is the value that you can use in other places to refer to the specific version of an Android SDK target.

List Devices

To display a list of available Android device(s) that are currently configured, try this:

You should see available device definitions like the following:

(Followed by other devices, if available)

The Android Emulator

The Android Emulator emulates a complete Android device in software on a desktop computer. Therefore, to do Android development, you will not necessarily need to have an actual physical device at your disposal. You can locate the Android emulator tool as part of the Android SDK here:

Creating an Android Virtual Device

To run an instance of the Android operating system inside the emulator, you will first need to create an Android Virtual Device. You can do this with the following kind of a command:

Type the entire command on one line. Then press ENTER in the end. You should see something like this:

Cool! You have successfully created your Android Virtual Device.

Running your virtual device

To execute your new Android Virtual Device in an emulator, you can simply do this:

You should see and Android Emulator starting up and something like below in the terminal window:

The emulator itself should have opened in a new window, running a complete copy of the Android operating system.

Creating a new Android application

To create the initial source code for a new Android application, try this:

Again, the entire command would be written on one line. In the end, press ENTER. You should see something like this in your terminal window:

Awesome! You have successfully created an Android project.

Project Directory Contents

After successfully creating a project, navigate to your project directory. You should have the following files and directories in place:

Adjust the created project

It appears that the project creation script is stuck in an older version of Gradle, which is no longer compatible with newer versions of the overall Android build system. To address the problem, we will need to edit the «gradle-wrapper.properties» file under the «wrapper» subdirectory of the «gradle» directory in the created project source. In that file, by default, you find a line like this:

This can be changed to this:

(essentially, we change gradle version from 1.12 to 2.2.1, as it should be).

Likewise, in the generated «build.gradle» file, you should change the line that says «runProguard false» to «minifyEnabled true» (apparently, the syntax for this was changed at a point during the Android build system development cycle, but the «android create project» script is yet to be updated accordingly).

Compiling an Android Project

Before you compile your project, you must be connected to the internet in order for the gradle wrapper script to download the appropriate gradle software components. Once ready, to compile your Android project, navigate to your project directory on your command line (change directory), and do this:

For Mac or Linux:

The «gradlew» script is a wrapper script that then downloads all the necessary components that are needed to run the complete Gradle build. Once any necessary downloading is completed, the wrapper continues to execute the actual build. In the end, you should find the final APK installer in the «build» -> «outputs» -> «apk» directory under your project directory:

The installer to use is the second one in the list above (*-debug.apk).

The APK file

The Android Application Package, most commonly known as APK, is the installer and distribution file format for Android apps. Once your Gradle build has successfully completed, you should have an APK file that was generated from your source code.

The Android Debug Bridge

Android Debug Bridge (adb) is a command line tool used to communicate with a connected android device or emulator. It is commonly used for installation and debugging of apps during development.

You can locate the Android Debug Bridge executable (adb or adb.exe) here:

For complete official information about Android Debug Bridge, refer to the link below:

Bear in mind that before you install and debug an app, you must have one of the following in place:

(1) Connected Android device

(2) Running Android Emulator

Select the appropriate device

If you have a device connected, or an emulator running, to check if it is connected, try this:

This command will list all physical Android gadgets (tablets, phones, etc.) that you have connected to your development computer (via USB or otherwise), as well as any Android emulator instances that you may have running. If ever you plug in several devices, and/or run several emulators simultaneously, observing this list becomes increasingly important in selecting which one of them you would wish to interact with.

You should see something like the following:

To select a specific Android instance (whether device or emulator) to use, you can use the -s parameter of adb to specify which device to use, followed by the device ID from the list above. For example:

Installing an Android app

If this is your first time to install the particular app on the device or emulator, you can simply do this:

Then press ENTER and the following kind of information should be displayed in your terminal window:

Congratulations. You have successfully installed your Android app. It should now appear in the application menu of the device or emulator.

Replacing or reinstalling an app

To replace a previously installed app, the -r parameter of adb can be used. Try this:

Take note that the -r parameter means to replace an existing application. So, doing this ..

.. would generate an error, as shown below, since you are trying to install the same version of the app without using the -r parameter.

Debugging with adb logcat

The logcat command of adb is used to display system messages of a running Android OS (whether device or emulator). This is extremely useful to find out what is happening to an application or a device. Any and all messages generated by the device are shown here, giving a wealth of information for any kind of troubleshooting requirements.

You should see logs in your terminal window something like the following:

The logcat command of adb is commonly used by app developers and testers to trace the cause of crashes in an Android app during development.

Filtering logs

To filter logs using the logcat command of adb. You can do this:

The asterisk (*) character means ALL logs and the hash (#) character is the filter, which can be one of the following:

For example, doing this .

. would result to something like the following:

When filtering logs, a priority is followed from top to bottom. If *:W is used, Warnings are displayed first followed by Errors then Fatal logs. Like in the sample above. Thus, filtering with Verbose (default) will display the logs starting from Verbose down to Fatal.

Furthermore, you can also filter logs with a keyword. Try this (this only works on a Unix-like environment, such as Mac OS X or Linux):

For example, doing this .

. would result to something like the following:

The pipe (|) character means that logs from the logcat command of adb will be an input for grep (a command used to search for strings). The -i parameter of grep means ignore case.

Interrupting logcat

You can at any time interrupt the logcat command by pressing Ctrl+C in your terminal window. You should then have returned to your command line.

Congratulations!

You have completed this tutorial. You have successfully created an Android application purely on the command line.

Источник