SETUP.md

   1
   2 If you want to start help developing ownCloud please follow the [contribution guidelines][0] and observe these instructions.
   3
   4 If you have any problems, start again with 1) and work your way down. If something still does not work as described here, please open a new issue describing exactly what you did, what happened, and what should have happened.
   5
   6 ### 1. Fork and download android/develop repository:
   7
   8 NOTE: You must have git in your environment path variable to perform the next operations.
   9
  10 * Navigate to https://github.com/owncloud/android, click fork.
  11 * Clone your new repo: "git clone git@github.com:YOURGITHUBNAME/android.git"
  12 * Move to the project folder with "cd android"
  13 * Checkout remote develop branch: "git checkout -b develop remotes/origin/develop"
  14 * Pull changes from your develop branch: "git pull origin develop"
  15 * Make official ownCloud repo known as upstream: "git remote add upstream git@github.com:owncloud/android.git"
  16 * Make sure to get the latest changes from official android/develop branch: "git pull upstream develop"
  17
  18 At this point you can continue using different tools to build the project. Section 2, 3, 4, 5 and 6 describe some of the existing alternatives.
  19
  20 ### 2. Building with Ant:
  21
  22 NOTE: You must have the Android SDK 'tools/', and 'platforms-tools/' folders in your environment path variable.
  23
  24 * Resolve necessary dependencies running:
  25     - Windows: "setup_env.bat ant"
  26     - Mac OS/Linux: "./setup_env.sh ant"
  27 * Run "ant clean".
  28 * Run "ant debug" to generate a debuggable version of the ownCloud app.
  29
  30 ### 3. Building with console/maven:
  31
  32 NOTE: You must have mvn (version >= 3.1.1) in your environment path. Current Android 'platforms-tools' need to be installed.
  33
  34 Download/install Android plugin for Maven, then build ownCloud with mvn:
  35
  36 * Resolve necessary dependencies running:
  37     - Windows: "setup_env.bat maven"
  38     - Mac OS/Linux: "./setup_env.sh maven"
  39 * cd ..
  40 * git clone https://github.com/mosabua/maven-android-sdk-deployer.git
  41 * cd maven-android-sdk-deployer
  42 * mvn -pl com.simpligility.android.sdk-deployer:android-19 -am install
  43 * cd ../android/owncloud-android-library
  44 * mvn install
  45 * cd ..
  46
  47 Now you can create ownCloud APK using "mvn package" and find it as ownCloud.apk under the target
  48
  49 ### 4. Building with Gradle:
  50
  51 * Complete the setup of project properties running:
  52     - Windows: "setup_env.bat gradle"
  53     - Mac OS/Linux: "./setup_env.sh gradle"
  54 * Open a terminal and go to the "android" directory that contains the repository.
  55 * Run the 'clean' and 'build' tasks using the Gradle wrapper provided:
  56     - Windows: gradlew.bat clean build
  57     - Mac OS/Linux: ./gradlew clean build
  58 * You can find the generated apk file in android/build/outputs/apk
  59
  60 ### 5. Building with Eclipse:
  61
  62 NOTE: You must have the Android SDK 'tools/', and 'platforms-tools/' folders in your environment path variable.
  63
  64 * Resolve necessary dependencies running:
  65     - Windows: "setup_env.bat ant"
  66     - Mac OS/Linux: "./setup_env.sh ant"
  67     * Open Eclipse and create new "Android Project from Existing Code". Choose android/actionbarsherlock/library as root.
  68 * Clean project and compile.
  69 * If any error appears, check the project properties; in the 'Android' section, API Level should be greater or equal than 14.
  70 * Make sure android/actionbarsherlock/library/bin/library.jar was created.
  71 * Create a new "Android Project from Existing Code". Choose android/owncloud-android-library as root.
  72 * Clean project and compile.
  73 * If any error appears, check the project properties; in the 'Android' section, API Level should be 19 or greater.
  74 * Make sure android/owncloud-android-library/bin/classes.jar was created.
  75 * Import ownCloud Android project.
  76 * Clean project and compile.
  77 * If any error appears, check the project properties of owncloud-android project; in the 'Android' section:
  78     - API Level should be 19 or greater.
  79     - Two library projects should appear referred in the bottom square: actionbarsherlock/library and owncloud-android-library. Add them if needed.
  80 * After those actions you should be good to go. HAVE FUN!
  81
  82 NOTE: Even though API level is set to 19, APK also runs on older devices because in AndroidManifest.xml minSdkVersion is set to 8.
  83
  84 ### 6. Building with Android Studio:
  85
  86 * Complete the setup of project properties running:
  87     - Windows: "setup_env.bat gradle"
  88     - Mac OS/Linux: "./setup_env.sh gradle"
  89 * Select 'Open Project...'. The file chooser will show an Android face as the folder icon. Select
  90   it to open the project.
  91 * To build the project, follow the guidelines shown on [4. Building with Gradle][2].
  92
  93 ### 7. Create pull request:
  94
  95 NOTE: You must sign the [Contributor Agreement][1] before your changes can be accepted!
  96
  97 * Commit your changes locally: "git commit -a"
  98 * Push your changes to your GitHub repo: "git push"
  99 * Browse to https://github.com/YOURGITHUBNAME/android/pulls and issue pull request
 100 * Click "Edit" and set "base:develop"
 101 * Again, click "Edit" and set "compare:develop"
 102 * Enter description and send pull request.
 103
 104 ### 8. Create another pull request:
 105
 106 To make sure your new pull request does not contain commits which are already contained in previous PRs, create a new branch which is a clone of upstream/develop.
 107
 108 * git fetch upstream
 109 * git checkout -b my_new_develop_branch upstream/develop
 110 * If you want to rename that branch later: "git checkout -b my_new_develop_branch_with_new_name"
 111 * Push branch to server: "git push -u origin name_of_local_develop_branch"
 112 * Use GitHub to issue PR
 113
 114
 115 [0]: https://github.com/owncloud/android/blob/master/CONTRIBUTING.md
 116 [1]: http://owncloud.org/about/contributor-agreement/
 117 [2]: https://github.com/owncloud/android/blob/master/SETUP.md#4-building-with-gradle