Merge pull request #27 from 05nelsonm/mn/feature/prep-for-gradle-maven-publish-implementation

Prep for gradle maven publish implementation

Author: 05nelsonm

.gitmodules

@@ -1,8 +0,0 @@
-[submodule "external/AndroidPluggableTransports"]
-	path = external/AndroidPluggableTransports
-	url = https://github.com/guardianproject/AndroidPluggableTransports.git
-	branch = master
-[submodule "external/tor-android"]
-	path = external/tor-android
-	url = https://github.com/guardianproject/tor-android.git
-	ignore = all

docs/assets/Screenshot_SampleApp_Debug_full.png

@@ -1,41 +1,97 @@
 Get Started
 ===
 
-## Implementation (topl-service)
- - In your App Module's `build.gradle` file, add the following to the `dependencies` block"
+## Implementation - Step 1: Assets/Binaries
+ - **GeoIP files**:
+    - Your application will need geoip and geoip6 files. Due to
+    <a href="https://lists.torproject.org/pipermail/tor-dev/2020-January/014117.html" target="_blank">this issue</a>
+    they currently cannot be provided via a dependency that can be easily updated. 
+    Until then, you'll have to provide them.
+    - Steps:
+        - Download `geoip` and `geoip6` files from https://github.com/torproject/tor/tree/master/src/config
+            - If you prefer the non-mirror repository, you can also obtain them from
+            https://gitweb.torproject.org/tor.git/tree/src/config
+        - In your Application module's `src/main` directory, create a new `Directory` named `assets`
+        - Copy `geoip` and `geoip6` files into the `assets` directory (or a subdirectory within 
+        `assets`, such as `assets/common/`. File extensions not necessary).
+ - **torrc file**:
+    - Not needed
+    - Your application's `torrc` file gets created for you based on what you have stored in 
+    [TorServicePrefs](./topl-service/io.matthewnelson.topl_service.prefs/-tor-service-prefs/index.md). 
+    If nothing is in `TorServicePrefs` for that particular setting, then it will fall back on 
+    your static/default [TorSettings](./topl-core-base/io.matthewnelson.topl_core_base/-tor-settings/index.md) 
+    that you supply upon initialization of `TorServiceController.Builder`. 
+ - **Tor Binaries**:
+    - I use The GuardianProject's <a href="https://github.com/guardianproject/tor-android" target="_blank">tor-android</a>
+    project to build binaries, and provided them 
+    <a href="https://github.com/05nelsonm/TOPL-Android-TorBinary" target="_blank">here</a>. The 
+    difference is in how they are packaged as a dependency, and the contents of what you are
+    importing as a dependency. I package them in the `jniLibs` directory so that the Android OS
+    will automatically install them into your application's `/data/app/...` directory, and include
+    no unnecessary classes or resources; just the binaries. Android API 29+ no longer supports 
+    execution of executable files from your application's `/data/data/` directory, and must now be
+    installed in the `context.applicationInfo.nativeLibraryDir` directory (aka, `/data/app/...`) 
+    to execute.
+        - Nothing more is needed in terms of configuring initialization via the 
+        `TorServiceController.Builder`, as files will be installed in the correct directory, and 
+        named to match what `topl-service` looks for.
+    - If you wish to use GuardianProject's binaries, see 
+    <a href="https://github.com/guardianproject/tor-android" target="_blank">tor-android</a>.
+        - You'll need to use their `NativeResouceInstaller` to install the binaries.
+        - You'll need to also implement `TorServiceController.Builder.useCustomTorConfigFiles` 
+        method when initializing `topl-service` and provide it with your own 
+        [TorConfigFiles](./topl-core-base/io.matthewnelson.topl_core_base/-tor-config-files/index.md).
+            - See the sample provided in the 
+            [TorConfigFiles.Builder](./topl-core-base/io.matthewnelson.topl_core_base/-tor-config-files/-builder/index.md) 
+            documentation.
+ - **Transport Plugin Binaries**:
+    - Currently unsupported. Working on it!!!  
+
+
+!!! Info
+    Tor Binaries are ~8MB for each ABI (will be less after compression), so it's advised that builds 
+    are split to keep apk sizes down. For example, the `sampleapp`'s universalApk size (all ABIs) 
+    is ~16MB, where splits are ~7MB. See the `sampleapp`'s `build.gradle` file for more details. 
+    <a href="https://github.com/05nelsonm/TorOnionProxyLibrary-Android/blob/master/sampleapp/build.gradle" target="_blank">here</a>  
+
+## Implementation - Step 2: topl-service
+ - In your Application module's `build.gradle` file, add the following to the `dependencies` block:
      ```groovy
      def topl_android_version = "{{ topl_android.release }}"
-     implementation 'io.matthewnelson.topl-android:topl-core-base:$topl_android_version'
-     implementation 'io.matthewnelson.topl-android:topl-service:$topl_android_version'
+     implementation "io.matthewnelson.topl-android:topl-core-base:$topl_android_version"
+     implementation "io.matthewnelson.topl-android:topl-service:$topl_android_version"
      ```
