From 1573904b17722303f66434804cd515fc012b78af Mon Sep 17 00:00:00 2001 From: Sascha Cowley <16543535+SaschaCowley@users.noreply.github.com> Date: Thu, 26 Sep 2024 17:37:35 +1000 Subject: [PATCH] Tidy development environment documentation (#17215) Summary of the issue: The development environment documentation has a number of lint violations and inconsistencies. Description of user facing changes The development environment documentation has been slightly updated to be easier to read. Description of development approach - Fixed lint errors to do with headings and code blocks not being surrounded by blank lines. - Slightly restructured dependency documentation so that submodules are organised into run time, build time and VS Code dependencies. - Moved the reference to Doxygen to a new "Other dependencies" section. - Fixed a couple of violations of the one-sentence-per-line rule. - Changed in-text references to NV Access to use proper capitalisation and spacing ("NV Access" rather than "nvaccess" or a reference to our NVDA repo (`nvaccess/nvda`)) - Fixed some sentences not ending with full stops or colons. - Changed the reference to WIL to call it "Windows Implementation Libraries (WIL)" - Linked to the git submodules documentation. --- projectDocs/dev/createDevEnvironment.md | 58 ++++++++++++++++--------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/projectDocs/dev/createDevEnvironment.md b/projectDocs/dev/createDevEnvironment.md index 0042c366354..8bc0f04ac86 100644 --- a/projectDocs/dev/createDevEnvironment.md +++ b/projectDocs/dev/createDevEnvironment.md @@ -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 . 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. @@ -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. @@ -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. @@ -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 @@ -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.