NVDA, the free and open source Screen Reader for Microsoft Windows
Switch branches/tags
ARM64Compat IAccessibleTableUpgrade NVDARemoteControl ThomasStivers-I7477 UIACaching UIAInMSWordByDefault abandoned-t3800 addPerfTimerClass addon-packaging aim-workshop appveyorBuildsPRs aria-goog-editable ariaBrailleInput ariaGrids ariaRoleDescription atlInReadme badUIAPerAppModule beta bitmapTracking brailliantBtHid bufferlessIa2WebExperiment captionBot captionBotWithPillow comPortNoFriendly comtypesUpdate csun16Math deadFocus disableUIAForConsolewindowClass dllExeInSymStore edgeRS1 edgeSpeedup_dynamicControlFields edgeSpeedup espeak-ng-latest espeak_compilePhomemeData espeak1.48.15 espeakEditbuild espeakMasterTest excel_disableAutoPassthrough excelWithUIA execInThread experiment_unitTestingForF9-F10 experiment_useCompiledMSWordInterface extendSpeechRefactor extensionPointsNonDefaultArgsForHandlers fastSAPI5Interuption fasterEdgeHeadingQuickNav filteredPythonConsoleCompletions filteredUIAPresentation fixBrowseSel fixGuiAlignmentIssues fixInstaller fixMergedVBufBackendLibsCrash fixMinhookPathCase fixMozSel fixOrphanedChangesOnNext-forMaster fixOrphanedChangesOnNext fixPyscreeze fixReloadPlugins fixUninitialisedBaseClass focusRedirection gecko64Crash geckoRelationTargetsOfTypeFix getSelectedItemsCount googleDocsTablenavigation googleSheets googleSheetsPrototype guiSpacing handleDeadEdgeTextRanges i1555 i1939 i2591 i2807 i3138 i3321 i4011 i4493 i4561_fixUiLangChange i4636-F10_selects_and_copies i4773_withChrome i4773 i4834-BadRegexInDictCausesCrash i4877SpeechManager i5050-AddOptionForSpeechViewerOnStartup i5050-FixRaceConditionOnExit i5050-RememberPositionOfSpeechViewer i5382NewSounds i5396_halfRegion i5467 i5490-Lock_keys_double_announce i5534 i5544 i5591-HTML5_structural_elements i5641 i5871 i5886-ElementsListNotAppearing i5906 i5927 i5942 i5946-experiment_reportColumnNumber i5946-reportSectionNumber i5998 i6004_WordPageNumbering i6005 i6007OrbitReader i6010 i6015 i6017 i6021 i6024 i6033 i6036 i6047-IFrameVsFrame i6049-ShowAllSpeechInSpeechViewer i6051_imageMapIsIgnoredInFF i6063_updateHanSoneConnect i6096 i6099-useWxSpinCtrl i6101-UpdateSymbolListDialog i6101_SymbolsListCtrl i6102-MSWordCrossRefLinks i6112 i6116MoreBaum i6122 i6127-fixCapsLockToggleAssertion i6127_enableWxAssertions i6159 i6206-OKButtonNotDefault i6216 i6219 i6275-addGuiToAddonCompat i6312-FixMouseInteractionSymbolList i6333_alignOkCancel i6348-documentFormattingDialog i6350-tidyWelcomeDialog i6368-WordFreeze i6374 i6412-EmptyPatternInDictionaryEntry i6430 i6446-numbersInTablesIgnored i6461handyTechGestures i6467 i6467_2 i6470-LimitCursorBlinkRate i6500ExcelEnter i6502ItunesWebFreeze i6555-supportLanguageSwitchingInWord i6570 i6577 i6580 i6594 i6598-mouseTrackingMultiMon i6599-truncatedStringFix i6606 i6611-wordPadRegression i6628 i6641_reintroduceCustomWXPython i6684_alternative i6684 i6705 i6713 i6797 i6848 i6852 i6911 i6948 i6998 i7111 i7143 i7216_i7217 i7243 i7253 i7269 i7281 i7286 i7289 i7308 i7348 i7553 i7574ThreadSafeBrailleNote i7592-convertDictNamesToIDs i7592-fixEspeakDictNames i7601-dontReportLabelAsClickable i7652 i7692-fixWxAssertionOnWelcomeScreen i7696 i7709 i7740-fixEspeakFreezeWithTamilEmoji i7770 i7788-integrateBrailleViewer i7824 i7828 i7840 i7869 i7908 i7960 i7971 i7975 i8032 i8038 i8041 i8064 i8163_updateGuiHelperDocs i8249-replaceApplyButtonAndShortcuts i8407 i8448 i8603 i8609 i8664 i8692 i8759 i8777 i8787 i8924 i8994 ia2EolCaret ia2GrammarError ignoreUIANullNotificationEvents insDelInChrome installed_systemTestWithRobot invalidGeckoVersion javaImprovements killTlbNewerThanMod kindle1.19 kindleTables labelObjects latestEspeak logWxAssertions macCommandKey madaRtl master mathPlayer2014 mathml mergedVBufBackendLibs mergedVbufBackendLibs minorSpeechViewerTweaks modalDialogs mouseRewrite mozLog mozText msaaTestVBuf msvcAnalyze multiCategorySettings next noESpeakEmojis nvWaveEnhancements offsetsUnicodeBeyond16 oneCoreAsDefault oneCoreDisableAppendSilence oneCoreOnFallback perForegroundUIAPropertyChangeEvents pr6241WithMiscDeps pr6467_fix pr7201_fix pr7440_revert pr8898_speakObjectProperties_copyStates rc recogNoLocation recognizeArgs redstone reduceClickables release-2013.1 reportFormatAfterCursorOption reportGenericAriaLabel restoreHandytechServer revert-8742-perForegroundUIAPropertyChangeEvents revert-8879-getSelectedItemsCount revert-8886-reportGenericAriaLabel robotOnAppveyor rpcGetActiveObject saveConfigAfterUsageStatsDialog smartDictionaries sourceDllsNotVersioned speechPlayerInEspeak staging_l10n_2014-11-19_-_20-10-11 superBraile synthBrailleStats systemTestWithRobot t513 t525 t708 t1271a2 t1271 t1668old t1668 t1707 t1846-ie10Msaa t1987 t2003 t2039 t2093 t2209 t2702 t2729 t2961 t2975 t2990 t3503 t3504 t3570 t3680 t3695 t3726 t3731 t3732 t3739 t3791 t3831old t3851 t3860 t3886 t3889 t3934 t3939 t4069 t4103 t4130 t4174 t4176 t4195 t4294 t4305 t4381 t4418 t4499 t4521 t4770 t4772 t4838 t5037 t5060 t5066 t5231 t5323 t5390 t5396 t5926 t5955 t5987 t5997 t6027 t6029 temp-edgeContent textInfoEndpointComparing tonesInThread touchReview try-2017.2WithNewEspeak try-2017.3rc1 try-6355 try-6607 try-7302 try-7762 try-7890 try-7901 try-7930 try-7989 try-8941 try-ARM64Compat try-IAccessibleTableUpgrade try-UIAInMSWordByDefault try-adobeAcrobat_chromium try-aim-workshop try-appveyorTests try-aria-goog-editable try-ariaBrailleInput try-authenticode try-brailliant try-captionBot try-comPortNoFriendly try-comtypes1.1.7 try-eSpeakFix try-edgeSpeedup try-excelScreenUpdating try-fixInstallLogging try-fixInstaller try-fixInstaller2 try-fixInstaller3 try-fixMinhookCase try-fixOutlookCtrlYCrash try-fixPot try-fixPyscreeze try-freedomscientific-native try-germanShortcutKeyFix try-i770 try-i2699contextSensitiveHelp try-i2807 try-i4859VbufUpdateNull try-i6017 try-i6216 try-i6374 try-i6467 try-i6524 try-i6570 try-i6598-mouseTrackingMultiMon try-i6628 try-i6845Serial try-i6911 try-i7021ReaderCrash try-i7111 try-i7124 try-i7216_i7217 try-i7243 try-i7253 try-i7269 try-i7308WithUnhookInprocWinEvent try-i7308 try-i7348 try-i7431OneCoreSpeechDucking try-i7498OcSpeechOptions try-i7553 try-i7687 try-i7709 try-i7740-fixEspeakFreezeWithTamilEmoji try-i7754-zoomChatFix try-i7770 try-i7788-integrateBrailleViewer try-i7975 try-i8149 try-i8249-replaceApplyButtonAndShortcuts try-i8574 try-i8603 try-i8664 try-i8753elementsFilterTree try-i8759 try-i8894 try-i8924 try-i8944 try-i8994 try-iTunesUIAFix try-iaAccNavigateWorkAround try-installed_systemTestWithRobot try-installed_systemTestsWithRobot try-invalidGeckoVersion try-kindle1.19 try-kindleSel try-kindleTables try-kindleWip try-latestEspeak try-liblouis-utf-32 try-liblouis3.7 try-liblouis3.8 try-masterWithNVDAHelperDebug try-mozLog try-mozSyms try-multicatWithScaling try-nextDebug try-nextGecko64Crash try-nextNhDebug try-nextWithIaHt2 try-nextWithInstallLogging try-nextWithInstallerLogging try-noGetPixel try-ocSpeechCharLag try-ocSpeechMulti try-ocSpeechWavParams try-oneCoreFallback try-oneCoreSpeech try-outlookAutoCompleteUIA try-partialVBufRender try-peInSyms try-perForegroundUIAPropertyChangeEvents try-pr-5680 try-pr-7591 try-pr6329 try-pr7440_revert try-pr7566 try-pr7625 try-pr7702 try-pr7725 try-pr7762 try-pr8110 try-pr8159 try-restoreHandytechServer try-revertMinhook try-sconstructDevDocs try-sourceDllsNotVersioned try-speechPlayerInEspeak try-superBraille try-systemTestWithRobot try-tableCell try-taskmanFix try-testBtHIDWithSetOutputReport try-testOldRelease try-transComments try-uiaCacheableValueCOMErrorHandler try-unhookInprocWinEvent try-unitTests try-unregisterUIAProxyWinEvents try-updateEspeak try-vbufPartialRender try-vbufPartialRenderRowFix try-vbufPostMessage try-vision try-w10 try-wdag try-win10sdk try-windows10s_uiAccess try-windows10s try-wordDocumentsWithUIA try-wxPy4 uiaAllInMtaGit uiaAllInMtaMarshal uiaCoalesceEvents unregisterUIAProxyWinEvents updateCheckAssertions updateEspeak-debugBranch updateEspeak updateIssueTemplate updateIssueTemplates updateMiscDeps vbufFocusReading vbufGuessFormFieldLabels vbufInplaceRendering1 vbufPartialRender vbufPartialRenderRowFix vbufPostMessage vc2012 wdag win8_ie_uia win10rs5TaskSwitch win10sdk winEventsInprocess windows7sp1 windows10s_uiAccess windows10s wip_i5758 wordDocumentsWithUIA wxOnAssertFix
Nothing to show
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update issue templates (#9000) Dec 5, 2018
appveyor Merge all vbufBackend dlls into nvdaHelperRemote.dll (#8866) Oct 30, 2018
appx Merge all vbufBackend dlls into nvdaHelperRemote.dll (#8866) Oct 30, 2018
extras/controllerClient Remove extras/NVDA CD, which is extremely outdated and no longer useful. Apr 30, 2014
include Update liblouis to version 3.8, add debug logging functionality and c… Dec 6, 2018
launcher Allow add-ons to supply version compatibility information in manifest… Dec 6, 2018
miscDeps @ 3a00653 Update miscDeps to latest. (PR #8629) Aug 15, 2018
nvdaHelper Update liblouis to version 3.8, add debug logging functionality and c… Dec 6, 2018
site_scons/site_tools Python 3 imports: try importing Python 3 version before resorting to … Aug 22, 2018
source Merge branch 'beta' Dec 10, 2018
tests Allow add-ons to supply version compatibility information in manifest… Dec 6, 2018
uninstaller Provide programmatic version information in all of our executables an… Sep 1, 2016
user_docs Merge branch 'beta' Dec 10, 2018
.gitattributes Added .gitattributes Nov 15, 2013
.gitignore Use Unicode CLDR to create speech symbol dictionaries with emojis (#8758 Sep 25, 2018
.gitmodules Use Unicode CLDR to create speech symbol dictionaries with emojis (#8758 Sep 25, 2018
appveyor.yml appveyor: manually grab pyscreeze 0.1.13 as latest release is complet… Jul 19, 2018
cldrDict_sconscript Emojis: build data for Vietnamese and Chinese variants. re #8799. (#8803 Oct 5, 2018
contributors.txt Add Bachir Benanou to contributors.txt who has been a key french tran… May 7, 2018
copying.txt Revert minhook back to version 1.2.2 (#8456) Jun 28, 2018
developerGuide.t2t Allow add-ons to supply version compatibility information in manifest… Dec 6, 2018
keyCommandsDoc.py In the User Guide, when a %kc:setting command is used for a setting w… Mar 30, 2016
readme.md Update liblouis to version 3.8, add debug logging functionality and c… Dec 6, 2018
scons.bat Use Python launcher if present (#7541) Feb 2, 2018
scons.py Add scripts to allow scons to be run just by typing scons at the root… Dec 10, 2013
sconstruct Use Unicode CLDR to create speech symbol dictionaries with emojis (#8758 Sep 25, 2018

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 2.7.15, 32 bit
  • 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 Summary list, under Desktop for C++, Optional grouping, ensure the following is 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

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 dependencies are included in Git submodules:

Other Dependencies

These dependencies are not included in Git submodules, but aren't needed by most people.

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.

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.

To generate developer documentation, type:

scons devDocs

The developer docs will be placed in the devDocs folder in the output directory.

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.

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.

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

scons pot

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. Currently, NVDA has two kinds of automated testing: unit tests and translatable string checks.

To run the tests, first change directory to the root of the NVDA source distribution as above. Then, run:

scons 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

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

scons checkPot

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"