-   
- - TODO: geoip files and binaries
  
  - Create a new class which extends [TorSettings](./topl-core-base/io.matthewnelson.topl_core_base/-tor-settings/index.md)
    and apply your own default settings.
+    - See the SampleApp's 
+    <a href="https://github.com/05nelsonm/TorOnionProxyLibrary-Android/blob/master/sampleapp/src/main/java/io/matthewnelson/sampleapp/MyTorSettings.kt">MyTorSettings</a> 
+    class for help.
+    - Also checkout the documentation in the `TorSettings` class for more of a breakdown and help.
    
  - In your Application class' `onCreate` implement, and customize as desired, the
    [TorServiceController.Builder](./topl-service/io.matthewnelson.topl_service/-tor-service-controller/-builder/index.md)
    
  - Call APIs provided from
    [TorServiceController.Companion](./topl-service/io.matthewnelson.topl_service/-tor-service-controller/index.md)
  
-## Using the SNAPSHOT version
+### Using the SNAPSHOT version of topl-service
 
- - In your Project's `build.gradle` file, add the following to the `repositories` block:
+ - In your Application module's `build.gradle` file, add the following (*outside* the `android` block):
      ```groovy
-     mavenCentral()
-     maven {
-         url 'https://oss.sonatype.org/content/repositories/snapshots/'
+     repositories {
+         maven {
+             url 'https://oss.sonatype.org/content/repositories/snapshots/'
+         }
      }
      ```
    
- - In your App module's `build.gradle` file, add (or modify) the following in the `dependencies` block:
+ - In your Application module's `build.gradle` file, add (or modify) the following in the `dependencies` block:
      ```groovy
      def topl_android_version = "{{ topl_android.next_release }}-SNAPSHOT"
      implementation 'io.matthewnelson.topl-android:topl-core-base:$topl_android_version'
      implementation 'io.matthewnelson.topl-android:topl-service:$topl_android_version'
      ```
 
-     !!! Warning
+    !!! Warning
         SNAPSHOT versions are ever changing and may contain not yet fully fleshed out features. Do **not** ship a release.

docs/assets/Screenshot_SampleApp_Debug_notification1.png

@@ -1,14 +1,25 @@
 # TorOnionProxyLibrary-Android
-An Android Library for embedding Tor as a service into your Application
+An Android Library for embedding Tor as a service into your Application  
 
 **NOTE: This project exists independently of the Tor Project, & Guardian Project.**  
 
-This is a Fork of the <a href="https://github.com/thaliproject/Tor_Onion_Proxy_Library" target="_blank">Tor_Onion_Proxy_Library</a>  
+This is a Fork of the 
+<a href="https://github.com/thaliproject/Tor_Onion_Proxy_Library" target="_blank">Tor_Onion_Proxy_Library</a> 
+project. 
 
-This fork has been re-built from the ground up and engineered specifically for Android, where
-it was once multi-platform. It's been re-written in Kotlin, heavily refactored, and a separate
-`Service` created for abstracting away the complexities into simple APIs to make embedding Tor
-directly into your Application, easy.
+<center>
+    <img src="assets/Screenshot_SampleApp_Debug_full.png" width="250"/>
+    <img src="assets/Screenshot_SampleApp_Debug_notification1.png" width="250"/>
+    <img src="assets/Screenshot_SampleApp_Debug_notification2.png" width="250"/>
+</center>
+
+It's been re-built from the ground up and engineered specifically for :material-heart-multiple: 
+Android :material-heart-multiple:, where it was once multi-platform. It's been re-written in 
+Kotlin, heavily refactored to improve reliability/ease of use, and an `android.app.Service` 
+built on top as an additional module/Library for abstracting away complexities.  
+
+The `topl-service` module/Library has simple to use APIs for integrating Tor into your 
+application, and customizing the notification to meet your liking.  
 
 ## [Project Roadmap](roadmap.md)
 

docs/assets/Screenshot_SampleApp_Debug_notification2.png

