We are currently migrating Bugzilla to GitHub issues.
Any changes made to the bug tracker now will be lost, so please do not post new bugs or make changes to them.
When we're done, all bug URLs will redirect to their equivalent location on the new bug tracker.

Bug 1637

Summary: README.android
Product: SDL Reporter: wboe <w.boeke>
Component: *don't know*Assignee: Ryan C. Gordon <icculus>
Status: RESOLVED FIXED QA Contact: Sam Lantinga <slouken>
Severity: minor    
Priority: P2 CC: gabomdq, philipp.wiesemann
Version: 2.0.0   
Hardware: All   
OS: Android (All)   
Attachments: Original file from www.libsdl.org/tmp/SDL/README.android, supposing that this is the latest

Description wboe 2012-11-09 03:44:01 UTC 
Hi, this is not really about bugs, only some remarks about the latest README.android file. Here we go..

The Instructions, after point 4:
A directory 'obj' has been created. Move this to some location and replace it with a symlink. Then other projects can use this symlink too, and the complete SDL lib does not have to be recompiled for each new project.

The sample wrapper class MyGame contains 2 methods that are actual no-ops. The class can be empty if you whish.

The sentence
  Then replace "SDLActivity" in AndroidManifest.xml with the name of your
  class, .e.g. "MyGame"
is not quite complete. The name in this file must be equal to the main java class, else the build will stop. The name used by the device where the app is installed is specified in build.xml, which is read by the ant tool, and should be different for each project. The name that the user sees on his device is specified in res/values/strings.xml.

The Eclipse IDE is not needed at all, it is an extra layer between you and the tools that do the actual work. The easiest way is:
  android create project
If this works you can re-use the project many times. From now on you need only 2 commands:
  ../../ndk-build
  ant debug install

Regarding the icons: the 3 directories res/drawable-hdpi etc can be replaced with 1 named res/drawable, where an icon file icon.png can be placed.

Actually, this README.android file is both too short and too long. It is too short to learn everything a newbee need to know about building Android apps with the SDK and the NDK. And it is too long because it contains information that an Android developer will know already.

Kind regards,
wboe
Comment 1 Philipp Wiesemann 2012-11-10 02:52:37 UTC 
With all the warnings is this file maybe also the documentation on SDL_ANDROID_BLOCK_ON_PAUSE could be extended to include some. Its functionality (which is currently enabled by default) may be confusing when porting programs (which already use SDL) from other platforms.

That is because even if programs cared about the "minimized" state and stopped rendering in this case they do often (I assume this) do not care about what happens if their main thread is just stopped while timers and worker threads continue. This may lead to a messed up state and timed out network connections (if they are not in worker threads) which may not be wanted if just doing a short telephone call on Android and then returning to the program.

Which means in such cases SDL_ANDROID_BLOCK_ON_PAUSE should be disabled to get a behaviour similar to the one on other platforms. Or use it and have to write some special cases in the program source to handle Android (e.g. put network code in worker thread, use a proper timer or stop it).
Comment 2 Philipp Wiesemann 2012-11-10 03:25:26 UTC 
The README.android currently (HG) mentions Android 2.0 while the AndroidManifest.xml sets "minSdkVersion" to "10" (under the comment with 2.1 which is wrong because this is 2.3).

The AndroidManifest.xml could be changed to have

<uses-sdk android:minSdkVersion="5" android:targetSdkVersion="10"/>

which would require Android 2.3 or higher to compile but would make the APK run on Android 2.0 too.

On the other hand README.Platforms mentions Android 2.1 (which would be 7) for some reason I do not know (yet).

The SDL_android.cpp uses "getExternalFilesDir" with JNI which is available since Android 2.2 [1] (which would be 8). But as long as the connected functionality is not used SDL should still work with Android 2.0. So maybe there could be a comment too or the minimum level could be raised to 8 everywhere.

[1] http://developer.android.com/reference/android/content/Context.html#getExternalFilesDir(java.lang.String)
Comment 3 Gabriel Jacobo 2012-11-16 04:37:17 UTC 
@Phillip, I initially had SDL_ANDROID_BLOCK_ON_PAUSE undefined by default precisely to imitate what the desktop version of the same app would do, which is keep going even if the user switches to a different program.
However, this is a mobile system and the paradigm is different here. On iOS, you right out don't have the chance to keep looping in the background (the system halts you), and blocking in this way is more effective for saving battery, and restarting your app immediately after the user comes back, instead of having to poll for a restore event.
Regarding timers, network connections, etc, you should do whatever you need to do with them when you get the minimize event which is designed to let you know that the app will be pausing.
Finally, the options are open to you, it's just a define, you can change it at will ;)

Regarding the main issue of this ticket, if you can submit a patch for the README I'll review it and apply it. Thanks!
Comment 4 wboe 2012-11-19 06:56:26 UTC 
Created attachment 993 [details]
Original file from www.libsdl.org/tmp/SDL/README.android, supposing that this is the latest

So this is a patch to a README file, which feels a bit strange, but Gabriel Jacobo asked for it.
Comment 5 Gabriel Jacobo 2012-11-21 03:28:51 UTC 
It's in http://hg.libsdl.org/SDL/rev/afb9be20f8d2 . Thanks!
Comment 6 Philipp Wiesemann 2013-03-10 07:45:36 UTC 
(In reply to comment #2)
> On the other hand README.Platforms mentions Android 2.1 (which would be 7)
> for some reason I do not know (yet).

I created bug #1748 to propose a patch with some changes to the README files and included a related change.