Clarify Windows configonly.bat workflow and fix user-specific path

The previous workflow encouraged the user to create a batch file pointing to a nonexistant file before cloning the source code repository. Rearrange the calls so that the user can succesfully clone the QGIS repository, then create a batch file that calls a file in that source tree, then open the command prompt created by that batch file, then call a series of commands that configures using CMake, builds using Visual Studio, and runs QGIS.
qgis · May 11, 2020 · cd3b369 · cd3b369
1 parent b0e87db
commit cd3b369
Showing 1 changed file with 43 additions and 24 deletions.
diff --git a/doc/msvc.t2t b/doc/msvc.t2t
@@ -31,7 +31,7 @@ Download and install following packages:
 For the QGIS build you need to install following packages from cygwin:
 - bison
 - flex
-- git
+- git (even if you already have Git for Windows installed)
 -
 
 and from OSGeo4W (select //Advanced Install//):
@@ -51,62 +51,81 @@ dependencies.  If you're interested in that, check the history of this page in t
 or the SVN repository.
 
 ninja:
-  copy ninja.exe to d:\OSGeo4W64\bin\
+  copy ninja.exe to C:\OSGeo4W64\bin\
 
-=== Setting up the Visual Studio project with CMake ===
-
-/!\ Consider this section as example.  It tends to outdate, when OSGeo4W and
-SDKs move on.  ``ms-windows/osgeo4w/package-nightly.cmd`` is used for the
-nightly builds and constantly updated and hence might contain necessary
-updates that are not yet reflected here.
+=== Clone the QGIS Source Code ===
 
-To start a command prompt with an environment that both has the VC++ and the OSGeo4W
-variables create the following batch file (assuming the above packages were
-installed in the default locations):
+Chose a directory to store the QGIS source code.
+For example, to put it in the OSGeo4W64 install, navigate there:
 
 ```
-@echo off
-call X:\src\qgis\ms-windows\osgeo4w\msvc-env.bat x86_64
-@cmd
+cd C:\OSGeo4W64
 ```
 
-Save the batch file as ``d:\OSGeo4W64\OSGeo4W-dev.bat`` and run it.
-On the command prompt checkout the QGIS source from
+This directory will be assumed for all instructions
+that follow.
+
+On the command prompt clone the QGIS source from
 git to the source directory ``QGIS``:
 
 ```
 git clone git://github.com/qgis/QGIS.git
 ```
 
+This requires Git. If you have Git for Windows on your PATH already,
+you can do this from a normal command prompt. If you do not, you can
+use the Git package that was installed as part of Cygwin by opening
+a Cygwin[64] Terminal
+
 And, to avoid Git in Windows reporting changes to files not actually modified:
 
 ```
 git config core.filemode false
 ```
 
+=== Setting up the Visual Studio project with CMake ===
+
+/!\ Consider this section as example.  It tends to outdate, when OSGeo4W and
+SDKs move on.  ``ms-windows/osgeo4w/package-nightly.cmd`` is used for the
+nightly builds and constantly updated and hence might contain necessary
+updates that are not yet reflected here.
+
+To start a command prompt with an environment that both has the VC++ and the OSGeo4W
+variables create the following batch file (assuming the above packages were
+installed in the default locations):
+
+```
+@echo off
+call C:\OSGeo4W64\QGIS\ms-windows\osgeo4w\msvc-env.bat x86_64
+@cmd
+```
+
+Save the batch file as ``C:\OSGeo4W64\OSGeo4W-dev.bat`` and run it.
+
 
 Using configonly.bat to create the MSVC solution file:
-  We will be using the file ms-windows/osgeo4w/configonly.bat to create an MSVC solution file.
+  We will be using the file ``ms-windows/osgeo4w/configonly.bat`` to create an MSVC solution file.
   There are a few options for a solution file, following are the options: ninja, native MSVC.
-  The advantage of using native MSVC solution is that you can find the root of build problems much easily.
+  The advantage of using native MSVC solution is that you can find the root of build problems much more easily.
   configonly.bat is meant to create a configured build directory with a MSVC solution file:
 
-  ```
-  configonly.bat
-  ```
+```
+cd C:\OSGeo4W64\QGIS\ms-windows\osgeo4w
+configonly.bat
+```
 
 Compiling QGIS with MSVC:
   We will need to run MSVC with all the environment variables set, thus we will run it as follows:
-  Run the batch file OSGeo4W-dev.bat you created before. On the command prompt run: ``devenv``
+  Run the batch file OSGeo4W-dev.bat you created before. On the command prompt run: ``devenv`` to open MSVC.
   From MSVC, open the solution file
-  ``d:\OSGeo4W64\QGIS\ms-windows\osgeo4w\build-qgis-test-x86_64\qgis.sln``
+  ``C:\OSGeo4W64\QGIS\ms-windows\osgeo4w\build-qgis-test-x86_64\qgis.sln``
   Try to build the solution (go grab a cup of tea, it may take a while).
   If it fails, run it again and again until there are (hopefully) no errors.
 
 
 Running QGIS from within MSVC:
   Edit the properties of the project ALL_BUILD:
-  Debugging -> Command -> D:\OSGeo4W64\QGIS\ms-windows\osgeo4w\build-qgis-test-x86_64\output\bin\RelWithDebInfo\qgis.exe
+  Debugging -> Command -> ``C:\OSGeo4W64\QGIS\ms-windows\osgeo4w\build-qgis-test-x86_64\output\bin\RelWithDebInfo\qgis.exe``
   Run.
   Ignore the "These projects are out of date" message, it appears even if no files were changed.