[SCM] androidsdk-tools packaging branch, master, updated. 3ca7baf4b1bf87ea79390a9eb677a3104aa86570

[Jakub Adam]

The following commit has been merged in the master branch:
commit d1dc95e1e0b62c60259bfef2b87b564d1303030a
Author: Jakub Adam <jakub.adam at tieto.com>
Date:   Mon Apr 29 12:22:44 2013 +0200

    Created manual page for ddms

diff --git a/debian/androidsdk-ddms.manpages b/debian/androidsdk-ddms.manpages
new file mode 100644
index 0000000..cb284ae
--- /dev/null
+++ b/debian/androidsdk-ddms.manpages
@@ -0,0 +1 @@
+ddms.1
diff --git a/debian/copyright b/debian/copyright
index 968996a..1b262ec 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -5,17 +5,6 @@ Source: https://android.googlesource.com/platform/sdk
 Files: *
 Copyright: 2005-2013, The Android Open Source Project
 License: Apache 2.0
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- .
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
- .
- On Debian systems, the full text of the Apache License, Version 2.0
- can be found in the file `/usr/share/common-licenses/Apache-2.0'.
 
 Files: swtmenubar/*
 Copyright: 2011-2012, The Android Open Source Project
@@ -46,6 +35,24 @@ License: GPL-2+
  License version 2 can be found in the file
  `/usr/share/common-licenses/GPL-2'.
 
