Commit bd4cfbfe authored by Mygod's avatar Mygod

Update doc and guide

parent c7ef0e3a
* 1.3.4: * 1.3.4:
* Please use `android:path` instead of `android:pathPrefix`, sample code in documentations have been updated to reflect this recommendation.
* Fix occasional crash in `AlertDialogFragment`. * Fix occasional crash in `AlertDialogFragment`.
* Translation updates. * Translation updates.
* Dependency updates: * Dependency updates:
......
...@@ -10,13 +10,12 @@ Support library for easier development on [shadowsocks ...@@ -10,13 +10,12 @@ Support library for easier development on [shadowsocks
These are some plugins ready to use on shadowsocks-android. These are some plugins ready to use on shadowsocks-android.
* [simple-obfs](https://github.com/shadowsocks/simple-obfs-android/releases) * [v2ray](https://github.com/shadowsocks/v2ray-plugin-android)
* [kcptun](https://github.com/shadowsocks/kcptun-android/releases) * [kcptun](https://github.com/shadowsocks/kcptun-android/releases)
* [simple-obfs](https://github.com/shadowsocks/simple-obfs-android/releases)
## Developer's guide ## Developer's guide
WARNING: This library is still in beta (0.x) and its content is subject to massive changes.
This library is designed with Java interoperability in mind so theoretically you can use this This library is designed with Java interoperability in mind so theoretically you can use this
library with other languages and/or build tools but there isn't documentation for that yet. This library with other languages and/or build tools but there isn't documentation for that yet. This
guide is written for Scala + SBT. Contributions are welcome. guide is written for Scala + SBT. Contributions are welcome.
...@@ -32,11 +31,11 @@ There are no arbitrary restrictions/requirements on package name, component name ...@@ -32,11 +31,11 @@ There are no arbitrary restrictions/requirements on package name, component name
### Add dependency ### Add dependency
First you need to add this library to your dependencies. This library is written mostly in Scala First you need to add this library to your dependencies.
and it's most convenient to use it with SBT: This library is written mostly in Kotlin but can also work with Java-only projects:
```scala ```gradle
libraryDependencies += "com.github.shadowsocks" %% "plugin" % "0.0.4" implementation 'com.github.shadowsocks:plugin:$LATEST_VERSION'
``` ```
### Native binary configuration ### Native binary configuration
...@@ -44,7 +43,7 @@ libraryDependencies += "com.github.shadowsocks" %% "plugin" % "0.0.4" ...@@ -44,7 +43,7 @@ libraryDependencies += "com.github.shadowsocks" %% "plugin" % "0.0.4"
First you need to get your native binary compiling on Android platform. First you need to get your native binary compiling on Android platform.
* [Sample project for C](https://github.com/shadowsocks/simple-obfs-android/tree/4f82c4a4e415d666e70a7e2e60955cb0d85c1615); * [Sample project for C](https://github.com/shadowsocks/simple-obfs-android/tree/4f82c4a4e415d666e70a7e2e60955cb0d85c1615);
* [Sample project for Go](https://github.com/shadowsocks/kcptun-android/tree/41f42077e177618553417c16559784a51e9d8c4c). * [Sample project for Go](https://github.com/shadowsocks/v2ray-plugin-android/tree/172bd4cec0276112828614482fb646b79dbf1540).
In addition to functionalities of a normal plugin, it has to support these additional flags that In addition to functionalities of a normal plugin, it has to support these additional flags that
may get passed through arguments: may get passed through arguments:
...@@ -56,24 +55,22 @@ In addition to functionalities of a normal plugin, it has to support these addit ...@@ -56,24 +55,22 @@ In addition to functionalities of a normal plugin, it has to support these addit
### Implement a binary provider ### Implement a binary provider
It's super easy. You just need to implement two or three methods. For example for `obfs-local`: You just need to implement two or three methods. For example for `v2ray`:
```scala ```kotlin
final class BinaryProvider extends NativePluginProvider { class BinaryProvider : NativePluginProvider() {
override protected def populateFiles(provider: PathProvider) { override fun populateFiles(provider: PathProvider) {
provider.addPath("obfs-local", "755") provider.addPath("v2ray", 0b111101101)
// add additional files here // add additional files here
} }
// remove this method to disable fast mode, read more in the documentation // remove this method to disable fast mode, read more in the documentation
override def getExecutable: String = override fun getExecutable() = context!!.applicationInfo.nativeLibraryDir + "/libv2ray.so"
getContext.getApplicationInfo.nativeLibraryDir + "/libobfs-local.so"
override def openFile(uri: Uri): ParcelFileDescriptor = uri.getPath match { override fun openFile(uri: Uri): ParcelFileDescriptor = when (uri.path) {
case "/obfs-local" => "/v2ray" -> ParcelFileDescriptor.open(File(getExecutable()), ParcelFileDescriptor.MODE_READ_ONLY)
ParcelFileDescriptor.open(new File(getExecutable), ParcelFileDescriptor.MODE_READ_ONLY)
// handle additional files here // handle additional files here
case _ => throw new FileNotFoundException() else -> throw FileNotFoundException()
} }
} }
``` ```
...@@ -95,12 +92,16 @@ Then add it to your manifest: ...@@ -95,12 +92,16 @@ Then add it to your manifest:
<action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/> <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
<data android:scheme="plugin" <data android:scheme="plugin"
android:host="com.github.shadowsocks" android:host="com.github.shadowsocks"
android:pathPrefix="/$PLUGIN_ID"/> android:path="/$PLUGIN_ID"/>
</intent-filter> </intent-filter>
<meta-data android:name="com.github.shadowsocks.plugin.id" <meta-data android:name="com.github.shadowsocks.plugin.id"
android:value="$PLUGIN_ID"/> android:value="$PLUGIN_ID"/>
<!-- Optional: default is empty -->
<meta-data android:name="com.github.shadowsocks.plugin.default_config" <meta-data android:name="com.github.shadowsocks.plugin.default_config"
android:value="dummy=default;plugin=options"/> android:value="dummy=default;plugin=options"/>
<!-- Optional: remove to disable faster mode, read more in the documentation -->
<meta-data android:name="com.github.shadowsocks.plugin.executable_path"
android:value="$PATH_TO_EXECUTABLE_RELATIVE_TO_NATIVE_LIB_DIR"/>
</provider> </provider>
... ...
</application> </application>
......
...@@ -164,7 +164,7 @@ This corresponds to `com.github.shadowsocks.plugin.NativePluginProvider` in the ...@@ -164,7 +164,7 @@ This corresponds to `com.github.shadowsocks.plugin.NativePluginProvider` in the
<action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/> <action android:name="com.github.shadowsocks.plugin.ACTION_NATIVE_PLUGIN"/>
<data android:scheme="plugin" <data android:scheme="plugin"
android:host="com.github.shadowsocks" android:host="com.github.shadowsocks"
android:pathPrefix="/$PLUGIN_ID"/> android:path="/$PLUGIN_ID"/>
</intent-filter> </intent-filter>
<meta-data android:name="com.github.shadowsocks.plugin.id" <meta-data android:name="com.github.shadowsocks.plugin.id"
android:value="$PLUGIN_ID"/> android:value="$PLUGIN_ID"/>
...@@ -202,6 +202,7 @@ This allows the host app to launch your plugin without ever launching your app. ...@@ -202,6 +202,7 @@ This allows the host app to launch your plugin without ever launching your app.
## JVM mode ## JVM mode
This feature hasn't been implemented yet. This feature hasn't been implemented yet.
Please open an issue if you need this.
# Plugin security # Plugin security
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment