Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tidy development environment documentation #17215

Merged
merged 9 commits into from
Sep 26, 2024
Merged

Tidy development environment documentation #17215

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d004c78
Fixed a number of lint errors to do with wrong number of blank lines
SaschaCowley Sep 25, 2024
8a499e0
Slight restructure of dependencies documentation
SaschaCowley Sep 25, 2024
400bf1a
Fixed a line with multiple sentences
SaschaCowley Sep 25, 2024
2043e28
Fixed in-text references to NV Access to use proper capitalisation an…
SaschaCowley Sep 25, 2024
edfe2a2
Fixed some punctuation
SaschaCowley Sep 25, 2024
3ba180b
Use full name of wil
SaschaCowley Sep 25, 2024
d38c7b6
Add link to git submodules
SaschaCowley Sep 25, 2024
36a2494
Reformatted Visual Studio IDE support to be a single bullet point
SaschaCowley Sep 25, 2024
b0541ec
Apply suggestions from code review
SaschaCowley Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 38 additions & 20 deletions projectDocs/dev/createDevEnvironment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# Create NVDA Development Environment

## Getting the Source Code

The NVDA project uses the [git](https://www.git-scm.com/) version control system for its source code and documentation.

The NVDA repository is located at https://github.com/nvaccess/nvda.
The NVDA repository is located at <https://github.com/nvaccess/nvda>.

If you plan on contributing to NVDA, you will need to [fork and clone](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository.

Expand All @@ -11,48 +14,54 @@ After forking the repository into your user account (`YOUR-USERNAME`), clone wit
git clone --recursive https://github.com/YOUR-USERNAME/nvda.git
```


### Keeping the fork in sync

When you fork the repository, GitHub will create a copy of the master branch.
However, this branch will not be updated when the nvaccess master branch is updated.
To ensure your work is always based on the latest commit in the nvaccess master branch, it is recommended that your master branch be linked to the nvaccess master branch, rather than the master branch in your GitHub fork.
However, this branch will not be updated when the NV Access master branch is updated.
To ensure your work is always based on the latest commit in the `nvaccess/nvda` master branch, it is recommended that your master branch be linked to the `nvaccess/nvda` master branch, rather than the master branch in your GitHub fork.
You can do this from the command line as follows:

```sh
# Add a remote for the NV Access repository.
git remote add nvaccess https://github.com/nvaccess/nvda.git
# Fetch the nvaccess branches.
# Fetch the NV Access branches.
git fetch nvaccess
# Switch to the local master branch.
git checkout master
# Set the local master to use the nvaccess master as its upstream.
# Set the local master to use the NV Access master as its upstream.
git branch -u nvaccess/master
# Update the local master.
git pull
```

## Supported Operating Systems

Although NVDA can run on any Windows version starting from Windows 8.1, building NVDA from source is currently limited to only Windows 10 and above.

## 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

[Python](https://www.python.org/), version 3.11, 32 bit.

To replicate the production build environment, use the 3.11.x minor version of Python that [AppVeyor uses for the Visual Studio 2022 environment](https://www.appveyor.com/docs/windows-images-software/#python).

#### Microsoft Visual Studio

* Microsoft Visual Studio 2022
* To replicate the production build environment, use the [version of Visual Studio 2022 that AppVeyor is using](https://www.appveyor.com/docs/windows-images-software/#visual-studio-2022).
* When you do not use the Visual Studio IDE itself, you can download the [build tools](https://aka.ms/vs/17/release/vs_BuildTools.exe)
* When you are intending to use the Visual Studio IDE (not required for NVDA development), you can download [the community version](https://aka.ms/vs/17/release/vs_Community.exe), which is also used by AppVeyor
* The Professional and Enterprise versions are also supported
* Preview versions are *not* supported
* When installing Visual Studio, additional components must be included
* You can automatically fetch these using [NVDAs .vsconfig](../../.vsconfig) using the [import feature of the VS installer](https://learn.microsoft.com/en-us/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration)
* If you don't use the Visual Studio IDE itself, you can download the [build tools](https://aka.ms/vs/17/release/vs_BuildTools.exe).
* If you do intend to use the Visual Studio IDE (not required for NVDA development), you can download [the community version](https://aka.ms/vs/17/release/vs_Community.exe), which is also used by AppVeyor.
* The Professional and Enterprise versions are also supported.
* Preview versions are *not* supported.
* When installing Visual Studio, additional components must be included:
* You can automatically fetch these using [NVDAs .vsconfig](../../.vsconfig) using the [import feature of the VS installer](https://learn.microsoft.com/en-us/visualstudio/install/import-export-installation-configurations?view=vs-2022#import-a-configuration).
* In the list on the Workloads tab, in the Desktop grouping:
* Desktop development with C++.
* Once selected, ensure "C++ Clang tools for Windows" is included under the optional grouping.
Expand All @@ -64,7 +73,8 @@ To replicate the production build environment, use the 3.11.x minor version of P
* C++ ATL for v143 build tools (ARM64/ARM64EC)

### Git Submodules
Some of the dependencies are contained in Git submodules.

Some of the dependencies are contained in [Git submodules](https://git-scm.com/docs/gitsubmodules).
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.
Expand All @@ -84,16 +94,14 @@ If you aren't sure, run `git submodule update` after every git pull, merge or ch
* Python interface to FTDI driver/chip
* [Nullsoft Install System](https://nsis.sourceforge.io), version 3.08
* [Java Access Bridge 32 bit, from Zulu Community OpenJDK build 17.0.9+8Zulu (17.46.19)](https://github.com/nvaccess/javaAccessBridge32-bin)
* [wil](https://github.com/microsoft/wil/)
* [Windows Implementation Libraries (WIL)](https://github.com/microsoft/wil/)
* [NVDA DiffMatchPatch](https://github.com/codeofdusk/nvda_dmp)

Additionally, the following build time dependencies are included in the miscDeps git submodule:
#### Build time dependencies

* xgettext and msgfmt from [GNU gettext](https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/)

The following dependencies aren't needed by most people, and are not included in Git submodules:
* To generate [developer documentation for nvdaHelper](#building-nvdahelper-developer-documentation): [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15:
The following build time dependencies are included in the miscDeps git submodule:

* xgettext and msgfmt from [GNU gettext](https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/)

#### VS Code

Expand All @@ -111,4 +119,14 @@ The following dependencies aren't needed by most people, and are not included in
```

### Python dependencies
NVDA and its build system also depend on an extensive list of Python packages. They are all listed with their specific versions in the requirements.txt file in the root of this repository. However, the build system takes care of fetching these itself when needed. These packages will be installed into an isolated Python virtual environment within this repository, and will not affect your system-wide set of packages.

NVDA and its build system also depend on an extensive list of Python packages.
They are all listed with their specific versions in the `requirements.txt` file in the root of this repository.
However, the build system takes care of fetching these itself when needed.
These packages will be installed into an isolated Python virtual environment within this repository, and will not affect your system-wide set of packages.

### Other dependencies

The following dependencies aren't needed by most people:

* To generate [developer documentation for nvdaHelper](./buildingDevDocumentation.md#building-nvdahelper-developer-documentation): [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15.