carol8421 / outline-client

Outline clients, developed by Jigsaw. The Outline clients use the popular Shadowsocks protocol, and lean on the Cordova and Electron frameworks to support Windows, Android / ChromeOS, Linux, iOS and macOS.

Outline Client

The Outline Client is a cross-platform VPN or proxy client for Windows, macOS, iOS, Android, and ChromeOS. The Outline Client is designed for use with the Outline Server software, but it is fully compatible with any Shadowsocks server.

The client's user interface is implemented in Polymer 2.0. Platform support is provided by Cordova and Electron, with additional native components in this repository.

Requirements for all builds

All builds require yarn, in addition to other per-platform requirements. After cloning this repo, you should run "yarn" to install all dependencies.

Building the web app

Outline clients share the same web app across all platforms. This code is located in the src/www directory. If you are making changes to the shared web app and do not need to test platform-specific functionality, you can test in a desktop browser by running:

yarn gulp build --platform=browser
yarn cordova run browser

The latter command will open a browser instance running the app. Browser platform development will use fake servers to test successful and unsuccessful connections.

UI components are located in src/www/ui_components. The app logic is located in src/www/app.

Building the Android app

Additional requirements for Android:

• Android Studio 4+
• Android SDK 29

To build for android, run:

yarn gulp build --platform=android

To rebuild after modifying platform dependent files, run:

yarn cordova platform rm android && yarn gulp build --platform=android

If this gives you unexpected Cordova errors, run:

yarn run clean && yarn && yarn gulp build --platform=android

Cordova will generate a new Android project in the platforms/android directory. Install the built apk by platforms/android/build/outputs/apk/android-armv7-debug.apk

To learn more about developing for Android, see docs/android-development.

Building for Android with Docker

A Docker image with all pre-requisites for Android builds is included. To build:

• Install dependencies with ./tools/build/build.sh yarn
• Then build with ./tools/build/build.sh yarn gulp build --platform=android

Apple (macOS and iOS)

Additional requirements for Apple:

• An Apple Developer Account. You will need to be invited to join the "Jigsaw Operations LLC" team
• XCode 11+ (download)
• XCode command line tools

To build for macOS (OS X), run:

yarn run clean && yarn && yarn gulp build --platform=osx

To build for iOS, run:

yarn run clean && yarn && yarn gulp build --platform=ios

To learn more about developing for Apple, see docs/apple-development

Electron

Unlike the Android and Apple clients, the Windows and Linux clients use the Electron framework, rather than Cordova.

Windows

Additional requirements for building on Windows:

• Cygwin. It provides the "missing Unix pieces" required by build system such as rsync (and many others). It may be necessary to manually choose to install rsync in the Cygwin installer.

To build the Electron clients, run:

yarn do src/electron/build

To run the Electron clients, run:

yarn do src/electron/run

To package the Electron clients into an installer executable, run:

yarn do src/electron/package_[linux|windows]

Error reporting

To enable error reporting through Sentry for local builds, run:

export SENTRY_DSN=[Sentry development API key]
[platform-specific build command]

Release builds on CI are configured with a production Sentry API key.