Project

General

Profile

SDK » History » Version 25

Paul Kocialkowski, 08/12/2012 02:05 PM

1 1 John Smith
h1. SDK
2
3 25 Paul Kocialkowski
|_. Replicant version |_. Last SDK |_. API revision |
4
| Replicant 2.3 | 0001 | 10 |
5
| Replicant 2.2 | 0002 | 9 |
6 1 John Smith
7 25 Paul Kocialkowski
The [[ReplicantSDK]] page holds a list of the released Replicant SDK builds.
8 1 John Smith
9 25 Paul Kocialkowski
h2. Rationale
10 1 John Smith
11 25 Paul Kocialkowski
Replicant provides its own SDK, built from source, since the Android SDK as released by Google contains some non-free bits such as Google APIs.
12
Here is a list of the known non-free bits present in the Android SDK as released by Google:
13 1 John Smith
14 25 Paul Kocialkowski
|_. Component |_. Functionality |
15 1 John Smith
16 25 Paul Kocialkowski
h2. Installation guide
17 1 John Smith
18 25 Paul Kocialkowski
After downloading the Replicant SDK from the [[ReplicantSDK]] page, it should work the same as the Android SDK as provided by Google except that the Replicant SDK already contains a built and ready to use emulator image. 
19
Please refer to: http://developer.android.com/sdk/installing/index.html for further assistance. 
20 1 John Smith
21
h3. Dependencies
22
23 25 Paul Kocialkowski
Generally speaking, the Android/Replicant SDK requires the following packages:
24
* SDL
25
* Java JDK such as OpenJDK 6
26 1 John Smith
27 25 Paul Kocialkowski
In some unlikely cases, creating a "JAVA_HOME" environment variable and pointing it to your JDK's true install location (not the "bin" directory but one level upward) may prove necessary.
28 1 John Smith
29 25 Paul Kocialkowski
h4. Additional requirements for amd64
30 1 John Smith
31 25 Paul Kocialkowski
Note that the Replicant SDK is built for x86 platforms and you may need compatibility libraries such as @ia32-libs@.
32
On Trisquel/Ubuntu/Debian, you can install these with:
33
<pre>
34
apt-get install ia32-libs
35
</pre>
36 1 John Smith
37 25 Paul Kocialkowski
h2. Usage guides
38 2 John Smith
39 25 Paul Kocialkowski
h3. Using Eclipse
40 1 John Smith
41 25 Paul Kocialkowski
You may want to install Eclipse to work on Android Java applications. Note that this is not strictly necessary as all the required tools are already present on the SDK package. 
42 1 John Smith
43 25 Paul Kocialkowski
h4.  Installing the "Android Development Tools" plugin for Eclipse
44 1 John Smith
45 25 Paul Kocialkowski
If you have Eclipse installed and running properly, you may want to install the Android Development Tools plugin.
46 8 John Smith
47 25 Paul Kocialkowski
A solution for Eclipse 3.6 (not advised): some documentation recommends adding "https://dl-ssl.google.com/android/eclipse/" as a software update site in Eclipse, and pulling ADT from there. People have observed that this currently results in getting an ADT version which requires Eclipse 3.6, which has known issues and is not available in some widespread GNU/Linux distributions (e.g. Debian) at the moment.
48
49 1 John Smith
A somewhat manual solution:
50
51
* download ADT 0.9.8 into a stable location in your computer
52
53
http://dl.google.com/android/ADT-0.9.8.zip
54
Size: 8301417 B
55
MD5: 27e0de800512f13feae46fb554e6ee2f
56
57
* in Eclipse 3.5
58
59
- select "Window" > "Preferences" > "Install/Update" > "Available Software Sites"
60
- click the "Add" button
61
- name your software site something recognizable, e.g. "ADT 0.9.8"
62
- click "Archive" and select the "ADT-0.9.8.zip" file
63
64
* in Eclipse 3.5
65
66
- select "Help" > "Install New Software"
67
- select the "ADT 0.9.8" software site from the dropdown menu
68
- select the "Developer Tools" software package
69
- verify that the "Android DDMS" and "Android Development Tools" sub-packages were selected
70
- click the "Next" to install Android Developer Tools
71
72 2 John Smith
* restart Eclipse
73
74 25 Paul Kocialkowski
h4. Pointing "Android Development Tools" to the SDK directory
75 1 John Smith
76 9 John Smith
When you have installed ADT and restarted Eclipse, select the "Window" menu. You should see a menu entry named "Android SDK and AVD Manager". Then select "Preferences" from the "Window" menu. A menu item named "Android" should be available on the left panel.
77 3 John Smith
78 11 John Smith
If not, something is wrong. You might have the wrong flavour of Eclipse installed (the Classic, Java or RCP flavours are recommended). For example, it has been observed that the default Eclipse version which installs under Debian 6.0 ("squeeze") does not install ADT correctly, while an installation of Eclipse Classic 3.5.2 ("Galileo") downloaded from http://archive.eclipse.org/eclipse/downloads/drops/R-3.5.2-201002111343/download.php?dropFile=eclipse-SDK-3.5.2-linux-gtk.tar.gz (MD5: bde55a2354dc224cf5f26e5320e72dac) works fine. 
79 2 John Smith
80 12 John Smith
Once the "Android" menu item is available in the "Window" > "Preferences" dialog, select it. In the main panel, click the "Browse" button for the "SDK Location" field, and point it to the directory where you unzipped your Replicant SDK. Then click "Apply" or "OK".
81
82
Next time you enter this dialog, a line saying "Android 2.2.1 / Android Open Source Project / Platform: 2.2.1 / API level: 8" should be present in the list of SDK targets.
83
84 25 Paul Kocialkowski
h3. Writing a "Hello World" app in Eclipse
85 13 John Smith
86
h4. Creating an Android Virtual Device
87
88
To run your app in an emulator, you need to create an Android Virtual Device. In Eclipse, choose "Window" > "Android SDK and AVD Manager" > "Virtual Devices" > "New" and fill in the properties of the virtual device as follows:
89
90 14 John Smith
- Name: something descriptive like "AVD_for_Nexus_S"
91 13 John Smith
- Target: choose "Android 2.2.1 - API level 8" from the dropdown menu
92
- SD Card: specify the size of an emulated SD card, alternatively browse for an existing SD card image
93
- Skin: better choose "Default" and the screen resolution of your physical device, e.g. "WVGA800" for Nexus S
94
- leave other values at defaults and click "Create AVD"
95 1 John Smith
- if your disk is slow and you specified a large SD card image for creation, it may take a few seconds to complete
96 14 John Smith
97 17 John Smith
h4. Creating a project
98 14 John Smith
99
In Eclipse, choose "File" > "New" > "Project". In the tree of possible project types, a branch named "Android" should exist. Open it, select the project type "Android Project" and click "Next".
100 15 John Smith
101
Enter a name for your project, e.g. "hello". For "Content", select "Create new project in workspace" and "use default location". The project will be created in your local Eclipse workspace directory, in a subdirectory corresponding to the project name.
102
103 16 John Smith
Besides the project name, enter a friendly name for your application, e.g. "Hello World". Enter its package name, which can be either public (e.g. "com.example.hello") or private (e.g. "hello.test"). If you want the first piece of your application's user interface to be auto-created, leave the "Create Activity" checkbox checked and enter someting like "MainActivity" for the name of the "Activity" class to create.
104 15 John Smith
105 1 John Smith
Leave the minimum SDK version blank. Finally click "Finish" and your project should appear in Eclipse's left-hand projects tree.
106 17 John Smith
107
h4. Adding some code and resources into a project
108
109
To have your application's MainActivity class do something, consider adding some code. For example, you might want your application to have a button which closes it. In this sample, we specify the design of user interface elements in a separate XML resource file, so don't be surprised when you don't see anything related to their design here:
110
111
<pre>package hello.test;
112
113
import android.app.Activity;
114
import android.os.Bundle;
115
import android.view.View;
116
import android.widget.Button;
117
118
public class MainActivity extends Activity {
119
120
    @Override
121
    public void onCreate(Bundle savedInstanceState) {
122
    	
123
        super.onCreate(savedInstanceState);
124
        setContentView(R.layout.main);
125
        
126
        Button buttonFinish = (Button) findViewById(R.id.buttonFinish);
127
        buttonFinish.setOnClickListener(new View.OnClickListener() {
128
			@Override
129
			public void onClick(View v) {
130
				finish();
131
			}
132
		});
133
    }
134
}</pre>
135
136
You may notice how the constructor of MainActivity calls "setContentView(R.layout.main)". In this statement, R is a special resource class, pointing to resources hosted in the "res" directory of your project. The "layout" class limits the choice to layout resources hosted under the "res/layout" while "main" is the name of a layout resource file "main.xml" located there.
137
138
We need to create this resource file now. I would recommend having it be like this:
139
140
<pre><?xml version="1.0" encoding="utf-8"?>
141
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
142
    android:orientation="vertical"