@@ -111,8 +111,12 @@ git push
         - `mkdocs gh-deploy` to deploy
         - Ensure docs are served <a href="https://topl-android.matthewnelson.io" target="_blank">Here</a>
         - `exit`
-    - Go to the <a href="https://github.com/05nelsonm/TorOnionProxyLibrary-Android/releases/new" target="_blank">Draft a new release</a> page,
-      enter the release name ({{ topl_android.next_release }}) as tag and title, and have the description
-      point to the changelog. You can find the direct anchor URL from the
-      <a href="https://topl-android.matthewnelson.io/changelog/" target="_blank">Change Log</a>
-      page on the doc site.
+    - Sign SampleApp release apks:
+        - `scripts/sign_sampleapp_release_build.sh`
+    - Go to the <a href="https://github.com/05nelsonm/TorOnionProxyLibrary-Android/releases/new" target="_blank">Draft a new release</a> 
+    page
+        - Enter the release name ({{ topl_android.next_release }}) as tag and title.
+        - Have the description point to the changelog. You can find the direct anchor URL from the 
+        <a href="https://topl-android.matthewnelson.io/changelog/" target="_blank">Change Log</a> 
+        page on the doc site.
+        - Upload the signed release apks.

docs/get_started.md

@@ -45,8 +45,39 @@ android {
     kotlinOptions {
         jvmTarget = JavaVersion.VERSION_1_8
     }
+
+    // https://github.com/guardianproject/tor-android/blob/master/sampletorapp/build.gradle
+    splits {
+
+        // Configures multiple APKs based on ABI. This helps keep the size
+        // down, since PT binaries can be large.
+        abi {
+
+            // Enables building multiple APKs per ABI.
+            enable true
+
+            // By default all ABIs are included, so use reset() and include to specify
+            // that we only want APKs for x86 and x86_64, armeabi-v7a, and arm64-v8a.
+
+            // Resets the list of ABIs that Gradle should create APKs for to none.
+            reset()
+
+            // Specifies a list of ABIs that Gradle should create APKs for.
+            include "x86", "armeabi-v7a", "arm64-v8a", "x86_64"
+
+            // Specify whether or not you wish to also generate a universal APK that
+            // includes _all_ ABIs.
+            universalApk true
+        }
+    }
 }
 
+//repositories {
+//    maven {
+//        url 'https://oss.sonatype.org/content/repositories/snapshots/'
+//    }
+//}
+
 dependencies {
     implementation fileTree(dir: "libs", include: ["*.jar"])
     implementation project(':topl-core-base')
@@ -62,51 +93,12 @@ dependencies {
     implementation deps.kotlin.coroutinesAndroid
     implementation deps.kotlin.stdlib
 
+    implementation "io.matthewnelson.topl-android:tor-binary:0.4.3.5a"
+
     testImplementation deps.junit
 
     androidTestImplementation deps.androidx.test.core
     androidTestImplementation deps.androidx.test.espresso
     androidTestImplementation deps.androidx.test.junit
 
 }
-
-task updatePluggableTransportsSubmodule(type: Exec) {
-    workingDir "$rootDir"
-    commandLine "scripts/pull_latest_transports.sh"
-}
-
-task copyPluggableTransports(type: Copy, dependsOn: updatePluggableTransportsSubmodule) {
-    from("$rootDir/external/AndroidPluggableTransports/APTDispatchLibrary-MeekObfs4-Legacy/src/main/libs")
-    into("src/main/jniLibs")
-    rename { filename ->
-        filename.replace "$filename", 'libObfs4proxy.so'
-    }
-}
-
-task buildTorBinaries(type: Exec) {
-    workingDir "$rootDir"
-    commandLine 'scripts/update_tor_binaries.sh', 'build'
-}
-
-task copyTorBinaries(type: Copy, dependsOn: buildTorBinaries) {
-    from("$rootDir/external/tor-android/tor-android-binary/src/main/libs")
-    into("src/main/jniLibs")
-    rename { filename ->
-        filename.replace "$filename", 'libTor.so'
-    }
-}
-
-task updateTorBinaries(type: Exec, dependsOn: copyTorBinaries) {
-    workingDir "$rootDir"
-    commandLine 'scripts/update_tor_binaries.sh', 'update_versions_file'
-}
-
-task checkForTorBinaryUpdate(type: Exec) {
-    workingDir "$rootDir"
-    commandLine 'scripts/update_tor_binaries.sh', 'check_for_update'
-}
-
-gradle.projectsEvaluated {
-    preBuild.dependsOn(checkForTorBinaryUpdate)
-    preBuild.dependsOn(copyPluggableTransports)
-}