Android + NDK tips, part 2: Android project directory structure

An Android project folder is pretty cluttered. Most of the files and directory structure are determined by Eclipse and Android conventions, and many of the files and folders are auto-generated so there is nothing you can do about the clutter.

Below I describe the folder structure of an Android project. Please note that the terms "auto-generated" and "generated" are not the same. Auto-generated files are generated automatically on-demand, so you can safely delete them and they need not be checked-in to source control. Generated files are created by tools, but you can't delete them because they will not be regenerated. Auto-generated folders may contain content that is not auto-generated, so they are not always safe to delete.

Directory name   Purpose
--------------   -------
src              Conventional location for Android Java source code*
jni              Conventional location for C/C++ source code**
res              Conventional location for Android XML resource files
res/layout       Conventional location for dialog layouts
res/values       Conventional location for strings (to support internationalization)
res/drawable     Conventional location for bitmaps and other drawables
res/drawable-*   Auto-generated by Eclipse to hold different bitmaps for different screen densities
assets           Auto-generated by Eclipse for files to store in your *.apk (use AssetManager to read)
bin              Auto-generated by Eclipse to hold the *.apk, Java *.class files and other output files
gen              Auto-generated by Eclipse or vs-android to hold generated Java files
libs             Auto-generated by ndk-build to hold lib*.so file(s)
obj              Auto-generated by ndk-build to hold C/C++ object files

* Java package and class names are required to match the directory structure. A class named com.foo.Thing must be located at src/com/foo/Thing.java
** However, C/C++ source code can be placed anywhere you want

File name               Purpose
---------               -------
.classpath              Unsure, may help find Java dependencies. Generated by Eclipse when making a project.
.project                Generated by Eclipse to hold the project's name.*
AndroidManifest.xml     Specifies App's icon, required Android version, and a list of all activities.
default.properties      Unknown (generated)**
project.properties      Unknown (generated)**
proguard.cfg            Unknown (generated). May be related to Java obfuscation***
local.properties        Auto-generated to hold the location of the Android SDK on the current machine.
jni/Android.mk          sub-makefile that describes the C++ static libraries and *.so files you want to build
jni/Application.mk      contains settings that apply to all the C/C++ code 
                        (processor type, API level, standard library, project-wide compiler options)
build.xml               Unknown (required by vs-android only)
                        Note: in vs-android samples, the .* files are in the parent folder of 
                        everything else. But personally I have reconfigured my project so that these files 
                        are in the same folder as the files above.
(projname).vcxproj      vs-android project file
(projname).vcxproj.filters vs-android secondary project file****
(projname).sln          Visual studio solution file
(projname).suo          Auto-generated by Visual Studio for local user settings
(projname).vcxproj.user Auto-generated by Visual Studio for local user settings (one file is not enough?!)
(projname).sdf          Auto-generated by vs-android or VS. Probably a C++ symbol database (SQL Server Compact)

* .project is the Eclipse analogue of a Visual Studio project file, sort of, but it doesn't contain a list of the files that are in the project; in Eclipse, everything in the directory tree is implicitly part of the project. The project name is stored in the .project file, but as far as I can tell, this name is only cosmetic; it is not used in the output *.apk.
** default.properties or project.properties merely repeats the target SDK version from AndroidManifest.xml. A comment in the file claims the file is automatically generated, but apparently it is generated only once (on project creation). Eclipse will barf with a series of NullReferenceExceptions if the file is missing. For some reason there are two possible names for it; some projects use one name, others use the other name.
*** ProGuard is an obfuscation tool. I didn't ask for obfuscation, but Eclipse created proguard.cfg anyway.
**** *.vcxproj.filters specifies how files will be arranged into "Filters" (tree nodes that look like folders) in Visual Studio. I can't imagine why this information is not simply stored in the *.vcxproj file.

• Part 3: the actual tips