BearND has uploaded a new change for review. https://gerrit.wikimedia.org/r/180723
Change subject: Update README for Android Studio 1.0.0 ...................................................................... Update README for Android Studio 1.0.0 Change-Id: I6678f620564c569944675344806c8326e417af12 --- M README.mediawiki 1 file changed, 44 insertions(+), 141 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/apps/android/wikipedia refs/changes/23/180723/1 diff --git a/README.mediawiki b/README.mediawiki index e6c3210..ff5bbeb 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -4,165 +4,57 @@ 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... -=== Git === - -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/ - === Install Java SDK === The Java SDK 7 or higher (aka. JDK) is needed to build Android apps. To test: javac -version -=== Install Android SDK === +=== Install Android Studio and Android SDK === -It's probably best to install the Android SDK separately from Android Studio -- instead of the bundle. - -==== On a Mac you can use brew ==== -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 - -==== Other Platforms ==== -Download the SDK Tools from http://developer.android.com/sdk/index.html#Other - -==== All Platforms ==== -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. - -=== Optional: Install Android Emulator === - -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) - -You'll probably also want to install the HAXM installer package from the Extras category at the bottom. -* Intel X86 Emulator Accelerator (HAXM installer) - -Once you're satisfied that everything has been downloaded and installed, feel free to close the Android SDK Manager. - -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. :) - -=== Gradle and Android Studio === - -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. - -==== No need to install Gradle ==== - -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. - -==== Install Android Studio ==== - -Download and install the latest Android Studio IDE from http://developer.android.com/sdk/index.html#Other. +# 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. Alternatively, you can find the latest beta also at http://tools.android.com/download/studio. -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. -Optional plugins for Android Studio 1.0.0 (= 135.*): -* [http://plugins.jetbrains.com/plugin/7322?pr= Python Community Edition]: use version 3.4.135.24. +==== Check out the project ==== -* For JavaScript there is no plugin available, but you can get syntax highlighting with this -https://stackoverflow.com/questions/17137577/add-js-and-css-support-to-android-studio-project/17711474#17711474 -On MacOS the file is ~/Library/Preferences/AndroidStudioBeta/filetypes/Javascript.xml. +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. ==== Import as Gradle project into Android Studio ==== -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) +Now you should get the Import Project from Gradle dialog. -If prompted, provide the path to the Android SDK: e.g. /usr/local/opt/android-sdk +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 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. +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. -In Android Studio go to Build > Make Project. +==== Run / Debug the app ==== -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. +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'. -==== Run the app ==== - -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>" 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 -# Go to Run > Edit Configurations. -# Click the "+" symbol and choose Android Application. -# Choose "wikipedia" for the Module. -# Change the Target Device from Emulator to USB Device. -# Enter a name in the Name field, such as "Default Activity USB". -# Click OK - -Now up in the top right part of IDEA/AS you should see a green colored play button. Also if you go to the Run menu you should see an option to, for example "Default Activity USB". Use either option to pop the app onto your device and run it! - -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 - +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. -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. +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. ==== Logcat Configuration ==== @@ -174,12 +66,21 @@ * 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 ==== +==== Android Studio Plugins ==== -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. +* Checkstyle Configuration to see Checkstyle errors as you type + +In Android Studio preferences (settings), go to Plugins, click on the "Browse repositories..." button, and install the Checkstyle-IDEA inspection plugin. +Then go to the Checkstyle setting and add a new configuration file: click on the '+' in the upper pane, browse to the local file checkstyle.xml. +Make sure you activate the new configuration file by checking the check box next to it, so our checkstyle inspections are enabled and show up as IntelliJ errors in the code editor. Also check "Scan test classes" above. + +=== Gradle === + +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. ==== Useful Gradle commands ==== @@ -222,12 +123,14 @@ * 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 -=== Gerrit === +=== Contribute code via Gerrit === +Sorry, Github pull requests are currently not working. Learn about Gerrit and how to submit patches in this [http://www.mediawiki.org/wiki/Gerrit/Getting_started short guide] or the [http://www.mediawiki.org/wiki/Gerrit/Tutorial 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 +* 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 == Scripts == -- To view, visit https://gerrit.wikimedia.org/r/180723 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I6678f620564c569944675344806c8326e417af12 Gerrit-PatchSet: 1 Gerrit-Project: apps/android/wikipedia Gerrit-Branch: master Gerrit-Owner: BearND <bsitzm...@wikimedia.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
