An IntelliJ template project for android developers, pre-configured to work with Robolectric, Roboguice, an other common, useful Android libraries.
This is a "template" IntelliJ project created to bootstrap Android development. We have included as many of our go-to tools and as much hard earned configuration knowledge as possible to aid new projects. This includes out-of-the-box support for robolectric, robojuice, C2DM, great-expectations, android source Jars, and other important libraries.
There is a lot of stuff in here, everything from android source jars to dependency injection; we acknowledge that your project might not want all of it. We encourage your project to remove whatever you don't want.
We make the following assumptions. Feel free to deviate but you will likely need to fix some things as you go.
Don't open IntelliJ yet.
Install Android platform tools, Android 2.3.3 with Google APIs, and the most recent Android with Google APIs (needed for Robolectric). You change the Android version for your project later.
android update sdk -u --filter platform-tools,android-10,addon-google_apis-google-10,extra-android-support,android-16,addon-google_apis-google-16
Create a local git repo for your new project, or create one on GitHub and clone it. http://help.github.com/create-a-repo/
Optionally, fork the robolectric repo on GitHub if you wish to use a fork for your project to make it easy to contribute changes back to robolectric. We recommend that you fork robolectric. Go to https://github.com/pivotal/robolectric and click the "Fork" button.
Clone the AndroidIntelliJStarter project, then add all of its code and setup to your new project's repo by running:
git clone git://github.com/pivotal/AndroidIntelliJStarter starter_tmp cd starter_tmp ./script/setup_project YourProjectName path_to_your_project_repo #or ruby script/setup_project ...This script will prompt you for a package name and a robolectric repo, both are optional.
Default package name: com.example.android.sampleapp
Default robolectric repo is the read-only offical robolectric repo: git://github.com/pivotal/robolectric.git
To make sure everything is OK, run tests for both Robolectric and your project:
cd path_to_your_project_repo && (cd submodules/robolectric && ant clean test) && ant clean test
Open YourProject in IntelliJ 10.5 or higher.
Import IntelliJ Settings: File => Import Settings => YourProject/support/IntellijSettings.jar. This will destroy your existing IntelliJ settings!
Notes:
In IntelliJ, Run Unit Tests, Robolectric Unit Tests, and launch StarterApp and make sure they work.
At least glance at the stuff below about robojuice, C2DM, gp and gpp, forking robolectric, etc.
Stuck? Keep reading!
Salvation lies within.
Don't open IntelliJ yet.
Download the latest Mac SDK: http://developer.android.com/sdk/index.html
Unzip the archive and move the android-sdk-macosx dir to ~/android-sdk-macosx. This project assumes that android lives in ~/android-sdk-macosx. You will need to fix paths in several places if you choose a different location.
Add the android tools to the PATH.
# Note: change .bash_profile to .bashrc or something else if needed echo 'export PATH="$PATH:$HOME/android-sdk-macosx/tools:$HOME/android-sdk-macosx/platform-tools"' >> $HOME/.bash_profile
Open a new Terminal window and run
android:
# in a new Terminal window: android
Use the "Android SDK and AVD Manager" to download all of the SDKs. This project assumes SDK v10 (2.3.3) with Google APIs. You can change this later.
To install:
Install other SDKs using this method.
Make at least one Virtual Device (emulator) for the SDK(s) you installed above. Instructions at http://developer.android.com/tools/devices/index.html
Note: This project assumes you have SDK 10 with Google APIs (2.3.3) installed. You can change this in
build.properties.
Don't open IntelliJ yet.
Before you can start, you have to have a git repo for your new project on your machine.
If you are using GitHub, to create a new repo for your project, create it on GitHub and clone it to your local machine.
If you are NOT using GitHub, just create a repo on your local machine for your project (i.e.
git init).
Optionally, if you are using
git pairon your project, create a .pairs file in your new project's repo and run
git pair.
Finally, clone
pivotal/AndroidIntelliJStarterbe sure to use the read-only URI to avoid accidentally pushing changes to it.
git clone git://github.com/pivotal/AndroidIntelliJStarter starter_tmp
setup_projectwill rename the files and file contents that need to be changed from AndroidIntelliJStarter to YourProject and copy/commit all of the files into your project's repo.
cd starter_tmp ./script/setup_project YourProject path_to_your_project_repo
This script will prompt you for a package name and a robolectric repo, both are optional.
com.example.android.sampleapp.
We recommend that you fork robolectric for your project. For details on how to set up your fork to easily sync with pivotal/robolectric, see "Open Source Robolectric" below.
Note that Robolectric unit test require SDK v10 (2.3.3) with Google APIs. If you do not install this SDK then you will not be able to run Robolectric's own test suite.
Open YourProject in IntelliJ 10.5 or higher.
Import support/IntellijSettings.jar to automatically configure your SDKs and other important settings:
File => Import Settings => YourProject/support/IntellijSettings.jar
If everything goes well everything will be fixed when IntelliJ restarts.
Something about your machine's configuration does not match our settings. Manually fix all using the following instructions. Likely issues include:
If these are not the issue keep going to the SDK sections below.
If 1.6 is not listed, add it:
Check your Android SDKs:
Your Android SDKs are listed here. You might need to add a few. Note that if you want to run Robolectric's own test suite you will need to add Google APIs (2.3.3). For example:
If you need SDKs that are not listed you will need to install it via the Android SDK and AVD Manager. See above.
You might need to fix the Module SDKs for YourProject and Robolectric:
We have included several libraries and configurations that we use on most projects. You are free to keep them or remove them.
By default this project uses Roboguice for dependency injection. https://github.com/roboguice/roboguice
Configure dependency injection in MySampleApplication.ApplicationModule and RobolectricTestRunnerWithInjection.TestApplicationModule.
RobolectricTestRunnerWithInjection is a test runner configured to use Roboguice. See StarterActivityWithRoboguiceTest for example usage.
We've included the Fest expectation matchers to provide Jasmine-style expectations to your project. The fest-android extensions are also included for simpler android-specific tests.
Further documentation at http://fest.easytesting.org/ and https://github.com/square/fest-android
We have added many handy Jars, such as apache commons, google's Guava, the Jackson JSON parsing libraries, and more. Check them out in
libs/main/and
libs/test-- keep them or delete them.
These Ruby scripts should make your life easier. Feel free to edit them. They assume ruby lives in
/usr/bin/rubyso you might need to edit their
#!/usr/bin/rubyif yours is different. Alternatively these scripts can be run with ruby explicitly:
ruby script/[the script].
Be sure to check out "Project Setup Script", above, for more details on many of these scripts.
script/gp-- "Git Pull" script. This pulls and rebases your project and robolectric.
script/gpp-- "Git Pull Push" script. Same as script/gp but also runs all tests in robolectric. and your project. If they pass it will
git push.
script/setup_project [YourProject] [path_to_your_project_repo]-- Copies AndroidIntelliJStarter into a project git repo, and gives the project a name of [YourProject].
script/set_package-- Change the Java package from the default to the provided package name.
script/init_git_repo-- create a new local git repository. Existing
.gitdirectory safely moved to
.git.bak.
In addition to the built-in Android
anttasks you will likely use the following additions often. You can chain them, such as
ant clean test. Feel free to edit
build.xmlto fit your needs.
ant clean-- deletes all output dirs
ant test-- executes the project tests
There are a couple of useful maven tasks:
mvn clean-- deletes all output dirs
mvn test-- executes the project tests
mvn install-- writes the target (your apk by default) to the local maven repo
Robolectric is open source and it continuously improves. We recommend that your project fork robolectric. By forking you have the freedom to choose when (if ever) to update to later versions of robolectric, make changes to your fork as needed, and contribute those changes back to pivotal/robolectric using the official github pull-request workflow.
The official Github workflow (http://help.github.com/fork-a-repo/) details how to merge another repo's code into your own fork, such as merging pivotal/robolectric into yourproject/robolectric:
Do the following once per machine:
# add pivotal/robolectric HEAD as an upstream remote cd submodules/robolectric git remote add upstream git://github.com/pivotal/robolectric.git
When you want to merge in upstream:
# merge pivotal/robolectric into your fork cd submodules/robolectric git fetch upstream git merge --no-commit upstream/master
Then:
Make a pull request: http://help.github.com/send-pull-requests/
If you started with the default (non-pushable submodule) robolectric, you can change your mind later and set up your project to use your own fork later by following these instructions.
.gitmodules -- delete the '[submodule "submodules/robolectric"]' section if present.
.git/config -- delete the '[submodule "robolectric"]' section if present.
Clean up git and directories
git rm --cached submodules/robolectric rm -rf submodules
After forking robolectric on Github, add a submodule that points to your robolectric repository:
git submodule add ***YOUR-GIT-REPOSITORY-URI-HERE*** submodules/robolectric git submodule init (cd submodules/robolectric && ant clean test)