Expand Windows installation documentation (#1584)

Rewrite it a bit and document the linker configuration step.

book/src/installation_windows.md

@@ -6,7 +6,7 @@ You will want to go for the GNU toolchain if you depend on libraries that can on
 
 ## Install Rustup
 
-Install the rust toolchain via [rustup](https://rustup.rs/).
+Install the Rust toolchain via [rustup](https://rustup.rs/).
 
 ## Install GTK 4
 
@@ -16,26 +16,40 @@ Install the rust toolchain via [rustup](https://rustup.rs/).
 
 ### Set Rust toolchain to MSVC
 
-Set the Rust toolchain to MSVC by executing:
+Tell Rust to use MSVC by executing:
 
 ```
 rustup default stable-msvc
 ```
 
-### Build GTK 4 
+Note that this does not install the MSVC toolchain. If you don't have it yet, you will need to [install it separately](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup).
+
+### Build GTK 4
+
+Follow the [`gvsbuild` docs to build GTK 4](https://github.com/wingtk/gvsbuild#development-environment). Be sure to build the right version:
 
-Follow the [`gvsbuild` docs to build GTK 4](https://github.com/wingtk/gvsbuild#development-environment).
-When choosing the GTK version to build, select `gtk4` instead of `gtk3`: 
 ```
 gvsbuild build gtk4
 ```
-<!--  -->
-### Update `Path` environment variable
 
-2. Add `New User Variable` and update `Path` in environment variable to include `PKG_CONFIG_PATH` and the GTK 4 libraries:
-   1. Go to settings -> Search and open `Advanced system settings` -> Click on `Environment variables`
-   2. Select `New` -> Input `Variable name` : `PKG_CONFIG_PATH` & `Variable value` : `C:\gtk-build\gtk\x64\release\lib\pkgconfig`
-   3. Select `Path` -> Click on `Edit` -> Add `C:\gtk-build\gtk\x64\release\bin`
+### Update environment variables
+
+1. Go to Start
+2. Search for 'Advanced system settings'
+3. Click 'Environment Variables...'
+4. Ensure there is a user variable named `PKG_CONFIG_PATH` with value `C:\gtk-build\gtk\x64\release\lib\pkgconfig`
+5. Edit the variable named `Path` and add `C:\gtk-build\gtk\x64\release\lib\pkgconfig` to it
+
+### Ensure your linker can find GTK's library files
+
+Open `%HOMEPATH%\.cargo\config` for editing. You can add extra flags for your linker here to tell it where GTK's library files are. If you're using the `stable-x86_64-pc-windows-msvc` Rust toolchain, your config may look like this:
+
+```toml
+[target.x86_64-pc-windows-msvc]
+rustflags = ["-C", "link-args=/LIBPATH:C:\\gtk-build\\gtk\\x64\\release\\lib\\"]
+```
+
+This `rustflags` value should work for Microsoft's linker as well as LLVM's `lld-link.exe`.
 
 You can now continue with the [project setup](./project_setup.html).
 
@@ -67,17 +81,15 @@ Make sure to check the box "Desktop development with C++" during the installatio
 
 Download git from [gitforwindows.org](https://gitforwindows.org/).
 
-
 ### CMake
-Download CMake from [https://cmake.org/download/](https://cmake.org/download/)
 
+Download CMake from [https://cmake.org/download/](https://cmake.org/download/)
 
 ### Python
 
 Download python from [python.org](https://www.python.org/downloads).
 Make sure to opt-in to adding Python to your Path during the installation process.
 
-
 ### Meson
 
 Install meson by executing:
@@ -91,14 +103,11 @@ pip install meson ninja
 Download Gettext 0.21 from [mlocati.github.io](https://mlocati.github.io/articles/gettext-iconv-windows.html).
 Make sure to select the static version.
 
-
 ### Pkg-config
 
 Download pkg-config-lite from [sourceforge.net](https://sourceforge.net/projects/pkgconfiglite/).
 Then extract and unpack it in `C:/`, so that the executable is in `C:\pkg-config-lite-0.28-1\bin`.
 
-
-
 ### Update environment variables
 
 1. Go to settings -> Search and open `Advanced system settings` -> Click on `Environment variables`
@@ -115,7 +124,6 @@ C:\gnome\bin
 - Variable name: `PKG_CONFIG_PATH`
 - Variable value: `C:\gnome\lib\pkgconfig`
 
-
 ### Compile and install GTK 4
 
 From the Windows start menu, search for `x64 Native Tools Command Prompt for VS 2019`.
@@ -131,7 +139,7 @@ git clone https://gitlab.gnome.org/GNOME/librsvg.git --depth 1
 :: Make sure that cmd finds pkg-config-lite when searching for pkg-config
 where pkg-config
 
-:: Make sure that setuptools is available. 
+:: Make sure that setuptools is available.
 pip install setuptools
 
 cd gtk
@@ -169,7 +177,7 @@ If you used the MSVC toolchain before, make sure to revert all changes you made
 
 ### MSYS2
 
-Install MSYS2 from [www.msys2.org](https://www.msys2.org/) 
+Install MSYS2 from [www.msys2.org](https://www.msys2.org/)
 
 ### Install GTK 4
 
@@ -182,12 +190,11 @@ There, execute the following commands to install `GTK 4`, `pkgconf` and `gcc`.
 pacman -S mingw-w64-x86_64-gtk4 mingw-w64-x86_64-gettext mingw-w64-x86_64-libxml2 mingw-w64-x86_64-librsvg mingw-w64-x86_64-pkgconf mingw-w64-x86_64-gcc
 ```
 
-
 ### Update `Path` environment variable
 
 1. Go to settings -> Search and open `Advanced system settings` -> Click on `Environment variables`
 2. Select `Path` -> Click on `Edit` -> Add the following three entries:
- 
+
 ```
 C:\msys64\mingw64\include
 C:\msys64\mingw64\bin
@@ -206,4 +213,5 @@ Please note that this command might change in the future.
 If it does not work anymore, please open an [issue](https://github.com/gtk-rs/gtk4-rs/issues/new/choose) on our repo.
 
 You can now continue with the [project setup](./project_setup.html).
+
 </details>