See also https://git.wikimedia.org/summary/apps%2Fandroid%2Fjava-mwapi.git
These instructions should help you download the Wikipedia for Android source code and get the latest version running in an emulator or on a real Android device. Some of the steps assume you are using bash but should be easily translatable for other shells as well. We've written theses instructions initially for OS X but most should also work on Linux and Windows. But anyway, here we go for those who enjoy a fun side project for a good cause...
The Java SDK 7 or higher (aka. JDK) is needed to build Android apps. To test:
javac -version
- Download Android Studio from http://developer.android.com/sdk/index.html and follow the instructions there. Make sure you have 1.0.0 or newer.
- Install Android Studio
- Start Android Studio and run the setup wizard.
- Standard installation is fine.
- Accept licenses
- Installation will take a while.
Now that Android Studio is set up, check out our project, either from Android Studio or command line. In Android Studio the Quick Start screen will give you the option to "Check out project from Version Control", choose Git, then https://git.wikimedia.org/git/apps/android/wikipedia.git for the repository URL.
We usually name the folder android-wikipedia since there is also an iOS project.
Now you should get the Import Project from Gradle dialog.
If not you can select "Import Project..." from the File menu, then select the folder you cloned the git repo to (e.g. android-wikipedia)
The defaults on the next screen should be fine: "Use default gradle wrapper (recommended)". Click Next.
If you see a pop-up in the upper right "Frameworks detected: Android framework is detected in the project" click on the Configure link. If you are missing the Android support libraries please note that Gradle pulls them from the local Android SDK installation if the extra-android-m2repository package is installed.
Once the import is complete, you can change the build variant to devDebug but leaving it at alphaDebug is fine, too. To do so see the Build Variants tab on the left hand side of Android Studio. If you don't see any tabs on the side click on the button in the lower left, which looks like a computer display.
Android Studio generates a run configuration automatically now. So, all you have to do to run the app is to click on the green play or debug button in the middle of the toolbar, next to the name of the run configuration. If you need more run configurations go to Run > Edit Configurations again, click the '+' symbol, choose Android Application, set the Module to 'wikipedia'.
One of Android Studios's standout features it inherited from IntelliJ is debugging. If you want to do that, you just need to click the Debug (green bug) button. To set breakpoints in your code, as with other IDEs, click in the gutter to the left of the source code in the IDE and notice that a little red circle is added. For example, if you set a breakpoint in the first line of public CommunicationBridge(final WebView webView, final String baseURL) in CommunicationBridge.java -
this.webView = webView;
- you'll get a glimpse into what actually happens the moment after tapping on an article title from search results. With the debugger, you can step through the code one line at a time, jump over methods, manipulate variables to see what would happen, and so on. Refer to online documentation to learn more about how the debugger works.
To debug anything inside the WebView (JavaScript, CSS, ...), you can connect to the app via Google Chrome on your desktop by entering the address
chrome://inspect/#devices
Then click on the topmost "inspect" link under "WebView in org.wikipedia". From there you can debug the WebView side like any other web site in Chrome.
After starting the project you'll likely notice a torrent of messages in the logcat window, and so it can help to setup a filter to cut down on those messages.
- At the top of the window, click on the "No Filters" drop-down list and select "Edit Filter Configuration"
- Change the name to something more meaningful ("org.wikipedia" for example)
- In the text field "by Package Name" enter "org.wikipedia"
- Because the log level can be changed on the main interface, it may be helpful to leave the level set to "Verbose"
- Select "OK"
- Checkstyle Configuration to see Checkstyle errors as you type
We've moved from Maven to Gradle builds. (The Maven pom.xml file is obsolete now, and only used by Jenkins to run the Checkstyle check.) The Gradle build works best in combination with Android Studio but it should work with IntelliJ as well but we don't test/support it anymore. (Android Studio is based on IntelliJ Community Edition.) No need to install Gradle, since this project uses the Gradle wrapper that's stored in the Git repo. This also ensures that everyone has the same Gradle version.
If you prefer command line use the wrapper script in the root of the repo:
./gradlew
To run a clean debug build:
./gradlew -q clean assembleDevDebug
You can skip the clean part usually, which makes it much faster (from 1m:05s to 7s on my box):
./gradlew -q assembleDevDebug
To install build on device/emulator:
./gradlew -q installDevDebug
To see ProGuard output: ./gradlew clean --info proguardDevRelease
To run tests:
./gradlew wikipedia:connectedAndroidTestDevDebug
This might take some time. The output will contain an HTML page with nicely formatted test results
Refresh dependencies (usually not needed): ./gradlew --refresh-dependencies
List dependencies:
./gradlew wikipedia:dependencies --configuration compile
Instead of "DevDebug" you can also use other build variants like "AlphaDebug", "BetaDebug", or "ProdDebug". Note that to use the "Release" build type you need to have a keystore and a properties file set up, see the end of the wikipedia/build.gradle file for hints.
More info: http://developer.android.com/sdk/installing/studio-build.html
- Alpha releases: https://android-builds.wmflabs.org (happen automatically on the half hour mark after code gets merged to master)
- Beta releases: https://play.google.com/store/apps/details?id=org.wikipedia.beta
- Production releases: https://play.google.com/store/apps/details?id=org.wikipedia
Sorry, Github pull requests are currently not working. Learn about Gerrit and how to submit patches in this short guide or the tutorial.
See pending/recent code reviews:
- Wikipedia Android app: https://gerrit.wikimedia.org/r/#/projects/apps/android/wikipedia,dashboards/default
- Java MediaWiki-API: https://gerrit.wikimedia.org/r/#/projects/apps/android/java-mwapi,dashboards/default
- MobileApp MediaWiki extension: https://gerrit.wikimedia.org/r/#/projects/mediawiki/extensions/MobileApp,dashboards/default
Theses scripts are for certain situations. The results of these scripts get added to version control, so they are not needed for building the app.
The various CSS files for this project are generated by the (mainly *.less) files found in the MobileApp MediaWiki extension. Gerrit or Github. You'll need a MediaWiki installation, Mediawiki-vagrant recommended, to run generate this.
in vagrant directory:
vagrant enable-role mobileapp vagrant provision
That will give you a mediawiki/extensions/MobileApp which will be a git repo. Next step is to change the url in (this repo/)scripts/make-css-assets.bash script to point to 127.0.0.1:8080/w instead of the bits url then run the script, and test.
Portions of JavaScript code run inside the WebView component that displays articles. This code is prepackaged using a [Grunt-js](http://gruntjs.com/getting-started), which must be re-run every time the master .js files are edited before building.
Preparing:
First, install the Grunt CLI tool:
npm install -g grunt-cli
Install dependencies for packaging:
cd www npm install
Building:
cd www grunt
This will produce output files under wikipedia/assets which will be included in the .apk.
You can also have grunt run continuously, watching the effected files for updates and running the build tasks automatically. This might be useful.
cd www grunt watch ... update files ...
Many of our icons are maintained as SVG originals, rasterized to PNG at the various output resolutions via a script. This rasterization is not part of the main build process, so needs to be re-run when adding new icons.
Install sh python module:
sudo easy_install sh
Ensure you have librsvg and the 'rsvg-convert' command:
- On Ubuntu, run "sudo apt-get install librsvg2-bin"
- On Mac OS X using Homebrew, run "brew install librsvg"
- On Ubuntu, run "sudo apt-get install imagemagick"
- On Mac OS X using Homebrew, run "brew install imagemagick"
- On Ubuntu, run "sudo apt-get install pngcrush"
- On Mac OS X using Homebrew, run "brew install pngcrush"
python scripts/convert-icons.py
Original files from icon-svgs/*/*.svg are rendered and copied into the res/ subdirectories. Note that they are not automatically added to git!
sudo pip install unicodecsv sudo pip install jinja2
cd scripts python make-templates.py mv *.java ../wikipedia/src/main/java/org/wikipedia/staticdata/