+Files: debian/ddms.pod
+Copyright: 2013, www.linuxtopia.org
+           2012-2013, Jakub Adam <jakub.adam at ktknet.cz>
+License: Apache-2.0
+
+License: Apache 2.0
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ .
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ .
+ On Debian systems, the full text of the Apache License, Version 2.0
+ can be found in the file `/usr/share/common-licenses/Apache-2.0'.
+
 License: EPL-1.0
  Eclipse Public License - v 1.0
  .
diff --git a/debian/ddms.pod b/debian/ddms.pod
new file mode 100644
index 0000000..cf927d6
--- /dev/null
+++ b/debian/ddms.pod
@@ -0,0 +1,288 @@
+=head1 NAME
+
+ddms - a graphical debugging tool for Android
+
+=head1 SYNOPSIS
+
+ddms
+
+=head1 DESCRIPTION
+
+Dalvik Debug Monitor Service (DDMS) provides port-forwarding services, screen
+capture on the device, thread and heap information on the device, logcat,
+process, and radio state information, incoming call and SMS spoofing, location
+data spoofing, and more. This page provides a modest discussion of DDMS
+features; it is not an exhaustive exploration of all the features and
+capabilities.
+
+DDMS will work with both the emulator and a connected device. If both are
+connected and running simultaneously, DDMS defaults to the emulator.
+
+=head2 How DDMS works
+
+DDMS acts as a middleman to connect the IDE to the applications running on
+the device. On Android, every application runs in its own process, each of
+which hosts its own virtual machine (VM). And each process listens for
+a debugger on a different port.
+
+When it starts, DDMS connects to adb and starts a device monitoring service
+between the two, which will notify DDMS when a device is connected or
+disconnected. When a device is connected, a VM monitoring service is created
+between adb and DDMS, which will notify DDMS when a VM on the device is started
+or terminated. Once a VM is running, DDMS retrieves the the VM's process ID
+(pid), via adb, and opens a connection to the VM's debugger, through the adb
+daemon (adbd) on the device. DDMS can now talk to the VM using a custom wire
+protocol.
+
+For each VM on the device, DDMS opens a port upon which it will listen for
+a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next
+on 8601, and so on. When a debugger connects to one of these ports, all traffic
+is forwarded between the debugger and the associated VM. Debugging can then
+process like any remote debugging session.
+
+DDMS also opens another local port, the DDMS "base port" (8700, by default),
+upon which it also listens for a debugger. When a debugger connects to this
+base port, all traffic is forwarded to the VM currently selected in DDMS, so
+this is typically where you debugger should connect.
+
+Tip: You can set a number of DDMS preferences in File > Preferences. Preferences
+are saved to "$HOME/.ddmsrc".
+
+=head3 Known debugging issues with Dalvik
+
+Debugging an application in the Dalvik VM should work the same as it does in
+other VMs. However, when single-stepping out of synchronized code, the
+"current line" cursor may jump to the last line in the method for one step.
+
+=head2 Left Pane
+
+The left side of the Debug Monitor shows each emulator/device currently found,
+with a list of all the VMs currently running within each. VMs are identified
+by the package name of the application it hosts.
+
+Use this list to find and attach to the VM running the activity(ies) that you
+want to debug. Next to each VM in the list is a "debugger pass-through" port
+(in the right-most column). If you connect your debugger to one of the the ports
+listed, you will be connected to the corresponding VM on the device. However,
+when using DDMS, you need only connect to port 8700, as DDMS forwards all
+traffic here to the currently selected VM. (Notice, as you select a VM in the
+list, the listed port includes 8700.) This way, there's no need to reconfigure
+the debugger's port each time you switch between VMs.
+
+When an application running on the device calls waitForDebugger() (or you
+select this option in the developer options), a red icon will be shown next to
+the client name, while it waits for the debugger to attach to the VM. When
+a debugger is connected, the icon will turn green.
+
+If you see a crossed-out bug icon, this means that the DDMS was unable to
+complete a connection between the debugger and the VM because it was unable to
+open the VM's local port. If you see this for all VMs on the device, it is
+likely because you have another instance of DDMS running (this includes the
+Eclipse plugin).
+
+If you see a question mark in place of an application package, this means that,
+once DDMS received the application pid from adb, it somehow failed to make
+a successful handshake with the VM process. Try restarting DDMS.
+
+=head2 Right pane
+
+On the right side, the Debug Monitor provides tabs that display useful
+information and some useful tools.
+
+=head2 Info
+
+This view shows some general information about the selected VM, including the
+process ID, package name, and VM version.
+
+=head2 Threads
+
+The threads view has a list of threads running in the process of the target VM.
+To reduce the amount of data sent over the wire, the thread updates are only
+sent when explicitly enabled by toggling the "threads" button in the toolbar.
+This toggle is maintained per VM. This tab includes the following information:
+
+B<ID> a VM-assigned unique thread ID. In Dalvik, these are odd numbers starting
+from 3.
+
+B<Tid> the Linux thread ID. For the main thread in a process, this will match
+the process ID.
+
+B<Status> the VM thread status. Daemon threads are shown with an asterisk (*).
+This will be one of the following:
+
+    running  - executing application code
+    sleeping - called Thread.sleep()
+    monitor  - waiting to acquire a monitor lock
+    wait     - in Object.wait()
+    native   - executing native code
+    vmwait   - waiting on a VM resource
+    zombie   - thread is in the process of dying
+    init     - thread is initializing (you shouldn't see this)
+    starting - thread is about to start (you shouldn't see this either)
+
+B<utime> cumulative time spent executing user code, in "jiffies" (usually 10ms).
+Only available under Linux.
+
+B<stime> cumulative time spent executing system code, in "jiffies" (usually
+10ms).
+
+B<Name> the name of the thread
+
+"ID" and "Name" are set when the thread is started. The remaining fields are
+updated periodically (default is every 4 seconds).
+
+=head2 VM Heap
+
+Displays some heap stats, updated during garbage collection. If, when a VM is
+selected, the VM Heap view says that heap updates are not enabled, click the
+"Show heap updates" button, located in the top-left toolbar. Back in the VM
+Heap view, click Cause GC to perform garbage collection and update the heap
+stats.
+
+=head2 Allocation Tracker
+
+In this view, you can track the memory allocation of each virtual machine. With
+a VM selected in the left pane, click Start Tracking, then Get Allocations to
+view all allocations since tracking started. The table below will be filled
+with all the relevant data. Click it again to refresh the list.
+
+=head2 Emulator Control
+
+With these controls, you can simulate special device states and activities. Features include:
+
+B<Telephony Status> change the state of the phone's Voice and Data plans (home,
+roaming, searching, etc.), and simulate different kinds of network Speed and
+Latency (GPRS, EDGE, UTMS, etc.).
+
+B<Telephony Actions> perform simulated phone calls and SMS messages to the
+emulator.
+
+B<Location Controls> send mock location data to the emulator so that you can
+perform location-aware operations like GPS mapping.
+
+To use the Location Controls, launch your application in the Android emulator
+and open DDMS. Click the Emulator Controls tab and scroll down to Location
+Controls. From here, you can:
+
+=over 3
+
+=item -
+
+Manually send individual longitude/latitude coordinates to the device.
+
+Click Manual, select the coordinate format, fill in the fields and click Send.
+
+=item -
+
+Use a GPX file describing a route for playback to the device.
+
+Click GPX and load the file. Once loaded, click the play button to playback the
+route for your location-aware application.
+
+When performing playback from GPX, you can adjust the speed of playback from
+the DDMS panel and control playback with the pause and skip buttons. DDMS will
+parse both the waypoints (<wpt>, in the first table), and the tracks (<trk>,
+in the second table, with support for multiple segments, <trkseg>, although they
+are simply concatenated). Only the tracks can be played. Clicking a waypoint in
+the first list simply sends its coordinate to the device, while selecting a
+track lets you play it.
+
+=item -
+
+Use a KML file describing individual placemarks for sequenced playback to the
+device.
+
+Click KML and load the file. Once loaded, click the play button to send the
+coordinates to your location-aware application.
+
+When using a KML file, it is parsed for a <coordinates> element. The value of
+which should be a single set of longitude, latitude and altitude figures. For
+example:
+
+<coordinates>-122.084143,37.421972,4</coordinates>
+
+In your file, you may include multiple <Placemark> elements, each containing a
+<coordinates> element. When you do so, the collection of placemarks will be
+added as tracks. DDMS will send one placemark per second to the device.
+
+B<Note:> DDMS does not support routes created with the
+<MultiGeometry><LineString>lat1, long1, lat2, long2,
+...</LineString></MultiGeometry> methods. There is also currently no support
+for the <TimeStamp> node inside the <Placemark>. Future releases may support
+timed placement and routes within a single coordinate element.
+
+=back
+
+=head2 File Explorer
+
+With the File Explorer, you can view the device file system and perform basic
+management, like pushing and pulling files. This circumvents using the adb
+push and pull commands, with a GUI experience.
+
+With DDMS open, select Device > File Explorer... to open the File Explorer
+window. You can drag-and-drop into the device directories, but cannot drag out
+of them. To copy files from the device, select the file and click the Pull File
+from Device button in the toolbar. To delete files, use the Delete button in the
+toolbar.
+
+If you're interested in using an SD card image on the emulator, you're still
+required to use the mksdcard command to create an image, and then mount it
+during emulator bootup. For example, from the /tools directory, execute:
+
+$ mksdcard 1024M ./img
+$ emulator -sdcard ./img
+
+Now, when the emulator is running, the DDMS File Explorer will be able to read
+and write to the sdcard directory. However, your files may not appear
+automatically. For example, if you add an MP3 file to the sdcard, the media
+player won't see them until you restart the emulator. (When restarting the
+emulator from command line, be sure to mount the sdcard again.)
+
+=head2 Screen Capture
+
+You can capture screen images on the device or emulator by selecting
+Device > Screen capture... in the menu bar, or press CTRL-S.
+
+=head2 Exploring Processes
+
+You can see the output of ps -x for a specific VM by selecting Device > Show
+process status... in the menu bar.
+
+=head2 Cause a GC to Occur
+
+Cause garbage collection to occury by pressing the trash can button on the
+toolbar.
+
+=head2 Running Dumpsys and Dumpstate on the Device (logcat)
+
+To run dumpsys (logcat) from Dalvik, select Device > Run logcat... in the menu
+bar.
+
+To run dumpstate from Dalvik, select Device > Dump device state... in the menu
+bar.
+
+=head2 Examine Radio State
+
+By default, radio state is not output during a standard logcat (it is a lot of
+information). To see radio information, either click
+Device > Dump radio state... or run logcat as described in Logging Radio
+Information.
+
+=head2 Stop a Virtual Machine
+
+You can stop a virtual machine by selecting Actions > Halt VM. Pressing this
+button causes the VM to call System.exit(1).
+
+=head1 KNOWN ISSUES
+
+If you connect and disconnect a debugger, ddms drops and reconnects the client
+so the VM realizes that the debugger has gone away. This will be fixed
+eventually.
+
+=head1 COPYRIGHT
+
+This manual page is licensed under the Apache License, Version 2.0.
+
+Copyright (C) 2013 www.linuxtopia.org
+
+Copyright (C) 2013 Jakub Adam <jakub.adam at ktknet.cz>
diff --git a/debian/rules b/debian/rules
index 184c174..18e64dd 100755
--- a/debian/rules
+++ b/debian/rules
@@ -4,6 +4,8 @@ include /usr/share/cdbs/1/class/javahelper.mk
 
 export CLASSPATH := androidsdk-common.jar:androidsdk-ddmlib.jar:androidsdk-ddmuilib.jar:androidsdk-sdkstats.jar:androidsdk-swtmenubar.jar:androidsdk-hierarchyviewerlib.jar:/usr/share/java/swt.jar:/usr/share/java/jfreechart.jar:/usr/share/java/jfreechart-swt.jar:/usr/share/java/org.eclipse.jface.jar:/usr/share/java/org.eclipse.core.commands.jar:/usr/share/java/org.eclipse.equinox.common.jar:/usr/share/java/guava.jar:/usr/share/java/kxml2.jar
 
+POD2MAN := pod2man --center "Android SDK Tools" -r "Debian"
+
 common-post-build-indep::
 	for BNDFILE in debian/*.bnd; do \
 		JARNAME=`basename $$BNDFILE .bnd`.jar; \
@@ -25,6 +27,8 @@ common-post-build-indep::
 	jar uf androidsdk-uiautomatorviewer.jar -C uiautomatorviewer/src/main/java images
 	jh_manifest -m com.android.uiautomator.UiAutomatorViewer androidsdk-uiautomatorviewer.jar
 
+	$(POD2MAN) -s 1 debian/ddms.pod ddms.1
+
 install/androidsdk-ddms::
 	mkdir -p debian/androidsdk-ddms/usr/share/icons/hicolor/128x128/apps
 	cp ddms/app/src/main/resources/images/ddms-128.png \
@@ -39,3 +43,6 @@ install/androidsdk-hierarchyviewer::
 	cp hierarchyviewer2/hierarchyviewer2lib/src/main/java/images/sdk-hierarchyviewer-16.png \
 		debian/androidsdk-hierarchyviewer/usr/share/icons/hicolor/16x16/apps/hierarchyviewer.png
 	chmod 644 debian/androidsdk-hierarchyviewer/usr/share/icons/hicolor/16x16/apps/hierarchyviewer.png
+
+clean::
+	rm -f ddms.1

-- 
androidsdk-tools packaging