Building NVDA

Comprehensive guide to building NVDA from source, including preparing the source tree, creating binary builds, and customizing builds

Prerequisites

Before building NVDA, ensure you have:

• Completed the development environment setup
• Cloned the NVDA repository with submodules
• Installed Python 3.13.12, Visual Studio 2022/2026, and uv

All build commands should be run from the root directory of the NVDA repository in a command prompt or PowerShell.

Preparing the Source Tree

Before running NVDA or creating builds, you must prepare the source tree:

scons source

This command:

• Compiles C++ components (nvdaHelper)
• Generates COM interfaces
• Processes dependencies
• Sets up the development environment

When to Rebuild

Run scons source again whenever:

• The version of comtypes changes
• Language files are added or changed
• Git submodules are updated
• C++ code in nvdaHelper is modified

Including User Documentation

To access user documentation from the Help menu while running from source:

scons source user_docs

Building user documentation is slower because it regenerates each time the revision number changes. For routine development, scons source alone is faster.

Build Performance Optimization

Speed up builds by using multiple CPU cores:

Using Specific Core Count

scons source -j 4

Replace 4 with the number of cores you want to use.

Using All Available Cores

scons source --all-cores

Building across multiple cores can cause scrambled output and occasionally build errors.

Troubleshooting Build Errors

If you experience errors with multi-threaded builds, force a serial build:

scons source -j 1

This makes tracking down issues easier and may resolve intermittent errors.

Running the Source Code

After preparing the source tree, launch NVDA directly from source:

runnvda.bat

Command Line Options

View all available options:

runnvda.bat -h

or

runnvda.bat --help

These arguments are documented in the NVDA user guide.

Running from source is the fastest way to test changes during development. You don’t need to create full binary builds for routine testing.

Making Binary Builds

Binary builds can run on systems without Python or NVDA’s development dependencies. These are used for snapshots and releases.

Non-Archived Binary Build

Create a portable build without archiving:

scons dist

The build is created in the dist/ directory.

This is equivalent to an extracted portable archive and useful for testing the full distribution without creating installer packages.

Building the Installer

Create a launcher archive (one executable that allows installation or portable distribution):

scons launcher

The launcher executable is placed in the output/ directory.

File naming:

• Release builds: nvda_<version>.exe
• Snapshot builds: nvda_snapshot_<version>.exe

Additional Build Targets

Debug Symbols Archive

Generate an archive of debug symbols for DLL/EXE binaries:

scons symbolsArchive

Output: output/nvda_<version>_debugSymbols.zip

Debug symbols are essential for analyzing crash dumps and debugging release builds.

Translation Template

Generate a gettext translation template for translators:

scons pot

Output: output/nvda.pot

Controller Client

Build the controller client library:

scons client

Output: output/nvda_<version>_controllerClient.zip

Developer Documentation

Generate developer documentation (requires Doxygen):

scons devDocs

Customizing Builds

Build behavior can be customized using command-line variables:

Available Build Variables

version · string

The version of this build

scons launcher version=2024.1.0

version_build · string · default: "0"

A unique number for this build

scons launcher version_build=12345

release · boolean · default: "false"

Whether this is a release version

Enables:

• C++ compiler optimizations (/O2)
• Whole-program optimization
• Optimized Python bytecode

scons launcher release=1

publisher · string

The publisher of this build

scons launcher publisher="My Organization"

certFile · path

Certificate file for code signing (PFX format with private key)

scons launcher certFile=certificate.pfx

certPassword · string

Password for the signing certificate’s private key

scons launcher certFile=cert.pfx certPassword=mypassword

certTimestampServer · url

URL of the timestamping server for authenticode signatures

scons launcher certFile=cert.pfx certTimestampServer=http://timestamp.digicert.com

outputDir · path · default: "output"

Directory where final built archives are placed

scons launcher outputDir=releases

Example: Custom Version Build

scons launcher version=test1

This creates a launcher named nvda_snapshot_test1.exe in the output/ directory.

Example: Signed Release Build

scons launcher release=1 certFile=mycert.pfx certPassword=secret certTimestampServer=http://timestamp.digicert.com

Code signing requires a valid code signing certificate. For production releases, NV Access uses their own certificate.

Build Targets Summary

source

Prepare source tree for development

scons source

dist

Create non-archived binary build

scons dist

launcher

Build installer executable

scons launcher

symbolsArchive

Generate debug symbols archive

scons symbolsArchive

pot

Create translation template

scons pot

client

Build controller client

scons client

Build System Details

SCons Build System

NVDA uses SCons version 4.10.1 as its build system. SCons is a Python-based build tool similar to Make.

Key SCons files:

• sconstruct - Main build configuration (720 lines)
• */sconscript - Module-specific build scripts

Build Architectures

NVDA builds components for multiple architectures:

• x86 (32-bit) - Legacy Windows support
• x86_64 (64-bit) - Primary Windows architecture
• ARM64 - Native ARM Windows support
• ARM64EC - ARM64 with x64 emulation compatibility

Python Virtual Environment

The build system automatically creates and manages a Python virtual environment:

SCons must be executed through scons.bat from the repository root. Running SCons directly from outside the virtual environment will fail.

Advanced Build Configuration

nvdaHelper Debug Flags

For C++ component debugging:

scons source nvdaHelperDebugFlags=debugCRT,RTC

Available flags:

• debugCRT - Use debug C runtime
• RTC - Runtime checks
• analyze - Static analysis

nvdaHelper Log Level

Control logging verbosity (0-59, lower is more verbose):

scons source nvdaHelperLogLevel=10

Default: 15

Cleaning Builds

Remove built files:

scons -c

Clean specific targets:

scons -c dist
scons -c launcher

Troubleshooting

Build fails with 'SCons was started outside virtual environment'

Always use scons.bat from the repository root, not the system-wide SCons command:

# Correct
scons source

# Incorrect
python -m SCons source

Multi-threaded build produces errors

Force single-threaded build:

scons source -j 1

Comtypes changes not reflected

Rebuild the source tree:

scons -c source
scons source

Missing Visual Studio components

Verify all required components are installed:

where cl.exe
where link.exe

Should show paths to Visual Studio 2022 or 2026 build tools.

Code signing fails

Ensure:

• Certificate file exists and is in PFX format
• Certificate password is correct
• Timestamp server is accessible
• Certificate is valid for code signing

Next Steps

Running from Source

Learn how to run and test NVDA from source

Development Overview

Understand NVDA’s architecture and development workflow

Additional Resources

For more details, see:

• sconstruct (line 1-720 in /home/daytona/workspace/source/sconstruct)
• projectDocs/dev/buildingNVDA.md in the source tree