ShadowsocksX-NG2 is a modern rewrite of ShadowsocksX-NG for macOS 15+ and Apple Silicon (arm64). Its source code and build configuration are in this directory. The archived legacy version is described on the repository home page.

The app uses upstream releases of sslocal, v2ray-plugin, and Cloak ck-client. HTTP inbound traffic is handled directly by shadowsocks-rust; Legacy Privoxy is no longer bundled.

Development, build, and test

Install the Xcode/Swift toolchain, Task, XcodeGen, and SwiftLint. See the development guide for tool versions and installation instructions.

From this directory, fetch the external binaries before generating the Xcode project for the first build:

Scripts/fetch-external-binaries.sh
task gen:prj
task build

Debug builds use ad-hoc signing by default and do not require a certificate. See Signing and distribution for Developer ID configuration and release requirements. project.yml is the source of truth for project settings; the generated .xcodeproj is not checked in.

Run the unified validation workflow from the repository root:

task --exit-code --taskfile ShadowsocksX-NG2/Taskfile.dist.yml validate
# Run only the requested stages, in the specified order:
task --exit-code --taskfile ShadowsocksX-NG2/Taskfile.dist.yml validate -- format:check lint test

The default order is lint → test → build; execution stops on the first failure. Real-process smoke tests remain available through the explicit test:smoke task. Run task format:check separately to check formatting without modifying files. Logs and results are saved in ShadowsocksX-NG2/.build/validation/. From this directory, you can run task --exit-code validate. See the development guide for individual tasks, evidence, and test boundaries.

Documentation

Document	Contents
Development, build, and test	Validation entry points and artifacts, individual tasks, code style tools, Git hooks, and document language
Project structure and source search	Source layers, test directories, cross-target file constraints, and search methods
GUI, Agent, Helper, and sslocal architecture	Implementation snapshot from 2026-10-24: process boundaries, configuration publication, traffic paths, and lifecycle
External binaries, signing, and distribution	Supply-chain checks, Debug/Release signing, release requirements, and dependency updates
Bundled rule snapshots	Sources, conversion semantics, maintenance scripts, and offline checks
Subscriptions, plugins, and listener configuration	Subscription data, user plugins, Cloak, local and LAN listeners, and configuration recovery
Server library encryption format	Encrypted file format and external decryption contract

The glossary and architecture decision records are maintained in Simplified Chinese and describe domain terminology and accepted designs. docs/design/ and docs/research/ are historical design and research records. Use the current code as the source of truth for implementation behavior.