Getting Started (Developer)#

This guide explains how to set up your environment, build, and run bgscan locally for development.

Read first: Contributing — branching, commit conventions, and PR workflow.

Prerequisites#

• Go 1.27+ (see go.mod for the exact version)
• Git
• For Android builds: Android NDK

1. Clone the repository#

git clone https://github.com/MohsenBg/bgscan.git
cd bgscan

2. Create a branch#

git checkout -b feature/my-change

See Contributing for branch naming conventions.

3. Install dependencies#

bgscan uses a companion tool called bgscan-builder to fetch and build the project’s dependencies. The install scripts download it for you, place it in the project root, and use it to fetch the correct dependency build for your OS/architecture.

Linux / macOS

./scripts/install-deps.sh

Windows

./scripts/install-deps.ps1

This script will:

1. Download bgscan-builder into the project root.
2. Run bgscan-builder setup-dev --project-dir <project-root> to download the correct dependencies for your OS/arch and place them in the right directory.

4. Build and run#

Once dependencies are installed:

go mod tidy
go run ./cmd/bgscan/

The startup health checks run first. Once they pass, press Enter to enter the TUI.

Building Releases#

To build release artifacts, you also need bgscan-builder. If you don’t already have it from the dependency step, install it:

Linux / macOS

./scripts/install-builder.sh

Windows

./scripts/install-builder.ps1

Build commands#

bgscan-builder release -os linux -arch amd64
bgscan-builder release -os android -arch arm64 -ndk-dir /opt/android-ndk
bgscan-builder release -os all -arch all -dest ./dist

Building for Android#

Android builds require the Android NDK. Pass its path with -ndk-dir:

bgscan-builder release -os android -arch arm64 -ndk-dir /opt/android-ndk

bgscan-builder reference#

A small Go CLI for managing the project. The same binary is used for three workflows:

• install / update — resolve a bgscan release, verify its checksum, and place it on disk. (Run by the user-facing installer.)
• release — assemble dependencies (Xray, Slipstream) and build a release binary for a target OS/arch.
• setup-dev — download the correct dependency binaries for the host so go run ./cmd/bgscan/ works locally.

Flags: