Skip to content
NVDA, the free and open source Screen Reader for Microsoft Windows
Python C++ C NSIS Makefile C#
Branch: master
Clone or download
DataTriny and feerrenrut ExitDialog: Align OK and Cancel buttons to the right (PR #10076)
In most NVDA and Windows dialogs, the OK and Cancel buttons are aligned to the right.
This change makes the exit dialog consistent.
Latest commit 12f27ac Oct 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Request for behavior of other NVDA versions Apr 11, 2019
appveyor Python 3: Fix use of subprocess (#9716) Jun 11, 2019
appx Python 3: Fix use of subprocess (#9716) Jun 11, 2019
extras/controllerClient Added C# example for NVDA controller client DLL (PR #9600) May 21, 2019
include Update liblouis to commit 58d67e63 (#10168) Oct 4, 2019
launcher Allow add-ons to supply version compatibility information in manifest… Dec 6, 2018
miscDeps @ e204946 Update miscDeps to contain new brlApi module (#9812) Jun 26, 2019
nvdaHelper Report hidden formatting in MS Word (#10313) Oct 7, 2019
site_scons/site_tools Update Scons build environment to run on Python 3 (#9667) Jun 11, 2019
source ExitDialog: Align OK and Cancel buttons to the right (PR #10076) Oct 19, 2019
tests Abstract vision framework with included support for focus, navigator … Aug 12, 2019
uninstaller Provide programmatic version information in all of our executables an… Sep 1, 2016
user_docs
.gitattributes Added .gitattributes Nov 15, 2013
.gitignore Add reference to readme for visual studio code project repository (PR #… Oct 2, 2019
.gitmodules Update dependencies for Python 3 (#9630) Jun 9, 2019
appveyor.yml Remove threshold and threshold_py3_staging from branches to automatic… Sep 1, 2019
cldrDict_sconscript Modify NVDA behavior with CLDR characters (#9707) Oct 4, 2019
contributors.txt Update contributors file Aug 6, 2019
copying.txt Revert minhook back to version 1.2.2 (#8456) Jun 28, 2018
developerGuide.t2t Update Developer Guide re. tab completion (PR #9935) Jul 19, 2019
keyCommandsDoc.py txt2tags for python3 #8734 (#9648) Jun 11, 2019
readme.md Update readme links: use HTTPS (PR #10315) Oct 4, 2019
scons.bat Update Scons build environment to run on Python 3 (#9667) Jun 11, 2019
scons.py Update Scons build environment to run on Python 3 (#9667) Jun 11, 2019
sconstruct Bundle Universal CRT libraries when creating NVDA distribution. (#10347) Oct 7, 2019

readme.md

NVDA

NVDA (NonVisual Desktop Access) is a free, open source screen reader for Microsoft Windows. It is developed by NV Access in collaboration with a global community of contributors. To learn more about NVDA or download a copy, visit the main NV Access website.

Key Project Links

Getting the Source Code

The NVDA project uses the Git version control system for its source code and documentation.

The NVDA Git repository is located at https://github.com/nvaccess/nvda.git. You can clone it with the following command, which will place files in a directory named nvda:

git clone --recursive https://github.com/nvaccess/nvda.git

The --recursive option is needed to retrieve various Git submodules we use.

Dependencies

The NVDA source depends on several other packages to run correctly.

Installed Dependencies

The following dependencies need to be installed on your system:

  • Python, version 3.7, 32 bit
    • Use latest minor version if possible.
  • Microsoft Visual Studio 2017 Community, Version 15.3 or later:
    • Download from https://visualstudio.microsoft.com/downloads/
    • When installing Visual Studio, you need to enable the following: On the Workloads tab, in the Windows group: * Universal Windows Platform Development * Desktop development with C++
      • Then in the Installation details section, under Desktop for C++, Optional grouping, ensure the following are selected:
        • VC++ 2017 v141 toolset (x86,x64)
        • Windows 10 SDK (10.0.17134.0) for Desktop C++ x86 and x64
        • Visual C++ ATL for x86 and x64
      • In the Installation details section, under Individual components, ensure the following are selected:
        • Visual C++ compilers and libraries for ARM64
        • Visual C++ ATL for ARM64

Git Submodules

Most of the dependencies are contained in Git submodules. If you didn't pass the --recursive option to git clone, you will need to run git submodule update --init. Whenever a required submodule commit changes (e.g. after git pull), you will need to run git submodule update. If you aren't sure, run git submodule update after every git pull, merge or checkout.

For reference, the following run time dependencies are included in Git submodules:

Additionally, the following build time dependencies are included in Git submodules:

Other Dependencies

To lint using Flake 8 locally using our SCons integration, some dependencies are installed (automatically) via pip. Although this must be run manually, developers may wish to first configure a Python Virtual Environment to ensure their general install is not affected.

  • Flake8
  • Flake8-tabs

The following dependencies aren't needed by most people, and are not included in Git submodules:

  • To generate developer documentation for nvdaHelper: Doxygen Windows installer, version 1.8.15:

  • When you are using Visual Studio Code as your integrated development environment of preference, you can make use of our prepopulated workspace configuration for Visual Studio Code. While this VSCode project is not included as a submodule in the NVDA repository, you can easily check out the workspace configuration in your repository by executing the following from the root of the repository.

    git clone https://github.com/nvaccess/vscode-nvda.git .vscode

Preparing the Source Tree

Before you can run the NVDA source code, you must prepare the source tree. You do this by opening a command prompt, changing to the root of the NVDA source distribution and typing:

scons source

You should do this again whenever the version of comtypes changes or language files are added or changed. Note that if you want to access user documentation from the help menu while running the source version, you will also need to add user_docs to the command line like so:

scons source user_docs

While simply testing or committing changes, it may be faster usually just doing scons source as user documentation will change each time the revision number changes.

Compiling NVDAHelper with Debugging Options

Among other things, preparing the source tree builds the NVDAHelper libraries.
If trying to debug nvdaHelper, you can control various debugging options with the nvdaHelperDebugFlags command line variable. It takes one or more of the following flags:

  • debugCRT: the libraries will be linked against the debug C runtime and assertions will be enabled. (By default, the normal CRT is used and assertions are disabled.)
  • RTC: runtime checks (stack corruption, uninitialized variables, etc.) will be enabled. (The default is no runtime checks.)
  • analyze: runs MSVC code analysis on all nvdaHelper code, holting on any warning. (default is no analysis).

The special keywords none and all can also be used in place of the individual flags.

An example follows that enables debug CRT and runtype checks

scons source nvdaHelperDebugFlags=debugCRT,RTC

Symbol pdb files are always produced when building, regardless of the debug flags. However, they are not included in the NVDA distribution. Instead, scons symbolsArchive will package them as a separate archive.

By default, builds also do not use any compiler optimizations. Please see the release keyword argument for what compiler optimizations it will enable.

Running the Source Code

To start NVDA from source code, run nvda.pyw located in the source directory. To view help on the arguments that NVDA will accept, use the -h or --help option. These arguments are also documented in the user guide. Since NVDA is a Windows application (rather than command line), it is best to run it with pythonw.exe. However, if during development you encounter an error early in the startup of NVDA, you can use python.exe which is likely to give more information about the error.

Building NVDA

A binary build of NVDA can be run on a system without Python and all of NVDA's other dependencies installed (as we do for snapshots and releases).

Binary archives and bundles can be created using scons from the root of the NVDA source distribution. To build any of the following, open a command prompt and change to this directory.

To make a non-archived binary build (equivalent to an extracted portable archive), type:

scons dist

The build will be created in the dist directory.

Building the installer

To create a launcher archive (one executable allowing for installation or portable dist generation), type:

scons launcher

The archive will be placed in the output directory.

Building the developer documentation

To generate the NVDA developer guide, type:

scons developerGuide

The developer guide will be placed in the devDocs folder in the output directory. Note that the Python 3 sources of NVDA currently do not support building NVDA developer documentation using the scons devDocs command.

To generate developer documentation for nvdaHelper (not included in the devDocs target):

scons devDocs_nvdaHelper

The documentation will be placed in the devDocs\nvdaHelper folder in the output directory.

Generate debug symbols archive

To generate an archive of debug symbols for the various dll/exe binaries, type:

scons symbolsArchive

The archive will be placed in the output directory.

Generate translation template

To generate a gettext translation template (for translators), type:

scons pot

Customising the build

Optionally, the build can be customised by providing variables on the command line:

  • version: The version of this build.
  • release: Whether this is a release version.
    • This enables various C++ compiler optimizations such as /O2 and whole-program optimization.
    • It also instructs Python to generate optimized byte code.
  • publisher: The publisher of this build.
  • certFile: The certificate file with which to sign executables. The certificate must be in pfx format and contain the private key.
  • certPassword: The password for the private key in the signing certificate. If omitted, no password will be assumed.
  • certTimestampServer: The URL of the timestamping server to use to timestamp authenticode signatures. If omitted, signatures will not be timestamped.
  • outputDir: The directory where the final built archives and such will be placed.
  • targetArchitectures: The target architectures that NVDA should support. Possible values are all, x86 and x86_64. This should generally be left as the default.

For example, to build a launcher with a specific version, you might type:

scons launcher version=test1

Running Automated Tests

If you make a change to the NVDA code, you should run NVDA's automated tests. These tests help to ensure that code changes do not unintentionally break functionality that was previously working.

To run the tests (unit tests, translatable string checks), first change directory to the root of the NVDA source distribution as above. Then, run:

scons tests

Unit tests

To run only specific unit tests, specify them using the unitTests variable on the command line. The tests should be provided as a comma separated list. Each test should be specified as a Python module, class or method relative to the tests\unit directory. For example, to run only methods in the TestMove and TestSelection classes in the file tests\unit\test_cursorManager.py file, run this command:

scons tests unitTests=test_cursorManager.TestMove,test_cursorManager.TestSelection

Translatable string checks

To run only the translatable string checks (which check that all translatable strings have translator comments), run:

scons checkPot

Linting your changes

In order to ensure your changes comply with NVDA's coding style you can run the Flake8 linter locally. Some developers have found certain linting error messages misleading, these are clarified in tests/lint/readme.md. Running via SCons will use Flake8 to inspect only the differences between your working directory and the specified base branch. If you create a Pull Request, the base branch you use here should be the same as the target you would use for a Pull Request. In most cases it will be origin/master.

scons lint base=origin/master

To be warned about linting errors faster, you may wish to integrate Flake8 other development tools you are using. For more details, see tests/lint/readme.md

System Tests

You may also use scons to run the system tests, though this will still rely on having set up the dependencies (see tests/system/readme.md).

scons systemTests

To run only specific system tests, specify them using the filter variable on the command line. This filter accepts wildcard characters.

scons systemTests filter="Read welcome dialog"

Contributing to NVDA

If you would like to contribute code or documentation to NVDA, you can read more information in our contributing guide.

You can’t perform that action at this time.