annotate README.android @ 5067:61d53410eb41

Fixed bug #859 CREATE_SUBDIRS helps a lot if browsing HTML documentation in a file browser. ALWAYS_DETAILED_SEC makes sure everything has at least the automatic documentation like function prototype and source references. STRIP_FROM_PATH allows you to include only the relevant portions of the files' paths, cleaning up both the file list and directory tree, though you need to change the path listed here to match wherever you put SDL. ALIASES avoids some warnings generated by C:\source\svn.libsdl.org\trunk\SDL\src\joystick\darwin\10.3.9-FIX\IOHIDLib.h. It seems Apple uses a few commands which are not normally supported by Doxygen. BUILTIN_STL_SUPPORT adds support for parsing code which makes use of the standard template library. There isn't a lot of C++ in SDL (some in bwindow at least), but this still seems like a good idea. TYPEDEF_HIDES_STRUCT means that for code like this: typedef struct A {int B;} C; C is documented as a structure containing B instead of a typedef mapped to A. EXTRACT_ALL, EXTRACT_PRIVATE, EXTRACT_STATIC, EXTRACT_LOCAL_METHODS, EXTRACT_ANON_NSPACES and INTERNAL_DOCS make sure that _everything_ is documented. CASE_SENSE_NAMES = NO avoids potential conflicts when building documentation on case insensitive file systems like NTFS and FAT32. WARN_NO_PARAMDOC lets you know when you have documented some, but not all, of the parameters of a function. This is useful when you're working on adding such documentation since it makes partially documented functions easier to spot. WARN_LOGFILE writes warnings to a seperate file instead of mixing them in with stdout. When not running in quiet mode, these warnings can be hard to spot without this flag. I added *.h.in and *.h.default to FILE_PATTERNS to generate documentation for config.h.in and config.h.default. RECURSIVE tells doxygen to look not only in the input directory, but also in subfolders. EXCLUDE avoids documenting things like test programs, examples and templates which need to be documented separately. I've used EXCLUDE_PATTERNS to exclude non-source subdirectories that often find their way into source folders (such as obj or .svn). EXAMPLE_PATH lists directories doxygen will search to find included example code. So far, SDL doesn't really use this feature, but I've listed some likely locations. SOURCE_BROWSER adds syntax highlighted source code to the HTML output. USE_HTAGS is nice, but not available on Windows. INLINE_SOURCES adds the body of a function to it's documentation so you can quickly see exactly what it does. ALPHABETICAL_INDEX generates an alphabetical list of all structures, functions, etc., which makes it much easier to find what you're looking for. IGNORE_PREFIX skips the SDL_ prefix when deciding which index page to place an item on so you don't have everything show up under "S". HTML_DYNAMIC_SECTIONS hides the includes/included by diagrams by default and adds JavaScript to allow the user to show and hide them by clicking a link. ENUM_VALUES_PER_LINE = 1 makes enums easier to read by placing each value on it's own line. GENERATE_TREEVIEW produces a two frame index page with a navigation tree on the left. I have LaTeX and man pages turned off to speed up doxygen, you may want to turn them back on yourself. I added _WIN32=1 to PREDEFINED to cause SDL to output documentation related to Win32 builds of SDL. Normally, doxygen gets confused since there are multiple definitions for various structures and formats that vary by platform. Without this doxygen can produce broken documentation or, if you're lucky, output documentation only for the dummy drivers, which isn't very useful. You need to pick a platform. GENERATE_TAGFILE produces a file which can be used to link other doxygen documentation to the SDL documentation. CLASS_DIAGRAMS turns on class diagrams even when dot is not available. HAVE_DOT tells doxygen to try to use dot to generate diagrams. TEMPLATE_RELATIONS and INCLUDE_GRAPH add additional diagrams to the documentation. DOT_MULTI_TARGETS speeds up dot. OUTPUT_DIRECTORY, INPUT and other paths reflect the fact that this Doxyfile is intended to process src as well as include and is being run from a separate subdirectory. Doxygen produces several temporary files while it's running and if interrupted, can leave those files behind. It's easier to clean up if there aren't a hundred or so files in the same folder. I typically run doxygen in SDL/doxy and set the output directory to '.'. Since doxygen puts it's output in subfolders by type, this keeps things pretty well organised. You could use '../doc' instead and get the same results.
author Sam Lantinga <slouken@libsdl.org>
date Fri, 21 Jan 2011 12:57:01 -0800
parents 3811132c584f
children
rev   line source
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
1 ================================================================================
4726
9076cdb027af Cleanups.
Paul Hunkin <paul@bieh.net>
parents: 4725
diff changeset
2 Simple DirectMedia Layer for Android
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
3 ================================================================================
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
4
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
5 Requirements:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
6
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
7 Android SDK
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
8 http://developer.android.com/sdk/index.html
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
9
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
10 Android NDK r4 or later
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
11 http://developer.android.com/sdk/ndk/index.html
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
12
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
13
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
14 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
15 How the port works
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
16 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
17
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
18 - Android applications are Java-based, optionally with parts written in C
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
19 - As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
20 the SDL library
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
21 - This means that your application C code must be placed inside an android
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
22 Java project, along with some C support code that communicates with Java
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
23 - This eventually produces a standard Android .apk package
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
24
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
25 The Android Java code implements an "activity" and can be found in:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
26 android-project/src/org/libsdl/app/SDLActivity.java
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
27
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
28 The Java code loads your game code, the SDL shared library, and
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
29 dispatches to native functions implemented in the SDL library:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
30 src/SDL_android.cpp
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
31
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
32 Your project must include some glue code that starts your main() routine:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
33 src/main/android/SDL_android_main.cpp
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
34
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
35
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
36 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
37 Building an app
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
38 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
39
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
40 Instructions:
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
41 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
42 2. Move this SDL directory into the <project>/jni directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
43 3. Place your application source files in the <project>/jni/src directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
44 4. Edit <project>/jni/src/Android.mk to include your source files
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
45 5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
46
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
47 If you want to use the Eclipse IDE, skip to the Eclipse section below.
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
48
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
49 6. Edit <project>/local.properties to point to the Android SDK directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
50 7. Run 'ant debug' in android/project. This compiles the .java and eventually
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
51 creates a .apk with the native code embedded
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
52 8. 'ant install' will push the apk to the device or emulator (if connected)
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
53
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
54 Here's an explanation of the files in the Android project, so you can customize them:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
55
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
56 android-project/
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
57 AndroidManifest.xml - package manifest, do not modify
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
58 build.properties - empty
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
59 build.xml - build description file, used by ant
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
60 default.properties - holds the ABI for the application, currently android-4 which corresponds to the Android 1.6 system image
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
61 local.properties - holds the SDK path, you should change this to the path to your SDK
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
62 jni/ - directory holding native code
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
63 jni/Android.mk - Android makefile that includes all subdirectories
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
64 jni/SDL/ - directory holding the SDL library files
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
65 jni/SDL/Android.mk - Android makefile for creating the SDL shared library
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
66 jni/src/ - directory holding your C/C++ source
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
67 jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
68 res/ - directory holding resources for your application
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
69 res/drawable-* - directories holding icons for different phone hardware
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
70 res/layout/main.xml - place holder for the main screen layout, overridden by the SDL video output
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
71 res/values/strings.xml - strings used in your application, including the application name shown on the phone.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
72 src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
73
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
74
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
75 ================================================================================
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
76 Additional documentation
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
77 ================================================================================
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
78
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
79 The documentation in the NDK docs directory is very helpful in understanding the build process and how to work with native code on the Android platform.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
80
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
81 The best place to start is with docs/OVERVIEW.TXT
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
82
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
83
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
84 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
85 Using Eclipse
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
86 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
87
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
88 First make sure that you've installed Eclipse and the Android extensions as described here:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
89 http://developer.android.com/sdk/eclipse-adt.html
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
90
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
91 Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
92 * File -> New -> Other
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
93 * Select the Android -> Android Project wizard and click Next
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
94 * Enter the name you'd like your project to have
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
95 * Select "Create project from existing source" and browse for your project directory
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
96 * Make sure the Build Target is set to Android 1.6
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
97 * Click Finish
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
98
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
99
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
100 ================================================================================
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
101 Loading files and resources
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
102 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
103
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
104 NEED CONTENT
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
105
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
106
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
107 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
108 Troubleshooting
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
109 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
110
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
111 You can create and run an emulator from the Eclipse IDE:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
112 * Window -> Android SDK and AVD Manager
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
113
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
114 You can see if adb can see any devices with the following command:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
115 adb devices
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
116
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
117 You can see the output of log messages on the default device with:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
118 adb logcat
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
119
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
120 You can push files to the device with:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
121 adb push local_file remote_path_and_file
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
122
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
123 You can push files to the SD Card at /sdcard, for example:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
124 adb push moose.dat /sdcard/moose.dat
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
125
4976
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
126 You can see the files on the SD card with a shell command:
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
127 adb shell ls /sdcard/
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
128
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
129 You can start a command shell on the default device with:
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
130 adb shell
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
131
4975
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
132 You can do a clean build with the following commands:
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
133 ndk-build clean
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
134 ndk-build
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
135
4973
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
136 You can see the complete command line that ndk-build is using by passing V=1 on the command line:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
137 ndk-build V=1
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
138
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
139 If your application crashes in native code, you can use addr2line to convert the addresses in the stack trace to lines in your code.
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
140
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
141 For example, if your crash looks like this:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
142 I/DEBUG ( 31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
143 I/DEBUG ( 31): r0 00000000 r1 00001000 r2 00000003 r3 400085d4
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
144 I/DEBUG ( 31): r4 400085d0 r5 40008000 r6 afd41504 r7 436c6a7c
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
145 I/DEBUG ( 31): r8 436c6b30 r9 435c6fb0 10 435c6f9c fp 4168d82c
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
146 I/DEBUG ( 31): ip 8346aff0 sp 436c6a60 lr afd1c8ff pc afd1c902 cpsr 60000030
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
147 I/DEBUG ( 31): #00 pc 0001c902 /system/lib/libc.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
148 I/DEBUG ( 31): #01 pc 0001ccf6 /system/lib/libc.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
149 I/DEBUG ( 31): #02 pc 000014bc /data/data/org.libsdl.app/lib/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
150 I/DEBUG ( 31): #03 pc 00001506 /data/data/org.libsdl.app/lib/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
151
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
152 You can see that there's a crash in the C library being called from the main code. I run addr2line with the debug version of my code:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
153 arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
154 and then paste in the number after "pc" in the call stack, from the line that I care about:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
155 000014bc
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
156
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
157 I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
158
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
159 You can add logging to your code to help show what's happening:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
160
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
161 #include <android/log.h>
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
162
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
163 __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
164
4974
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
165 If you need to build without optimization turned on, you can create a file called "Application.mk" in the jni directory, with the following line in it:
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
166 APP_OPTIM := debug
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
167
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
168
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
169 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
170 Known issues
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
171 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
172
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
173 - SDL audio (although it's mostly written, just not working properly yet)
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
174 - TODO. I'm sure there's a bunch more stuff I haven't thought of