Subproject reorganization, POM cleanup, etc.

Purpose of code changes on this branch:

The goal is to get everything working happily with both Maven, and Eclipse (via 
m2eclipse) without having to manually maintain duplicate project metadata in 
the pom.xml files and the .classpath/.project files. This patch finally 
achieves that.

The first thing that was necessary was to reorganize the PlayN subprojects and 
introduce proper subprojects for the Java and HTML backends. Otherwise the core 
depended on half a dozen GWT-related libraries, which Android projects then 
inherited, which cause major headaches when trying to build an Android app.

In addition to the introduction of html and java subprojects, the dependencies 
of the other subprojects were reordered. The dependency tree of the main playn 
subprojects now looks like the following:

playn-project
+- playn-webgl
+- playn-core
   +- playn-html (also depends on playn-webgl)
   +- playn-java
   +- playn-android
   +- playn-server
   +- playn-jbox2d

There are a few things to note there:

One, core depends on nothing else (it used to depend on jbox2d and webgl). This 
is the best situation to ensure that we don't inadvertently rely on code in 
core that will not be available in all backends. Core had a couple of such 
inadvertent dependencies, which have been moved into the appropriate subproject 
temporarily, but which need to be repackaged or otherwise further abstracted:

- gwtbox2d/src/playn/core/DebugDrawBox2D.java
- html/src/playn/core/AutoClientBundleWithLookup.java

(Once the DebugDrawBox2D thing is worked out, playn-jbox2d can also not depend 
on playn-core).

Two, nothing depends on playn-jbox2d by default. Projects that wish to use 
jbox2d have to actually add a dependency on that project to do so. Currently 
the peas sample does so.

Three, the HTML backend provides Flash support, since the HTML backend is 
really the GWT backend, and GWT handles both JavaScript and ActionScript code 
generation. I didn't see any benefit to splitting playn-html into playn-html 
and playn-flash, and it would require a bunch of duplication in the POMs.

The samples have also been necessarily split up, with separate subprojects for 
each backend. This is different than the way they used to be split up, which 
hackily included all of the backends *except* android in the core project and 
then referenced source code from the core project in a stub POM for other 
backends. Now there are actual subprojects for each backend and the source code 
and metadata that goes along with that project also lives in the appropriate 
backend subproject. One caveat is that the Java backend is combined with the 
core project. I didn't see a huge benefit to splitting it into a separate 
subproject, since the Java backend does not introduce any additional 
dependencies.

The hello sample project demonstrates this new organization:

hello-core:
src/playn/sample/hello/core/HelloGame.java
src/playn/sample/hello/core/Pea.java
src/playn/sample/hello/java/HelloGameJava.java

hello-android:
src/playn/sample/hello/android/HelloGameActivity.java

hello-html:
src/playn/sample/hello/flash/HelloGameFlash.java
src/playn/sample/hello/html/HelloGameHtml.java
src/playn/sample/hello/HelloGame.gwt.xml
src/playn/sample/hello/HelloGameFlash.gwt.xml
war/HelloGame.html
war/HelloGameFlash.html
war/WEB-INF/web.xml

When importing everything into Eclipse, a separate Eclipse project will be 
created for hello-core, hello-android, and hello-html. The hello-android 
project can be "Run as Android application" (modulo two caveats mentioned 
later), the hello-html project can be "Run as Web application" (to run in 
devmode) and "GWT Compile"d (to compile to JavaScript). Naturally, the 
hello-core project can be "Run as Java application", which is the recommended 
way to develop and debug.

I also changed the Maven artifact names from, e.g., core to playn-core. This 
means a full Maven dependency will look like 
com.googlecode.playn:playn-core:1.0. This has the benefit that the jar files 
will be named playn-core-1.0.jar, which I think is preferable to just 
core-1.0.jar, and it also makes the Eclipse projects playn-core instead of just 
core, which is definitely helpful.

It is now possible to build and deploy Android APK files directly from the 
command line:

% cd playn
% mvn install
% cd sample/hello/android
(start your android emulator or connect a device)
% mvn android:deploy

Non-Eclipse users rejoice!

The Ant build scripts have also been updated to better interoperate with the 
multiproject setup. One now runs Ant from the, e.g., sample/hello directory 
instead of the sample/hello/core directory. The same Ant targets work as before:

% cd playn
% ant install
% cd sample/hello
% ant run-java (builds and runs the game using the Java backend)
% ant run-devmode (builds and runs the game using the HTML backend in GWT 
devmode)
% ant run-html (compiles the game to JavaScript and serves it up via Jetty)

I will eventually be adding "ant deploy-anrdoid" which will do the same thing 
that "mvn deploy:android" does, for users that prefer Ant to Maven.

I will also endeavor in the future to enhance the Maven support so that the 
HTML backend can be compiled from the command line via Maven and packaged into 
a war file for easy deployment.

There remain a few niggles which we can hopefully be streamlined:

1. The sample html backend projects must manually be configured to be "Google 
Web Toolkit" projects. The GWT Eclipse Plugin does not auto-detect them in the 
way that the Google Android Eclipse plugin does. This may be something that can 
be fixed upstream.

2. The Maven Android plugin is flaky when running in Eclipse. It sometimes 
reports: "error executing dx 
command=[me.gladwell.android.tools.drivers.DexCommand@3e722f5d] 
(com.jayway.maven.plugins.android.generation2:maven-android-plugin:3.0.0-alpha-2
:generate-sources:default-generate-sources:generate-sources)    pom.xml line 41" 
but refreshing the project generally makes that go away.

3. If one wishes to test and deploy an Android project from Eclipse, they have 
to check out the Pythagoras library and have it in their Eclipse workspace. 
Otherwise the Google Android Plugin fails to include the Pythagoras code in the 
APK it generates. This might also be something we can get the plugin 
maintainers to fix, because it's not a configuration problem. The Maven Android 
plugin does the right thing with the Pythagoras code, and the Eclipse plugins 
are supposed to get everything they need from the Maven POMs.

That's about the size of it. Once this goes in, I'll update the checkout/build 
instructions and add addition instructions for people who prefer to use Maven 
or Ant to Eclipse.

When reviewing my code changes, please focus on:
http://code.google.com/r/samskivert-playn/source/detail?r=6831bd28dda48a9b4ad715
b837037c7f21fa61f0&name=backend-reorg

After the review, I'll merge this branch into:
/trunk
Original issue reported on code.google.com by samskiv...@gmail.com on 18 Aug 2011 at 4:39
fredsa / playn

Subproject reorganization, POM cleanup, etc. #19