143
    android:layout_width="fill_parent"
144
    android:layout_height="fill_parent"
145
    >
146
<TextView
147
    android:id="@+id/textInfo"
148
    android:layout_width="fill_parent" 
149
    android:layout_height="wrap_content" 
150
    android:text="Click button to close app."
151
    />
152
<Button android:id="@+id/buttonFinish"
153
    android:layout_width="wrap_content"
154
    android:layout_height="wrap_content"
155 18 John Smith
    android:text="Close" />
156 17 John Smith
</LinearLayout>
157 1 John Smith
</pre>
158 18 John Smith
159 19 John Smith
Together, it makes sense. The "LinearLayout" element directs the application to fill the screen with its window ("fill_parent" for width and height). The "TextView" element displays a text field expanding to cover window width, but limits itself to content height ("wrap_content"). The "Button" element is a button named "buttonFinish", big enough to accommodate its content. Code obtains a handle to it by calling "Button buttonFinish = (Button) findViewById(R.id.buttonFinish);"), and creates an event listener for its OnClick event. This event listener calls "finish()" to close the app.
160 20 John Smith
161
h4. Running the app on an Android Virtual Device
162
163
Once you've coded your app, choose "Run" > "Run" in Eclipse. A dialog named "Android Device Chooser" will open, asking you to choose a device for it. Select the "Launch a new Android Virtual Device" checkbox and the virtual device you previously made, should become available for selection (select it and click "OK"). The virtual device will start booting up and will eventually run your app. Beware, on slow computers (e.g. an old model of Asus EEE PC) this can take minutes.
164 21 John Smith
165
h4. Running the app on a real Replicant device
166
167 22 John Smith
1. Declare your app as debuggable. In the left-hand sidebar of Eclipse, your project's resource tree should contain a file resource named "AndroidManifest.xml". Right-click it and choose "Open With". Proceed by choosing either "Android Manifest Editor" or "Text Editor". If you preferred the manifest editor GUI, select the tab "Application" at its bottom. On the "Application" tab, set the field "Debuggable" to "true". If you preferred the text editor, append the property "android:debuggable="true" to the "<application>" element.
168
169
2. Enable USB debugging on your device, for example by choosing "Menu" > "Settings" > "Applications" > "Development" and checking the "USB Debugging" checkbox.
170 23 John Smith
171
3. Verify that your device is visible. Prior to this, on Windows, you should install the ADB USB driver. On Mac, you should not need to configure anything. On some Linuxes (e.g. Ubuntu), you might need to add uDev rules (consult the "docs/guide/developing/device.html" file in your SDK directory, it contains detailed instructions).
172
173 24 John Smith
Do the verification by issuing "adb devices" on command line. Make your your ADB (Android Debug Bridge) is included in your PATH variable. If it lists your device and its numeric ID, all should be fine. If it lists "?????????" for the ID and says "No permissions" under Linux, you might need to restart the ADB server (become root and issue: "adb kill-server; adb start-server", this presumes that ADB is also present in the root user's PATH).
174 23 John Smith
175 24 John Smith
4. Run the app. Without a customized run configuration, Eclipse should display the "Android Device Chooser" dialog, letting you choose. 
176 23 John Smith
177
5. Optionally, configure automatic deployment: if you want to automatically deploy to devices when they're attached, create a run configuration for your app, proceeding to select "Deployment Target Selection Mode: Automatic" in the "Target" tab.