[PATCH] docs: Add caveats for Windows as the build platform

Bin Meng posted 1 patch 1 year, 8 months ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20220719131521.764317-1-bin.meng@windriver.com
There is a newer version of this series
docs/about/build-platforms.rst | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
[PATCH] docs: Add caveats for Windows as the build platform
Posted by Bin Meng 1 year, 8 months ago
Commit cf60ccc3306c ("cutils: Introduce bundle mechanism") introduced
a Python script to populate a bundle directory using os.symlink() to
point to the binaries in the pc-bios directory of the source tree.
Commit 882084a04ae9 ("datadir: Use bundle mechanism") removed previous
logic in pc-bios/meson.build to create a link/copy of pc-bios binaries
in the build tree so os.symlink() is the way to go.

However os.symlink() may fail [1] on Windows if an unprivileged Windows
user started the QEMU build process, which results in QEMU executables
generated in the build tree not able to load the default BIOS/firmware
images due to symbolic links not present in the bundle directory.

This commits updates the documentation by adding such caveats for users
who want to build QEMU on the Windows platform.

[1] https://docs.python.org/3/library/os.html#os.symlink

Signed-off-by: Bin Meng <bin.meng@windriver.com>
---

 docs/about/build-platforms.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst
index ebde20f981..1b297e87ee 100644
--- a/docs/about/build-platforms.rst
+++ b/docs/about/build-platforms.rst
@@ -94,8 +94,16 @@ not tested anymore, so it is recommended to use one of the latest versions of
 Windows instead.
 
 The project supports building QEMU with current versions of the MinGW
-toolchain, either hosted on Linux (Debian/Fedora) or via MSYS2 on Windows.
+toolchain, either hosted on Linux (Debian/Fedora) or via `MSYS2`_ on Windows.
+A more recent Windows version is always prefered as it is less likely to have
+problems with building via MSYS2. The building process of QEMU involves some
+Python scripts that call os.symlink() which needs special attention for the
+build process to successfully complete. On newer versions of Windows 10,
+unprivileged accounts can create symlinks if Developer Mode is enabled.
+When Developer Mode is not available/enabled, the SeCreateSymbolicLinkPrivilege
+privilege is required, or the process must be run as an administrator.
 
 .. _Homebrew: https://brew.sh/
 .. _MacPorts: https://www.macports.org/
+.. _MSYS2: https://www.msys2.org/
 .. _Repology: https://repology.org/
-- 
2.34.1
Re: [PATCH] docs: Add caveats for Windows as the build platform
Posted by Stefan Weil via 1 year, 8 months ago
Am 19.07.22 um 15:15 schrieb Bin Meng:

> Commit cf60ccc3306c ("cutils: Introduce bundle mechanism") introduced
> a Python script to populate a bundle directory using os.symlink() to
> point to the binaries in the pc-bios directory of the source tree.
> Commit 882084a04ae9 ("datadir: Use bundle mechanism") removed previous
> logic in pc-bios/meson.build to create a link/copy of pc-bios binaries
> in the build tree so os.symlink() is the way to go.
>
> However os.symlink() may fail [1] on Windows if an unprivileged Windows
> user started the QEMU build process, which results in QEMU executables
> generated in the build tree not able to load the default BIOS/firmware
> images due to symbolic links not present in the bundle directory.
>
> This commits updates the documentation by adding such caveats for users
> who want to build QEMU on the Windows platform.
>
> [1] https://docs.python.org/3/library/os.html#os.symlink
>
> Signed-off-by: Bin Meng <bin.meng@windriver.com>
> ---
>
>   docs/about/build-platforms.rst | 10 +++++++++-
>   1 file changed, 9 insertions(+), 1 deletion(-)
>
> diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst
> index ebde20f981..1b297e87ee 100644
> --- a/docs/about/build-platforms.rst
> +++ b/docs/about/build-platforms.rst
> @@ -94,8 +94,16 @@ not tested anymore, so it is recommended to use one of the latest versions of
>   Windows instead.
>   
>   The project supports building QEMU with current versions of the MinGW
> -toolchain, either hosted on Linux (Debian/Fedora) or via MSYS2 on Windows.
> +toolchain, either hosted on Linux (Debian/Fedora) or via `MSYS2`_ on Windows.
> +A more recent Windows version is always prefered as it is less likely to have


s/prefered/preferred/


> +problems with building via MSYS2. The building process of QEMU involves some
> +Python scripts that call os.symlink() which needs special attention for the
> +build process to successfully complete. On newer versions of Windows 10,
> +unprivileged accounts can create symlinks if Developer Mode is enabled.
> +When Developer Mode is not available/enabled, the SeCreateSymbolicLinkPrivilege
> +privilege is required, or the process must be run as an administrator.
>   
>   .. _Homebrew: https://brew.sh/
>   .. _MacPorts: https://www.macports.org/
> +.. _MSYS2: https://www.msys2.org/
>   .. _Repology: https://repology.org/


With the fix above:

Reviewed-by: Stefan Weil <sw@weilnetz.de

Thanks!