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...

We assume you already have Git installed. If you've never used Git, you will need to search the web on how to add git to the system from Apple Xcode, and then study on how to use git (look for material on https://mediawiki.org for git convention as practiced by MediaWiki programmers).

In the parent directory of your programming projects, run the following commands:

 git clone https://git.wikimedia.org/git/apps/android/wikipedia.git

Assuming the git clone operation worked, you will have a new folder representing the freshly cloned repository, "wikipedia".

It is recommended to rename the folder for the "wikipedia" repository to ensure you know which OS it's for (there's an iOS app by the name of "wikipedia", too, so it's good to have different folder names at the root of the repos).

 mv wikipedia/ android-wikipedia/

The Java SDK 7 or higher (aka. JDK) is needed to build Android apps. To test:

 javac -version

It's probably best to install the Android SDK separately from Android Studio -- instead of the bundle.

Install brew if you don't already have it. Instructions are at http://brew.sh.

Install Android SDK

 brew update
 brew doctor
 brew install android

Download the SDK Tools from http://developer.android.com/sdk/index.html#Other

Update your ~/.bash_profile file to set the $ANDROID_HOME variable to point to the 'sdk' folder contained in the compressed file you just extracted and to update your system path to point at some binaries.

 export ANDROID_HOME=/usr/local/opt/android-studio-sdk
 export PATH=$ANDROID_HOME/tools:$PATH

Source your your ~/.bash_profile

 source ~/.bash_profile

Now, and any time you open a new Terminal, the $ANDROID_HOME variable will be set automatically and you'll be able to run command line tools pertinent to Android software development, such as the tool aptly named "android".

Install the Android SDK components needed for the Wikipedia Android app:

 android update sdk -u --filter "tools,platform-tools,build-tools-21.1.1,android-21,extra-android-m2repository"

After you accept the licenses, this will download and install the necessary SDK components for you to build the app.

You can find more components via:

 android list sdk -e -a

Alternatively, you can use the GUI:

 android &

This will load a GUI tool called "Android SDK Manager" for managing the Android-related packages necessary for Android programming.

You may want to install some more packages from there.

It's usually best to run the app on real devices, but sometimes it's useful to use an emulator when a certain physical device is not available, like a different form factor (7", 10" tablet, ...).

If planning to use Android emulators, consider adding the "System Image" packages of various API levels in in the Android SDK Manager. Example:

• ARM EABI v7a System Image (API 21)

• Intel X86 Emulator Accelerator (HAXM installer)

If you've downloaded the Intel HAXM installer you're not done yet. You also need to run the installer. (Sometimes it's also useful to run it later again). You can find the dmg in $ANDROID_HOME/extras/intel/Hardware_Accelerated_Execution_Manager. Select a good memory limit. It depends on your machine. Some got it set to 2048 MB.

To set up actual emulators you'd want to run the following command in Terminal (or from Android Studio):

 android avd &

This will launch the Android Virtual Device Manager application where you can create different virtual machines with specs representative of devices in the wild. It's nice to be able to see how things work out on different screen sizes when you don't have lots of devices handy. To create a device, just go to the Device Definitions tab of Android Virtual Device Manager, click on one of the profiles, and then click "Create AVD". And in the ensuing dialog box set the Target to, for example, Android 4.4 - API Level 19, then click OK. You'll now see the virtual machine in the Android Virtual Devices tab. To make it work with HAXM (in the faster mode) chose a RAM setting <= as what you set when running the HAXM installer above. Also for newer system images chose 'Use Host GPU'.

If you see a warning like:

 HAX is not working and emulator runs in emulation mode

you may want to adjust the RAM settings. Also make sure you don't have both emulator options checked. Even though they are checkboxes, the two options 'Snapshot' and 'Use GPU' cannot be combined.

If instead you get:

 HAX is working and emulator runs in fast virt mode

Congrats! You should have a much faster emulator. :)

We've moved from Maven to Gradle builds. 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.) If you a trying out both the Maven build (from IntelliJ) and the Gradle build (from Android Studio or IntelliJ) a separate repo clone is recommended as to not confuse IntelliJ.

Yeah, nothing to do here since this project uses the Gradle wrapper that's stored in the Git repo. :) This also ensures that everyone has the same build environment.

Download and install the latest Android Studio IDE from http://developer.android.com/sdk/index.html#Other. Alternatively, you can find the latest beta also at http://tools.android.com/download/studio. Make sure you have 1.0.0 or newer.

Optional plugins for Android Studio 1.0.0 (= 135.*):

• Python Community Edition: use version 3.4.135.24.
• For JavaScript there is no plugin available, but you can get syntax highlighting with this

In the Quick Start or later from the File menu select "Import Project..." Select the folder you clone the git repo to (e.g. android-wikipedia)

If prompted, provide the path to the Android SDK: e.g. /usr/local/opt/android-sdk

The defaults on the next screen may need one tweak: check the radio button labeled "Use customizable gradle wrapper". (The Gradle wrapper files already exist in the android-wikipedia Git repository.) Click Next.

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.

In Android Studio go to Build > Make Project.

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.

Now, it's time to either run the app on an Android device or in an emulator. The emulator is slow due to being a full stack implementation. So most people seem to prefer to push apps to real Android devices.

To setup a configuration for a real Android device, first, on your Android device, go into Settings. Depending on your version of Android OS, you may need to take a different approach, but usually you can go to "About <phone/table></phone/table>" and tap repeatedly on the "Build number" cell until it tells you that you've put the device in developer mode. Now that developer mode is turned on, from the Settings app go into "Developer options" and turn on USB debugging (you may want to turn this feature off later on when you don't need it). Now, connect your Android device to your Mac. You'll be prompted with a message about allowing USB debugging for a particular RSA key fingerprint. Click OK to that.

Next, in Android Studio

1. Go to Run > Edit Configurations.
2. Click the "+" symbol and choose Android Application.
3. Choose "wikipedia" for the Module.
4. Change the Target Device from Emulator to USB Device.
5. Enter a name in the Name field, such as "Default Activity USB".
6. Click OK

One of IntelliJ's standout features 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.

If you wanted to use the emulator you can create another Run configuration.

Go to Run > Edit Configurations in IDEA/AS again, click the '+' symbol, choose Android Application, set the Module to 'wikipedia' again, and chose Show chooser dialog, set a name like Default Activity Prompt, and click OK. Then click the Play button or use the Run menu to get it started. Once the build is complete a dialog will let you chose the emulator to start or you can chose an already running one, which is much faster, of course. Then wait a while for everything to fire up and enjoy the emulator.

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"

In the IDEA/AS preferences (settings), go to Plugins and install the Checkstyle-IDEA inspection plugin. Then go to the Checkstyle setting and add a new configuration file: browse to the local file checkstyle.xml. Make sure you check the new configuration file so our checkstyle inspections are enabled and show up as IntelliJ errors in the code editor. Also check "Scan test classes" above.

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 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

Learn about Gerrit and how to submit patches in this short guide or the tutorial.

See pending/recent code reviews:

• Wikipedia app: https://gerrit.wikimedia.org/r/#/projects/apps/android/wikipedia,dashboards/default
• Java MW-API: https://gerrit.wikimedia.org/r/#/projects/apps/android/java-mwapi,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/