Web application modules support for modern or complex web sites.
Copyright (C) 2015-2021 Accessolutions (http://accessolutions.fr)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
See the file COPYING.txt at the root of this distribution for more details.
This is an add-on targeting the NVDA screen reader version 2016.3 or greater.
The following software is required in order to build this add-on:
- a Python distribution (2.7 or greater 32 bits is recommended). Check the Python website for Windows Installers.
- GNU Gettext tools. You can find windows builds here.
Additional requirements (see installation procedure in the next section):
- SCons - Website - version 3.0.0
- Markdown-2.0.1 or greater, to convert documentation files to HTML documents.
The recommended way to setup a Python build environment is to use virtualenv.
It is especially true when using different versions and flavours of the Python interpreter or working on projects that might have conflicting dependencies.
In this section, we will assume your Python 2.7 32 bits interpreter is not
in the PATH environment variable. In later sections, we will assume it
either is or you activated (as we recommend) the dedicated virtual environment.
The following commands use our dev team installation paths, amend according to your needs.
D:\dev\Python27-32\Scripts\pip install virtualenv
md D:\dev\venv
D:\dev\Python27-32\Scripts\virtualenv.exe D:\dev\venv\nvda-addon
We will inject in the new virtual environment references to the targetted NVDA source code and its Python dependencies.
This step is not strictly necessary, but it eases IDE integration and the use of code linters / style checkers.
From the root folder you store your projects in:
git clone --recurse-submodules "https://github.com/nvaccess/nvda.git"
cd nvda
git checkout --recurse-submodules release-2018.3.2
Then, create a .pth file in the site-packages of your virtual
environment containing the paths - in Windows format - to the cloned
source and dependancies, one line for each.
Example of a typical nvda.pth file:
D:\dev\src\nvda\source
D:\dev\src\nvda\include\scons\src\engine
D:\dev\src\nvda\include\pyserial
D:\dev\src\nvda\include\comtypes
D:\dev\src\nvda\include\wxPython
D:\dev\src\nvda\miscDeps\python
This exhaustive list is obtained from looking at the file
source/sourceEnv.py in the NVDA source tree.
Finally, copy the file scons.py from the root of this project to the
Scripts directory of the virtual environment.
This is just a small convenience script allowing easier invocation of the
SCons found in the cloned NVDA sub-module.
The VIRTUAL_ENV variable it defines holds a path in Windows format.
This has no impact if calling Python commands from the same hard disk unit
but would prevent ie. calling a python.exe on drive D: from your home
folder on drive C:.
The script can be patched in-place with the following command:
sed -E -i 's/^(VIRTUAL_ENV=)(.+)$/echo \1\\""$(cygpath \2)"\\"/e' /d/dev/venv/nvda-addon/Scripts/activate
D:\dev\venv\nvda-addon\Script\activate.bat
or from Git Bash:
. /d/dev/venv/nvda-addon/Scripts/activate
Note the leading period, meaning the script is sourced, not run.
Your command prompt should now be prefixed with the name of the virtual environment in parenthesis.
Any subsequent command will be run in the context of this virtual
environment.
The corresponding python.exe is now the first in your PATH environment
variable, whether another one was already present or not.
Furthermore, packages installed via pip will land in this virtual
environment instead of the base Python installation.
You can later run deactivate to leave this virtual environment, but let's
first finish to set it up.
pip install "Markdown>=2.0.1"
Optionally, if you did not create a nvda.pth file the in virtual environment:
pip install "SCons==3.0.0"
The new nvda-addon virtual environment is now ready to build our addon.
Note that it can also be used by many IDEs, such as PyDev for Eclipse, as the interpreter for the project.
This add-on is based upon the addonTemplate from the NVDA Add-ons Team and, as such, is built using SCons.
Depending on your environment, your SCons command might be either scons.py
or scons.bat. As a convention, scons will be used within this document.
The following commands are to be run from the project root folder.
scons pot
The resulting WebAccess.pot file will be created (or updated) in the project
root folder.
scons
The resulting WebAccess-<version>.nvda-addon file will be created (or
updated) in the project root folder.
In order to ease in place execution during development, the manifest
and documentation files generated by the build process are stored within the
source tree, instead of a separate build folder.
To get rid of them:
scons -c
To also get rid of the generated Gettext POT translation file:
scons -c pot
This project follows NVDA standards regarding installation of .nvda-addon
files.
However, one might want to use a development version executed directly from the source tree.
A possible solution is to use file-system junction. Run the following command
from the current user config addons directory:
mklink /J WebAccess <path to the addon folder in the source tree>
Note: Local administrator privileges are required.
In this configuration, run the following command from the same directory to remove the junction, uninstalling the development version:
rd WebAccess