NVDA Add-on Scons Template
This package contains a basic template structure for NVDA add-on development, building, distribution and localization. For details about NVDA add-on development, please see the NVDA Add-on Development Guide. The NVDA add-on development/discussion list is here
Copyright (C) 2012-2021 NVDA Add-on team contributors.
This package is distributed under the terms of the GNU General Public License, version 2 or later. Please see the file COPYING.txt for further details.
This template provides the following features you can use during NVDA add-on development and packaging:
- Automatic add-on package creation, with naming and version loaded from a centralized build variables file (buildVars.py) or command-line interface.
- See packaging section for details on using command-line switches when packaging add-ons with custom version information.
- Manifest file creation using a template (manifest.ini.tpl). Build variables are replaced on this template. See below for add-on manifest specification.
- Compilation of gettext mo files before distribution, when needed.
- To generate a gettext pot file, please run scons pot. A addon-name.pot file will be created with all gettext messages for your add-on. You need to check the buildVars.i18nSources variable to comply with your requirements.
- Automatic generation of manifest localization files directly from gettext po files. Please make sure buildVars.py is included in i18nFiles.
- Automatic generation of HTML documents from markdown (.md) files, to manage documentation in different languages.
You need the following software to use this code for your NVDA add-on development and packaging:
- a Python distribution (3.7 or later is recommended). Check the Python Website for Windows Installers.
- Scons - Website - version 3.1.0 or later. You can instlal it via PIP.
- GNU Gettext tools, if you want to have localization support for your add-on - Recommended. Any Linux distro or cygwin have those installed. You can find windows builds here.
- Markdown 3.1.0 or later, if you want to convert documentation files to HTML documents. You can install it via PIP.
To create a new NVDA add-on using this template:
- Create an empty folder to hold the files for your add-on.
- Copy the site_scons folder, and the following files, into your new empty folder: buildVars.py, manifest.ini.tpl, manifest-translated.ini.tpl, sconstruct, .gitignore, and .gitattributes
- Create an addon folder inside your new folder. Inside the *addon folder, create needed folders for the add-on modules (e.g. appModules, synthDrivers, etc.). An add-on may have one or more module folders.
- In the buildVars.py file, change variable addon_info with your add-on's information (name, summary, description, version, author and url).
- Put your code in the usual folders for NVDA extension, under the addon folder. For instance: globalPlugins, synthDrivers, etc.
- Gettext translations must be placed into addon\locale<lang>/LC_MESSAGES\nvda.po.
Add-on manifest specification
An add-on manifest generated manually or via buildVars.py must include the following information:
- Name (string): a unique identifier for the add-on. It must use camel case (e.g. someModule).
- Summary (string): name as shown on NVDA's Add-ons Manager.
- Description (string): a short detailed description about the add-on.
- Version (string)
- Author (string and an email address): one or more add-on author contact information in the form "name email@address".
- URL (string): a web address where the add-on information can be found (typically community add-ons website address (https://addons.nvda-project.org) is used).
- docFileName (string): name of the documentation file.
- minimumNVDAVersion (year.major or year.major.minor): the earliest version of NVDA the add-on is compatible with (e.g. 2019.3). Add-ons are expected to use features introduced in this version of NVDA or declare compatibility with it.
- lastTestedNVDAVersion (year.major or year.major.minor): the latest or last tested version of NVDA the add-on is said to be compatible with (e.g. 2020.3). Add-on authors are expected to declare this value after testing add-ons with the version of NVDA specified.
- addon_updateChannel (string or None): the update channel for the add-on release.
To manage documentation files for your addon:
- Copy the readme.md file for your add-on to the first created folder, where you copied buildVars.py. You can also copy style.css to improve the presentation of HTML documents.
- Documentation files (named readme.md) must be placed into addon\doc<lang>/.
To package the add-on for distribution:
- Open a command line, change to the folder that has the sconstruct file (usually the root of your add-on development folder) and run the scons command. The created add-on, if there were no errors, is placed in the current directory.
- You can further customize variables in the buildVars.py file.
- You can also customize version and update channel information from command line by passing the following switches when running scons:
- version: add-on version string.
- channel: update channel (do not use this switch unless you know what you are doing).
- dev: suitable for development builds, names the add-on according to current date (yyyymmdd) and sets update channel to "dev".
Note that this template only provides a basic add-on structure and build infrastructure. You may need to adapt it for your specific needs.
If you have any issues please use the NVDA addon list mentioned above.