1.2.0 release

CHANGELOG.md

@@ -0,0 +1,30 @@
+# 1.2.0
+
+### Incompatible API Changes
+- New required callback: `void Shell.Async.Callback.onTaskError(Throwable)`
+- Remove unnecessary method: `boolean Shell.testCmd(String)`
+
+### Behavior Changes
+- `SuFile` now always uses `Shell` for all operations:
+  - Deprecate constructor: `SuFile(String, boolean)`
+  - Deprecate constructor: `SuFile(File, boolean)`
+- `CallbackList.onAddElement(E)` will always run on the main thread.
+- All callbacks in `Shell.Async.Callback` will always run on the main thread.
+- Errors while executing operations are returned:
+  - `Shell.run(List, List, String...)` now returns `Throwable`
+  - `Shell.loadInputStream(List, List, InputStream)` now returns `Throwable`
+
+### New Implementations
+- New `Shell.Initializer` implementation:
+  - Deprecate: `void Shell.setInitializer(Shell.Initializer)`  
+    Recommend: `void Shell.setInitializer(Class<? extends Shell.Initializer>)`
+  - Deprecate: `void Shell.Initializer.onShellInit(Shell)`  
+    Recommend: `boolean Shell.Initializer.onShellInit(Context, Shell) throws Exception`
+  - Deprecate: `void Shell.Initializer.onRootShellInit(Shell)`  
+    Recommend: `boolean Shell.Initializer.onRootShellInit(Context, Shell) throws Exception`
+
+### Improvements
+- Fix BusyBox environment creation on some devices 
+- Bump internal BusyBox to 1.28.4
+- Update `SuFile` implementation to prevent filename clashing with shell commands
+

README.md

@@ -6,27 +6,31 @@ An Android library that provides APIs to a Unix (root) shell.
 
 Some poorly coded applications requests a new shell (call `su`, or worse `su -c <commands>`) for every single command, which is very inefficient. This library makes sharing a single, globally shared shell session in Android applications super easy: developers won't have to bother about concurrency issues, and with a rich selection of both synchronous and asynchronous APIs, it is much easier to create a powerful root app.
 
