Development Setup

Relevant source files

• .gitignore
• CONTRIBUTING.md
• GOALS.md
• LICENSE
• README.md
• build.go
• build.sh
• cmd/stdiscosrv/README.md
• cmd/strelaysrv/README.md
• cmd/syncthing/crash_reporting.go
• etc/firewall-ufw/README.md
• etc/firewall-ufw/syncthing
• lib/osutil/atomic.go
• lib/osutil/atomic_test.go
• lib/osutil/atomic_unix_test.go
• lib/osutil/lowprio_linux.go
• lib/osutil/lowprio_unix.go
• lib/osutil/lowprio_windows.go
• lib/osutil/osutil.go
• lib/osutil/osutil_test.go
• lib/syncthing/superuser_windows.go

This page covers the setup of a development environment for contributing to Syncthing. It explains how to obtain the source code, install prerequisites, build the project, and run tests. For information about contribution guidelines and code style, see Code Contribution Guidelines. For details on the testing infrastructure, see Testing.

Prerequisites

Required Tools

Syncthing development requires the following tools to be installed:

Tool	Minimum Version	Purpose
Go	As specified in go.mod	Compilation and testing
Git	Any recent version	Source code management

Optional Tools

Additional tools are needed for specific development tasks:

Tool	Purpose	When Required
buf	Protocol buffer generation	When modifying .proto files (see build.go860-864)
goversioninfo	Windows resource file generation	When building for Windows (see build.go686-742)
fpm	Debian package creation	When building .deb packages (see build.go595-662)

Sources: build.go860-864 build.go686-742 build.go595-662

Obtaining the Source Code

Cloning the Repository

Clone the Syncthing repository from GitHub:

For contributors planning to submit pull requests, fork the repository first on GitHub, then clone your fork and add the upstream remote:

Sources: README.md76-81 CONTRIBUTING.md56-58

Build System Overview

Syncthing uses a custom Go-based build system implemented in build.go This script provides a unified interface for building, testing, and packaging across all platforms.

Build Script Architecture

Build System Components

The build script defines multiple target configurations in build.go83-174 each specifying:

• buildPkgs: Go packages to compile build.go69
• archiveFiles: Files to include in distribution archives build.go71
• installationFiles: Files for package installations (e.g., systemd units, man pages) build.go73
• debdeps: Debian package dependencies build.go66

Sources: build.go63-174 build.sh1-37

Basic Build Commands

Building for Development

The simplest way to build all Syncthing components:

When invoked with no arguments, the build script defaults to install all. This builds all packages found in cmd/* and places binaries in the bin/ directory. This is the recommended command during development as it provides maximum error checking across the entire codebase.

Building a Specific Target

To build only the main Syncthing application:

Available targets as defined in build.go83-174:

• syncthing: Main synchronization application build.go88
• stdiscosrv: Discovery server build.go133
• strelaysrv: Relay server build.go159

The built binary will be placed in bin/syncthing (or bin/syncthing.exe on Windows).

Sources: build.go88-174 README.md76-81

Build Script Invocation Methods

Wrapper Script Features

• build.sh1-37 provides shortcuts like ./build.sh test which sets LOGGER_DISCARD=1 to reduce test output noise build.sh17
• The prerelease command in build.sh24-31 runs multiple scripts to prepare for a release, including updating authors build.sh25 copyrights build.sh26 and translations via weblate build.sh27

Sources: build.sh1-37 build.go10-40

Running Tests

Unit Tests

Run the test suite across all packages:

This command:

• Automatically regenerates assets if needed.
• Runs tests with the -short flag by default.
• Uses a 120-second timeout (configurable via -long flag) build.go58

Integration Tests

Run the integration test suite:

The integration tests:

• Use a longer timeout build.go59
• Are located in the test/ directory.

Benchmarks

Run performance benchmarks:

This is often run via the wrapper to discard logs: ./build.sh bench build.sh21

Sources: build.go58-59 build.sh16-22

Code Generation

Asset Generation

GUI assets must be regenerated when files in gui/ change:

The build system automatically checks if assets need regeneration by comparing modification times during normal builds.

Protocol Buffer Generation

When modifying .proto files in the proto/ directory:

This runs buf generate as specified in the build logic.

Test Mock Generation

Generate mock implementations for testing:

Sources: build.go7-10

Build Flags and Options

Common Build Flags

The build script supports numerous flags:

Flag	Description
-goos	Target operating system build.go42
-goarch	Target architecture build.go41
-no-upgrade	Disable upgrade functionality build.go43
-version	Set version string build.go44
-race	Enable race detector build.go46
-debug-binary	Create unoptimized binary for debugging build.go55

Version Management

The build system determines the version using:

1. The version flag build.go44
2. Git tags and commit information.
3. Fallback to "unknown-dev".

Sources: build.go40-61

Development Workflow

Typical Development Cycle

Key Points

1. DCO Sign-off: All commits must include a Signed-off-by line CONTRIBUTING.md75-117
2. Conventional Commits: Commit messages should follow the conventional commits specification CONTRIBUTING.md147-164
3. Coding Style: Use go fmt and follow standard Go review comments CONTRIBUTING.md132-143

Sources: CONTRIBUTING.md75-164 build.go10-40

Build Output and Artifacts

Generated Files and Directories

The build process creates several files and directories listed in .gitignore:

Path	Description
bin/	Compiled binaries .gitignore11
syncthing	Main binary (Unix) .gitignore1
stdiscosrv	Discovery server binary .gitignore2
*.tar.gz, *.zip	Distribution archives .gitignore3-4
coverage.out	Test coverage output .gitignore9

Archive Creation

Create distribution archives:

The targets for these archives are defined in the targets map in build.go83

Sources: .gitignore1-21 build.go83-174

Environment Variables

Build Environment Variables

Variable	Purpose
BUILDDEBUG	Enable debug output in the build script build.go47

Test Environment Variables

Variable	Purpose
LOGGER_DISCARD	Disable log output during tests build.sh17

Sources: build.go47 build.sh17

Package Creation

Debian Packages

Create a .deb package:

The package configuration (dependencies, descriptions, and file mappings) is defined in the target struct for syncthing build.go88-131 and stdiscosrv build.go133-158

The syncthing target includes:

• Binary: /usr/bin/syncthing build.go105
• Systemd units: User and System services build.go119-120
• Firewall presets: UFW configurations build.go122
• Desktop integration: .desktop files and icons build.go123-130

Sources: build.go88-158 etc/firewall-ufw/syncthing1-10