# Build the native components

Use macOS, Xcode 26.6 with its command-line tools and iOS SDKs, Git, Python 3,
rsync, patch, make, and **Go 1.27.1**. Dependencies are fetched from their pinned
upstreams using `go.mod` and `go.sum`. No account, VPN credentials, signing key
or proprietary application project is needed to build these static libraries.
Verify the downloaded package first with `shasum -a 256 -c SHA256SUMS`.

## WireGuard and AmneziaWG

The complete library subset is in `Vendor/wireguard-apple`. It is based on
WireGuard Apple commit `2fec12a6e1f6e3460b6ee483aa00ad29cddadab1`, with
the changes described in README.txt. Module versions and checksums are in
`Sources/WireGuardKitGo/go.mod` and `go.sum`; no additional module replacements
are needed. Its public headers expose both `wgTurnOn` and `awgTurnOn`.

From the package root, set an absolute Go directory and a new scratch directory
outside this source package. The example builds an unsigned iOS arm64 archive:

```sh
export GO_BIN=/absolute/path/to/go1.27.1/bin
export PROJECT_DIR="$PWD"
export CONFIGURATION_TEMP_DIR=/absolute/path/to/new-scratch/temp
export CONFIGURATION_BUILD_DIR=/absolute/path/to/new-scratch/output
export ARCHS=arm64
export PLATFORM_NAME=iphoneos
export SDKROOT="$(xcrun --sdk iphoneos --show-sdk-path)"
export IPHONEOS_DEPLOYMENT_TARGET=17.0
export DEPLOYMENT_TARGET_CLANG_FLAG_NAME=miphoneos-version-min
export DEPLOYMENT_TARGET_CLANG_ENV_NAME=IPHONEOS_DEPLOYMENT_TARGET
sh Scripts/build-wireguard.sh
```

The output is `$CONFIGURATION_BUILD_DIR/libwg-go.a`. The Makefile copies Go's
runtime into the scratch directory, applies the included suspend-aware clock
patch there, and builds both engines into a single C archive/Go runtime.
The original compiler installation is unchanged. For simulator output, use
`PLATFORM_NAME=iphonesimulator`, that SDK, supported simulator `ARCHS`, and
`DEPLOYMENT_TARGET_CLANG_FLAG_NAME=mios-simulator-version-min` in a separate
scratch directory. Swift/C sources build as the supplied WireGuardKit package
and link against this archive using normal WireGuardKit integration.

Run the native bridge tests on macOS in a disposable copy of the package:

```sh
cd Vendor/wireguard-apple/Sources/WireGuardKitGo
PATH="$GO_BIN:$PATH" go test -race ./... -count=1
```

These tests exchange synthetic packets over loopback and generate temporary
random keys. They do not require an account, remote VPN server or production
configuration, and do not modify a system VPN interface.

## Xray and libXray

`Scripts/build-xray.sh`, `Patches/`, and `LibXraySource/` provide the exact
build24 inputs, including the two Hysteria lifecycle/path-MTU patches. From the package root, use a separate empty scratch
directory for this build:

```sh
XRAY_WORK=/absolute/path/to/new-xray-scratch \
XRAY_GO_BIN=/absolute/path/to/go1.27.1/bin \
PYTHON_BIN=python3 sh Scripts/build-xray.sh
```

The script obtains pinned libXray commit
`3c694b23290f9849fe52284a345ebd4343bc90cd` and pinned Xray core module
`v1.260327.1-0.20260930074004-b26a91de4f32`, verifies/applies the seven patches,
runs the affected tests, and invokes the upstream Apple builder. The resulting
`LibXray.xcframework` includes iOS arm64 and simulator arm64/x86_64 slices.
It is linked in a separate extension process from the WireGuard/AmneziaWG
archive; two independent Go runtimes must not be linked into one process.

The additional lifecycle patch backports upstream commit
`c7dbfd5e1ea3bb2dee042582507b2ce78a44d3a7`. The safe-MTU patch applies only
to Hysteria and is required in both the client and listener for the conservative
packet-size bound. Modified MPL-covered files, including tests, are in
`Patches/Source/` in their final form; the patches reconstruct those files from
the pinned upstream. The wrapper API remains version 3.

A standalone Linux amd64 core can be built from the same patched scratch source:

```sh
cd "$XRAY_WORK/Xray-core"
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
  "$XRAY_GO_BIN/go" build -trimpath -ldflags=-buildid= -o ../xray-linux-amd64 ./main
```

This builds only the open-source core, without service configuration, credentials,
DNS records, proprietary API components or deployment scripts.

## Inputs and notices

`ThirdPartyNotices.txt` is byte-identical to the notice file in build24. Full
library licenses are retained alongside source; upstream copyright statements
are unchanged. `provenance.json` and `SHA256SUMS` identify the exact published
inputs. Rebuilding with another Xcode, SDK or directory may produce different
archive bytes even when the source is identical.
