kmp-tor-resource

This project is focused on the packaging and distribution of pre-compiled tor resources for Kotlin Multiplatform, primarily to be consumed as a dependency for kmp-tor.

Build Reproducibility

See DETERMINISTIC_BUILDS.md

Compilations

Tor and its dependencies are compiled from source using the following versions

	git tag
libevent	release-2.1.12-stable
openssl	openssl-3.4.1
tor	tor-0.4.8.16
xz	v5.8.1
zlib	v1.3.1

NOTE: All macOS and Windows compilations are code signed so they work out of the box.

More details about how things are compiled can be found HERE

Jvm/Node.js Supported Operating Systems & Architectures

	x86	x86_64	armv7	aarch64	ppc64
Windows	✔	✔
macOS		✔		✔
Linux (android)	✔	✔	✔	✔
Linux (libc)	✔	✔	✔	✔	✔
Linux (musl)
FreeBSD

Types (exec & noexec)

2 types of resources are available; exec and noexec. This is to support platforms where process execution is not allowed (e.g. iOS).

• resource-exec-tor and its -gpl variant:

  • Provides an implementation of ResourceLoader.Tor.Exec
  • Support for all platforms except iOS

• resource-noexec-tor and its -gpl variant:

  • Provides an implementation of ResourceLoader.Tor.NoExec
  • Support for all platforms except Node.js

Even though tremendous work has gone into making the noexec dependencies as safe as possible by unloading tor after each invocation of tor_run_main, there is no safer way to run tor than in its own process (as it was designed). The exec dependency should be utilized whenever possible.

Variants (tor & tor-gpl)

2 variants of tor are compiled; 1 with the flag --enable-gpl, and 1 without it.

Publications with the -gpl suffix are indicative of the presence of the --enable-gpl compile time flag.

Both variants are positionally identical with the same package names, classes, resource names/locations, etc. The only difference between them are the compilations of tor being provided.

Only 1 variant can be had for a project, as a conflict will occur if both are present.

Example

build.gradle.kts

// BAD
dependencies {
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor:$vKmpTorResource")
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor-gpl:$vKmpTorResource")
}

// BAD
dependencies {
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor:$vKmpTorResource")
    implementation("io.matthewnelson.kmp-tor:resource-noexec-tor-gpl:$vKmpTorResource")
}

// GOOD! (non-gpl)
dependencies {
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor:$vKmpTorResource")
    implementation("io.matthewnelson.kmp-tor:resource-noexec-tor:$vKmpTorResource")
}

// GOOD! (gpl)
dependencies {
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor-gpl:$vKmpTorResource")
    implementation("io.matthewnelson.kmp-tor:resource-noexec-tor-gpl:$vKmpTorResource")
}

This is to respect the GPL licensed code tor is utilizing such that projects who have a GPL license are able to take advantage of the new functionality, and projects who do not have a GPL license can still utilize tor without infringing on the license.

Get Started

// build.gradle.kts
dependencies {
    val vKmpTorResource = "408.16.3"
    implementation("io.matthewnelson.kmp-tor:resource-exec-tor:$vKmpTorResource")
    implementation("io.matthewnelson.kmp-tor:resource-noexec-tor:$vKmpTorResource")

    // Alternatively, if wanting tor compiled with `--enable-gpl` (GPL v3 licensed code)
//    implementation("io.matthewnelson.kmp-tor:resource-exec-tor-gpl:$vKmpTorResource")
//    implementation("io.matthewnelson.kmp-tor:resource-noexec-tor-gpl:$vKmpTorResource")
}

Configure Android

Some additional configuration may be necessary for your Android application.

• If utilizing the -exec dependency, compilations must be extracted to the nativeLibraryDir upon application install:

  // build.gradle.kts
  android {
      packaging {
          jniLibs.useLegacyPackaging = true
      }
  }

  // gradle.properties
  android.bundle.enableUncompressedNativeLibs=false

• If running unit tests for Android (not device/emulator), add the following dependency which will provide the desktop compilations and use them instead of the android compilations.

  // build.gradle.kts
  dependencies {
      testImplementation("io.matthewnelson.kmp-tor:resource-android-unit-test-tor:$vKmpTorResource")
  
      // Alternatively, if using the `-gpl` variants
  //    testImplementation("io.matthewnelson.kmp-tor:resource-android-unit-test-tor-gpl:$vKmpTorResource")
  }

• Setup splits for each ABI

  // build.gradle.kts
  android {
      splits {
          abi {
              isEnable = true
              reset()
              include("x86", "armeabi-v7a", "arm64-v8a", "x86_64")
              isUniversalApk = true
          }
      }
  }

Configure iOS

See the frameworks gradle plugin README for more details.

Configure Jvm/Java

See the filterjar gradle plugin README for more details.

Configure Node.js

See the npmjs README for more details.

If utilizing with kmp-tor, simply pass into TorRuntime.Environment.Builder.

• E.g. ResourceLoaderTorExec via resource-exec-tor dependency (or its -gpl variant)

val env = TorRuntime.Environment.Builder(myWorkDir, myCacheDir, ResourceLoaderTorExec::getOrCreate)

• E.g. ResourceLoaderTorNoExec via resource-noexec-tor dependency (or its -gpl variant)

val env = TorRuntime.Environment.Builder(myWorkDir, myCacheDir, ResourceLoaderTorNoExec::getOrCreate)

See kmp-tor-samples for more details.