-This library bundles with full featured `busybox` binaries. App developers can easily setup and create an internal `busybox` environment with the built-in helper method without relying on potentially flawed (or even no) external `busybox`. If you don't need the additional `busybox` binaries and willing to minimize APK size, [Proguard](https://developer.android.com/studio/build/shrink-code.html) is smart enough to remove the binaries for you.
+This library bundles with full featured `busybox` binaries. App developers can easily setup and create an internal `busybox` environment with the built-in helper method without relying on potentially flawed (or even no) external `busybox`.
 
 `libsu` also comes with a whole suite of I/O classes, re-creating `java.io` classes but enhanced with root access. Without even thinking about command-lines, you can use `File`, `RandomAccessFile`, `FileInputStream`, and `FileOutputStream` equivalents on all files that are only accessible with root permissions. The I/O stream classes are carefully optimized and have very promising performance.
 
 One complex Android application using `libsu` for all root related operations is [Magisk Manager](https://github.com/topjohnwu/MagiskManager).
 
+## Changelog
+
+[Link to Changelog](./CHANGELOG.md)
+
 ## Download
 ```java
 repositories {
     maven { url 'https://jitpack.io' }
 }
 dependencies {
-    implementation 'com.github.topjohnwu:libsu:1.1.1'
+    implementation 'com.github.topjohnwu:libsu:1.2.0'
 }
 ```
 
 ## Simple Tutorial
 
 ### Setup
 Subclass `Shell.ContainerApp` and use it as your `Application`.  
-Set flags, initializers, or busybox as soon as possible:
+Set flags, initializers as soon as possible:
 
 ```java
 public class ExampleApp extends Shell.ContainerApp {
@@ -36,16 +40,13 @@ public class ExampleApp extends Shell.ContainerApp {
         // Set flags
         Shell.setFlags(Shell.FLAG_REDIRECT_STDERR);
         Shell.verboseLogging(BuildConfig.DEBUG);
-        // Use internal busybox
-        BusyBox.setup(this);
     }
 }
 ```
 
 Specify the custom Application in `AndroidManifest.xml`
 
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     ...>
     <application
@@ -84,6 +85,10 @@ Shell.Async.su(new Shell.Async.Callback() {
     public void onTaskResult(List<String> out, List<String> err) {
         /* Do something with the result */
     }
+    @Override
+    public void onTaskError(Throwable err) {
+        /* Throwable thrown, handle the error */
+    }
 }, "cat /proc/mounts");
 
 /* Use a CallbackList to receive a callback every time a new line is outputted */
@@ -122,20 +127,20 @@ if (logs.exists()) {
 Initialize the shell with custom `Shell.Initializer`, similar to what `.bashrc` will do.
 
 ```java
-Shell.setInitializer(new Shell.Initializer() {
+Shell.setInitializer(ExampleInitializer.class);
+
+class ExampleInitializer extends Shell.Initializer {
     @Override
-    public void onRootShellInit(@NonNull Shell shell) {
-        /* Construct the initializer within Application if you need Context reference
-         * like the example below (getResources()). Application contexts won't leak memory, but
-         * Activities do! */
-        try (InputStream bashrc = getResources().openRawResource(R.raw.bashrc)) {
+    public boolean onRootShellInit(Context context, Shell shell) throws IOException {
+        // Use internal busybox
+        BusyBox.setup(context);
+        try (InputStream bashrc = context.getResources().openRawResource(R.raw.bashrc)) {
             // Load a script from raw resources
             shell.loadInputStream(null, null, bashrc);
-        } catch (IOException e) {
-            e.printStackTrace();
         }
+        return true;
     }
-});
+}
 ```
 
 ## Documentation

docs/allclasses-frame.html

@@ -2,9 +2,9 @@
 <!-- NewPage -->
 <html lang="zh">
 <head>
-<!-- Generated by javadoc (1.8.0_161) on Wed Feb 21 23:37:03 CST 2018 -->
+<!-- Generated by javadoc (1.8.0_152-release) on Wed Jun 20 04:07:06 CST 2018 -->
 <title>All Classes (libsu API)</title>
-<meta name="date" content="2018-02-21">
+<meta name="date" content="2018-06-20">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <script type="text/javascript" src="script.js"></script>
 </head>

docs/allclasses-noframe.html

@@ -2,9 +2,9 @@
 <!-- NewPage -->
 <html lang="zh">
 <head>
-<!-- Generated by javadoc (1.8.0_161) on Wed Feb 21 23:37:03 CST 2018 -->
+<!-- Generated by javadoc (1.8.0_152-release) on Wed Jun 20 04:07:06 CST 2018 -->
 <title>All Classes (libsu API)</title>
-<meta name="date" content="2018-02-21">
+<meta name="date" content="2018-06-20">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <script type="text/javascript" src="script.js"></script>
 </head>

docs/com/topjohnwu/superuser/BusyBox.html

@@ -2,9 +2,9 @@
 <!-- NewPage -->
 <html lang="zh">
 <head>
-<!-- Generated by javadoc (1.8.0_161) on Wed Feb 21 23:37:02 CST 2018 -->
+<!-- Generated by javadoc (1.8.0_152-release) on Wed Jun 20 04:07:05 CST 2018 -->
 <title>BusyBox (libsu API)</title>
-<meta name="date" content="2018-02-21">
+<meta name="date" content="2018-06-20">
 <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
 </head>
@@ -41,7 +41,6 @@
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
-<li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>
@@ -112,19 +111,19 @@ <h2 title="Class BusyBox" class="title">Class BusyBox</h2>
 extends <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></pre>
 <div class="block">A class that handles the bundled BusyBox.
  <p>
- <code>libsu</code> bundles with busybox binaries for both arm and x86 (arm64 and x64 are also covered).
- Developers using <code>libsu</code> can easily access busybox applets by calling <a href="../../../com/topjohnwu/superuser/BusyBox.html#setup-android.content.Context-"><code>setup(Context)</code></a>
- before any new shell is created (place this in the same place where you call
- <a href="../../../com/topjohnwu/superuser/Shell.html#setFlags-int-"><code>Shell.setFlags(int)</code></a>) and <a href="../../../com/topjohnwu/superuser/Shell.html#setInitializer-com.topjohnwu.superuser.Shell.Initializer-"><code>Shell.setInitializer(Shell.Initializer)</code></a>.
+ <code>libsu</code> bundles busybox binaries with arm/arm64 and x86/x64 covered.
+ Developers using <code>libsu</code> can setup busybox by calling <a href="../../../com/topjohnwu/superuser/BusyBox.html#setup-android.content.Context-"><code>setup(Context)</code></a>
+ before any new shell is created (e.g. the place where you call <a href="../../../com/topjohnwu/superuser/Shell.html#setFlags-int-"><code>Shell.setFlags(int)</code></a>), or
+ in the callback methods in <a href="../../../com/topjohnwu/superuser/Shell.Initializer.html" title="class in com.topjohnwu.superuser"><code>Shell.Initializer</code></a>.
  After calling <a href="../../../com/topjohnwu/superuser/BusyBox.html#setup-android.content.Context-"><code>setup(Context)</code></a>, busybox will be installed in the app's internal storage,
  and all new shells created will have the path to busybox <b>prepended</b> to <code>PATH</code>.
  This makes sure all commands are using the applets from busybox, providing predictable
  behavior so that developers can have less headache handling different implementation of the
  common shell utilities. Some operations in <code>com.topjohnwu.superuser.io</code> depends on a
  busybox to work properly, check before using them.
  <p>
- Note: the busybox binaries will add around 1.6MB to your APK, for developers not willing
- to use the busybox binaries bundled in <code>libsu</code>, you can use proguard to remove it:
+ Note: the busybox binaries will add 1.42MB to your APK. For developers not willing
+ to use the busybox binaries bundled in <code>libsu</code>, you can let proguard remove it:
  remember to <b>NOT</b> call <a href="../../../com/topjohnwu/superuser/BusyBox.html#setup-android.content.Context-"><code>setup(Context)</code></a> anywhere in your code, and enable both
  <b>minifyEnabled</b> and <b>shrinkResources</b> in your release builds. For more info, please
  check <a href="https://developer.android.com/studio/build/shrink-code.html">the official documentation</a>.</div>
@@ -207,7 +206,7 @@ <h4>BB_PATH</h4>
  If your app would like to rely on external busybox, you can directly assign the path to this field.
  All new shell instances created will have this directory <b>prepended</b> to <code>PATH</code>.
  <p>
- For example: Magisk Manager relies on the Magisk's internal busybox (located in
+ For example: Magisk Manager relies on Magisk's internal busybox (located in
  <code>/sbin/.core/busybox</code>). So instead of calling <a href="../../../com/topjohnwu/superuser/BusyBox.html#setup-android.content.Context-"><code>setup(Context)</code></a>, it can directly
  assign the busybox path to this field to discard the bundled busybox binaries.
  (<code>BusyBox.BB_PATH = new File("/sbin/.core/busybox")</code>).</div>
@@ -266,7 +265,6 @@ <h4>setup</h4>
 <li><a href="package-summary.html">Package</a></li>
 <li class="navBarCell1Rev">Class</li>
 <li><a href="package-tree.html">Tree</a></li>
-<li><a href="../../../deprecated-list.html">Deprecated</a></li>
 <li><a href="../../../index-all.html">Index</a></li>
 <li><a href="../../../help-doc.html">Help</a></li>
 </ul>