Shadowsocks for Android - Deploy & Usage Guide

1. Prerequisites

Development Environment

• JDK 11+ - Required for Android development
• Android SDK - Complete Android development environment
  • Android NDK - Native Development Kit for C/C++ components
• Rust - For native components
  • Install Rust using rustup
  • Add Android targets: rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Runtime Requirements

• Android 7.0 (API level 23) or higher
• Chrome OS (for Chrome OS compatibility)

Optional Tools

• Android Studio - Recommended for development
• Git - For cloning the repository

2. Installation

Clone the Repository

git clone --recurse-submodules https://github.com/shadowsocks/shadowsocks-android.git
cd shadowsocks-android

Update Submodules (if needed)

git submodule update --init --recursive

Install Dependencies

1. Install Android Studio and Android SDK
2. Install Android NDK through Android Studio SDK Manager
3. Install Rust and add Android targets as mentioned in prerequisites

3. Configuration

Environment Setup

• No specific environment variables required for basic usage
• API keys are not needed for the client application

Build Configuration

• The project uses standard Android build system
• No additional configuration files needed for basic build

4. Build & Run

Using Android Studio

1. Open the project in Android Studio
2. Sync Gradle files
3. Select build variant (debug/release)
4. Click "Run" to build and deploy to connected device/emulator

Using Gradle (Command Line)

# Build debug version
./gradlew assembleDebug

# Build release version
./gradlew assembleRelease

# Install to connected device
./gradlew installDebug

Build Verification

• Check CircleCI build status: https://circleci.com/gh/shadowsocks/shadowsocks-android
• Ensure all tests pass before deployment

5. Deployment

Distribution Options

Google Play Store

• Standard Version: Available on Google Play Store
• Beta Version: Join beta testing: https://play.google.com/apps/testing/com.github.shadowsocks

Direct APK Distribution

• Download APK from GitHub releases: https://github.com/shadowsocks/shadowsocks-android/releases
• Enable "Install from unknown sources" on Android device

Android TV Version

• Separate app for Android TV: https://play.google.com/store/apps/details?id=com.github.shadowsocks.tv
• Beta testing available: https://play.google.com/apps/testing/com.github.shadowsocks.tv

Build Variants

• Debug: For development and testing
• Release: For production deployment
• TV: For Android TV devices

6. Troubleshooting

Common Build Issues

Missing Submodules

# If build fails due to missing submodules
git submodule update --init --recursive

Rust Target Issues

# If Rust targets are missing
rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Gradle Sync Issues

• Ensure Android SDK and NDK paths are correctly configured in Android Studio
• Clean and rebuild project if Gradle sync fails

Runtime Issues

Connection Problems

• Verify server configuration
• Check network permissions
• Ensure proper routing rules are configured

Performance Issues

• Check device compatibility (API 23+)
• Monitor battery usage
• Verify proper background service operation

Development Issues

Code Quality

• Project uses Codacy for code quality: https://www.codacy.com/gh/shadowsocks/shadowsocks-android/dashboard
• Follow CONTRIBUTING guidelines: https://github.com/shadowsocks/shadowsocks-android/blob/master/CONTRIBUTING.md

Testing

• Use Android Studio's built-in testing tools
• Test on multiple API levels (23+)
• Verify functionality on both mobile and TV variants

License Compliance

• Project uses GPL-3.0 license
• Ensure compliance with open source licenses of dependencies
• Review open source licenses: https://github.com/shadowsocks/shadowsocks-android#open-source-licenses