README.md

   1 ## Why another Superuser?
   2 * Superuser should be open source. It's the gateway to root on your device. It must be open for independent security analysis. Obscurity (closed source) is not security.
   3 * Superuser should be NDK buildable. No internal Android references.
   4 * Superuser should also be AOSP buildable for those that want to embed it in their ROM.
   5 * Superuser should also be AOSP _embeddable_, meaning a ROM can easily embed it into their Settings app.
   6 * Maintenance and updates on both the market and source repositories should be timely.
   7 * I want to be able to point users of my app to a Superuser solution that I wrote, that I know works, and that I can fix if something is wrong.
   8 * Handle multiuser (4.2+) properly
   9 * Handle concurrent su requests properly
  10
  11 ## Translations
  12
  13 Translations are very much appreciated, but please do not submit translations on Github! Instead, use the review submission process on [CyanogenMod's gerrit instance](http://review.cyanogenmod.org/#/q/status:open,n,z).
  14
  15
  16
  17 ## Checking out the source
  18
  19 You'll need the "Widgets" dependency.
  20
  21 * $ mkdir /path/to/src
  22 * $ cd /path/to/src
  23 * $ git clone git://github.com/koush/Superuser
  24 * $ git clone git://github.com/koush/Widgets
  25
  26 These repositories do not keep the actual projects in the top level directory.
  27 This is because they contain tests, libs, and samples.
  28
  29 Make sure the SDK Platform for API 19 is installed, through the Android SDK Manager.  Install NDK Revision 9b from [here](http://developer.android.com/tools/sdk/ndk/index.html).
  30
  31 ## Eclipse
  32
  33 In Eclipse, import Widgets/Widgets and Superuser/Superuser. It should Just Work (TM).
  34
  35 ## Ant
  36
  37 * $ mkdir /path/to/src
  38 * $ cd /path/to/src
  39 * $ cd Superuser/Superuser
  40
  41 In this directory, create a file called local.properties. This file is used by ant for custom properties. You need to specify the location of the ndk directory and your keystore parameters:
  42
  43 ```
  44 ndk.dir=/Users/koush/src/android-ndk
  45 key.store=/Users/koush/.keystore
  46 key.alias=mykey
  47 ```
  48
  49 If you do not have a release key yet, [create one using keytool](http://developer.android.com/tools/publishing/app-signing.html).
  50
  51 Set up your SDK path (this is the directory containing platform-tools/, tools/, etc.):
  52
  53 * $ export ANDROID_HOME=/Users/koush/src/sdk
  54
  55 Then you can build:
  56
  57 * $ ant release
  58
  59 Outputs:
  60 * bin/update.zip - Recovery installable zip
  61 * bin/Superuser-release.apk - Superuser Android app
  62 * libs/armeabi/su - ARM su binary
  63 * libs/x86/su - x86 su binary
  64 * libs/mips/su - MIPS su binary
  65
  66 ## Building the su binary
  67
  68 You can use ant as shown above, to build the binary, but it can also be built without building the APK.
  69
  70 Make sure you have the android-ndk downloaded with the tool "ndk-build" in your path.
  71
  72 * $ cd /path/to/src/
  73 * $ cd Superuser/Superuser
  74 * $ ndk-build
  75
  76 The su binary will built into Superuser/Superuser/libs/armeabi/su.
  77
  78
  79
  80 ## Building with AOSP, CyanogenMod, etc
  81
  82 ROM developers are welcome to distribute the official Superuser APK and binary that I publish. That will
  83 allow them to receive updates with Google Play. However, you can also build Superuser as part of your
  84 build, if you choose to.
  85
  86 There are two ways to include Superuser in your build. The easiest is to build the APK as a separate app.
  87 To do that, simply add the local_manifest.xml as described below. The second way is by embedding it
  88 into the native Android System Settings.
  89
  90 #### Repo Setup
  91 Add the [local_manifest.xml](https://github.com/koush/Superuser/blob/master/local_manifest.xml) to your .repo/local_manifests
  92
  93 #### Configuring the Package Name
  94 The Superuser distributed on Google Play is in the package name com.koushikdutta.superuser.
  95 To prevent conflicts with the Play store version, the build process changes the package
  96 name to com.thirdparty.superuser. You can configure this value by setting the following
  97 in your vendor makefile or BoardConfig:
  98
  99 ```
 100 SUPERUSER_PACKAGE := com.mypackagename.superuser
 101 ```
 102
 103 #### Advanced - Embedding Superuser into System Settings
 104
 105 You will not need to change the package name as described above. Superuser will simply go
 106 into the com.android.settings package.
 107
 108 First, in a product makefile (like vendor/cm/config/common.mk), specify the following:
 109
 110 ```
 111 SUPERUSER_EMBEDDED := true
 112 ```
 113
 114 To modify packages/apps/Settings, you will need this [patch](http://review.cyanogenmod.org/#/c/32957/2//COMMIT_MSG,unified).
 115 The patch simply references the sources checked out to external/koush and makes changes
 116 to XML preference files and the AndroidManifest.xml. It is a very minimal change.
 117