From 039403e8a341a03782adabb935d23d950c958482 Mon Sep 17 00:00:00 2001 From: Jeff Rowberg Date: Mon, 17 Jan 2022 17:42:24 -0500 Subject: [PATCH 1/3] Improve Windows dev environment documentation --- windows/README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/windows/README.md b/windows/README.md index 08a9f37c7..d306e0c33 100644 --- a/windows/README.md +++ b/windows/README.md @@ -5,4 +5,60 @@ Some of the development helpers rely on `bash` being available. You can use the version provided by the official `git` installer. +For the quickest way to get started developing in Windows, use WinPython, *not* +Anaconda/Miniconda. Some users report impossible dependency/build headaches when +initializing a development environment starting from a base Miniconda3 +installation that is otherwise working perfectly. + +You will also need Microsoft Build Tools and an SDK appropriate for your +operating system. These are required in order to build the `plover-stroke` +package, which contains C code and does not currently have cross-platform Python +wheel packages available. These two tools can be downloaded from their official +sources here: + +- https://winpython.github.io/ +- https://visualstudio.microsoft.com/visual-cpp-build-tools/ + +**NOTE 1:** You can choose whichever WinPython release you want (32-bit/64-bit), +including the smallest "dot" releases that contain only the bare minimum +required for a functional Python interpreter. If you choose this or any other +pre-built installer that does not include the `tox` package, you will need to +install it with `pip` later. + +**NOTE 2:** There seem to be many sources for various MS Build Tools installers, +even from Microsoft. The above link is the correct one as of early 2022. When +you run the installer, make sure you select **both** the SDK for your Windows +version and the build tools for it. As of early 2022, you should choose +**"Windows 10 SDK (10.0.19041.0)"** and **"MSVC v142 - VS 2019 C++ x64/x86 build +tools (Latest)"**, assuming you are running Windows 10. This unfortunately +requires many gigabytes of data for a task that only needs perhaps 20 MB of +binary utilities and header files, but such is life. + +Once you have installed WinPython, the MS Build Tools, and the Windows SDK, +browse to your WinPython installation folder (e.g. `C:\Python\WPy32-3980`) and +run the "WinPython Command Prompt" shortcut. You should be able to confirm a +working environment by typing `python -V` and seeing the expected version +displayed. If you haven't already, install `tox` using by typing +`python -m pip install tox`. Finally, run the following to make sure the MS +Build Tools have been made available in your PATH for the development session: + +``` +"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars32.bat" +``` + +*(This path may change in the future with new versions of the SDK)* + +At this point, you can navigate to the `/openstenoproject/plover` folder where +you have cloned this project and try running the application from source using +the command `tox -e launch`. It will take a while the first time as it +downloads, builds, and installs everything, but you should be greeted with +Plover's main UI window after the initial build completes. + +This giant set of hoops for MS Build Tools support *should* only be necessary +the first time you run Plover and get all of its dependencies installed, since +`plover-stroke` will not need to be rebuilt every time (unless, of course, you +are modifying the `plover-stroke` source). + +Finally, breathe a sigh of relief and start doing the *real* development work. + See the [developer guide](../doc/developer_guide.md) for the rest of the steps. From 8d6fe33cc6d17e1f8ca173a48f03c7e04e40e961 Mon Sep 17 00:00:00 2001 From: Jeff Rowberg Date: Mon, 17 Jan 2022 20:52:40 -0500 Subject: [PATCH 2/3] Simplify updated Windows instructions --- windows/README.md | 62 ++++++++++++----------------------------------- 1 file changed, 16 insertions(+), 46 deletions(-) diff --git a/windows/README.md b/windows/README.md index d306e0c33..bdfc6fbc0 100644 --- a/windows/README.md +++ b/windows/README.md @@ -8,57 +8,27 @@ version provided by the official `git` installer. For the quickest way to get started developing in Windows, use WinPython, *not* Anaconda/Miniconda. Some users report impossible dependency/build headaches when initializing a development environment starting from a base Miniconda3 -installation that is otherwise working perfectly. - -You will also need Microsoft Build Tools and an SDK appropriate for your -operating system. These are required in order to build the `plover-stroke` -package, which contains C code and does not currently have cross-platform Python -wheel packages available. These two tools can be downloaded from their official -sources here: +installation that is otherwise working. WinPython is available here: - https://winpython.github.io/ -- https://visualstudio.microsoft.com/visual-cpp-build-tools/ - -**NOTE 1:** You can choose whichever WinPython release you want (32-bit/64-bit), -including the smallest "dot" releases that contain only the bare minimum -required for a functional Python interpreter. If you choose this or any other -pre-built installer that does not include the `tox` package, you will need to -install it with `pip` later. - -**NOTE 2:** There seem to be many sources for various MS Build Tools installers, -even from Microsoft. The above link is the correct one as of early 2022. When -you run the installer, make sure you select **both** the SDK for your Windows -version and the build tools for it. As of early 2022, you should choose -**"Windows 10 SDK (10.0.19041.0)"** and **"MSVC v142 - VS 2019 C++ x64/x86 build -tools (Latest)"**, assuming you are running Windows 10. This unfortunately -requires many gigabytes of data for a task that only needs perhaps 20 MB of -binary utilities and header files, but such is life. -Once you have installed WinPython, the MS Build Tools, and the Windows SDK, -browse to your WinPython installation folder (e.g. `C:\Python\WPy32-3980`) and -run the "WinPython Command Prompt" shortcut. You should be able to confirm a -working environment by typing `python -V` and seeing the expected version -displayed. If you haven't already, install `tox` using by typing -`python -m pip install tox`. Finally, run the following to make sure the MS -Build Tools have been made available in your PATH for the development session: +Make sure that you select a **64-bit** WinPython release that is >= 3.6. The +smallest available package is fine (the "dot" version with only the bare minimum +required to run Python) since `tox` handles dependencies. However, you will need +to install `tox` using `pip` once before proceeding. -``` -"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars32.bat" -``` +**NOTE**: If you are intending to develop specifically inside the `plover-stroke` +module, you will also need Microsoft Build Tools and an SDK appropriate for your +operating system. This is because the `plover-stroke` module contains C code +rather than just native Python code. **Most people will not need to do this.** +The Microsoft Build Tools installer is available here: -*(This path may change in the future with new versions of the SDK)* - -At this point, you can navigate to the `/openstenoproject/plover` folder where -you have cloned this project and try running the application from source using -the command `tox -e launch`. It will take a while the first time as it -downloads, builds, and installs everything, but you should be greeted with -Plover's main UI window after the initial build completes. - -This giant set of hoops for MS Build Tools support *should* only be necessary -the first time you run Plover and get all of its dependencies installed, since -`plover-stroke` will not need to be rebuilt every time (unless, of course, you -are modifying the `plover-stroke` source). +- https://visualstudio.microsoft.com/visual-cpp-build-tools/ -Finally, breathe a sigh of relief and start doing the *real* development work. +When you run the installer, make sure you select **both** the SDK for your +Windows version and the build tools for it (e.g. Windows 10 SDK, MSVC v142). +You will also need to run the appropriate `vcvars64.bat` file from the build +tools installation inside of your Python environment to establish the correct +paths, which is found in a subfolder of `\Program Files (x86)\Microsoft Visual Studio\`. See the [developer guide](../doc/developer_guide.md) for the rest of the steps. From b4e25ce299d94ccc64296f17101e903224c05b71 Mon Sep 17 00:00:00 2001 From: Jeff Rowberg Date: Mon, 17 Jan 2022 20:58:00 -0500 Subject: [PATCH 3/3] Clean up formatting of Windows development guide --- windows/README.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/windows/README.md b/windows/README.md index bdfc6fbc0..c2164a8db 100644 --- a/windows/README.md +++ b/windows/README.md @@ -5,30 +5,33 @@ Some of the development helpers rely on `bash` being available. You can use the version provided by the official `git` installer. -For the quickest way to get started developing in Windows, use WinPython, *not* -Anaconda/Miniconda. Some users report impossible dependency/build headaches when -initializing a development environment starting from a base Miniconda3 -installation that is otherwise working. WinPython is available here: +For the quickest way to get started developing in Windows, use WinPython rather +than Anaconda or Miniconda. Some users report impossible dependency/build +headaches when initializing a development environment starting from a base +Miniconda3 installation that is otherwise working. WinPython is available here: - https://winpython.github.io/ -Make sure that you select a **64-bit** WinPython release that is >= 3.6. The -smallest available package is fine (the "dot" version with only the bare minimum -required to run Python) since `tox` handles dependencies. However, you will need -to install `tox` using `pip` once before proceeding. +Make sure that you select a 64-bit Python release that is >= 3.6. The smallest +available package is fine (the "dot" version with only the bare minimum required +to run Python) since `tox` handles dependencies. However, you will need to +install `tox` using `pip` once before proceeding. -**NOTE**: If you are intending to develop specifically inside the `plover-stroke` -module, you will also need Microsoft Build Tools and an SDK appropriate for your +See the [developer guide](../doc/developer_guide.md) for the rest of the steps. + +## Special consideration for `plover-stroke` development + +If you are intending to develop specifically inside the `plover-stroke` module, +you will also need Microsoft Build Tools and an SDK appropriate for your operating system. This is because the `plover-stroke` module contains C code -rather than just native Python code. **Most people will not need to do this.** -The Microsoft Build Tools installer is available here: +rather than just native Python code. The Microsoft Build Tools installer is +available here: - https://visualstudio.microsoft.com/visual-cpp-build-tools/ -When you run the installer, make sure you select **both** the SDK for your +When you run the installer, make sure you select both the SDK for your Windows version and the build tools for it (e.g. Windows 10 SDK, MSVC v142). You will also need to run the appropriate `vcvars64.bat` file from the build tools installation inside of your Python environment to establish the correct -paths, which is found in a subfolder of `\Program Files (x86)\Microsoft Visual Studio\`. - -See the [developer guide](../doc/developer_guide.md) for the rest of the steps. +paths, which is found in a subfolder of +`\Program Files (x86)\Microsoft Visual Studio\`.