[PATCH] doc: enhance build instructions on windows

[PATCH] doc: enhance build instructions on windows

[Andre Muezerie]

* Updated about old Meson issue
* Added instruction to get developer prompt

Andre Muezerie (1):
  doc: enhanced build instructions on Windows

 .mailmap                              |  1 +
 doc/guides/windows_gsg/build_dpdk.rst | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

-- 
1.8.3.1

[PATCH] doc: enhanced build instructions on Windows

[Andre Muezerie]

Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
---
 .mailmap                              |  1 +
 doc/guides/windows_gsg/build_dpdk.rst | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/.mailmap b/.mailmap
index 5290420..60db768 100644
--- a/.mailmap
+++ b/.mailmap
@@ -98,6 +98,7 @@ Anatolii Gerasymenko <anatolii.gerasymenko@intel.com>
 Anatoly Burakov <anatoly.burakov@intel.com>
 Anbarasan Murugesan <anbarasanx.murugesan@intel.com>
 Anders Roxell <anders.roxell@linaro.org>
+Andre Muezerie <andremue@linux.microsoft.com> <andremue@microsoft.com>
 Andrea Arcangeli <aarcange@redhat.com>
 Andrea Grandi <andrea.grandi@intel.com>
 Andre Richter <andre.o.richter@gmail.com>
diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
index 708875c..c5fad81 100644
--- a/doc/guides/windows_gsg/build_dpdk.rst
+++ b/doc/guides/windows_gsg/build_dpdk.rst
@@ -72,10 +72,9 @@ A good option to choose is the MSI installer for both meson and ninja together::
 
 	http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer%22
 
-Required version is Meson 0.57.
-
-Versions starting from 0.58 are unusable with LLVM toolchain
-because of a `Meson issue <https://github.com/mesonbuild/meson/issues/8981>`_.
+Meson version 0.58 was unusable with LLVM toolchain
+because of an `issue <https://github.com/mesonbuild/meson/issues/8981>`_, but
+more recent versions are working fine.
 
 
 Install the Backend
@@ -129,13 +128,20 @@ Depending on the distribution, paths in this file may need adjustments.
 Option 3. Native Build on Windows using MSVC
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Open a 'Developer PowerShell for VS 2022' prompt from the start menu.
+Open a 'Visual Studio Developer Command Prompt'. When doing so, it's recommended
+to specify the Target Architecture (-arch) and the Host Architecture (-host_arch).
 The developer prompt will configure the environment
 to select the appropriate compiler, linker and SDK paths
 required to build with Visual Studio 2022.
 
 .. code-block:: console
 
+    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat" -host_arch=amd64 -arch=amd64
+
+Compile the code from the developer prompt.
+
+.. code-block:: console
+
    cd C:\Users\me\dpdk
    meson setup -Denable_stdatomic=true build
    meson compile -C build
-- 
1.8.3.1

Re: [PATCH] doc: enhanced build instructions on Windows

[Thomas Monjalon]

Hello and welcome,

25/10/2024 16:15, Andre Muezerie:
> Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
> ---
> --- a/doc/guides/windows_gsg/build_dpdk.rst
> +++ b/doc/guides/windows_gsg/build_dpdk.rst
> @@ -72,10 +72,9 @@ A good option to choose is the MSI installer for both meson and ninja together::
>  
>  	http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer%22
>  
> -Required version is Meson 0.57.
> -
> -Versions starting from 0.58 are unusable with LLVM toolchain
> -because of a `Meson issue <https://github.com/mesonbuild/meson/issues/8981>`_.
> +Meson version 0.58 was unusable with LLVM toolchain
> +because of an `issue <https://github.com/mesonbuild/meson/issues/8981>`_, but
> +more recent versions are working fine.

Please could we be more explicit about which version is working fine?

[PATCH v2 0/2] doc: enhance build instructions on windows

[Andre Muezerie]

* Updated about old Meson issue
* Added instruction to get developer prompt

---
v2:
 - provide Meson version that works

Andre Muezerie (2):
  doc: enhanced build instructions on Windows
  doc: provide Meson version that works

 .mailmap                              |  1 +
 doc/guides/windows_gsg/build_dpdk.rst | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

-- 
1.8.3.1

[PATCH v2 1/2] doc: enhanced build instructions on Windows

[Andre Muezerie]

Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
---
 .mailmap                              |  1 +
 doc/guides/windows_gsg/build_dpdk.rst | 16 +++++++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/.mailmap b/.mailmap
index 5290420..60db768 100644
--- a/.mailmap
+++ b/.mailmap
@@ -98,6 +98,7 @@ Anatolii Gerasymenko <anatolii.gerasymenko@intel.com>
 Anatoly Burakov <anatoly.burakov@intel.com>
 Anbarasan Murugesan <anbarasanx.murugesan@intel.com>
 Anders Roxell <anders.roxell@linaro.org>
+Andre Muezerie <andremue@linux.microsoft.com> <andremue@microsoft.com>
 Andrea Arcangeli <aarcange@redhat.com>
 Andrea Grandi <andrea.grandi@intel.com>
 Andre Richter <andre.o.richter@gmail.com>
diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
index 708875c..c5fad81 100644
--- a/doc/guides/windows_gsg/build_dpdk.rst
+++ b/doc/guides/windows_gsg/build_dpdk.rst
@@ -72,10 +72,9 @@ A good option to choose is the MSI installer for both meson and ninja together::
 
 	http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer%22
 
-Required version is Meson 0.57.
-
-Versions starting from 0.58 are unusable with LLVM toolchain
-because of a `Meson issue <https://github.com/mesonbuild/meson/issues/8981>`_.
+Meson version 0.58 was unusable with LLVM toolchain
+because of an `issue <https://github.com/mesonbuild/meson/issues/8981>`_, but
+more recent versions are working fine.
 
 
 Install the Backend
@@ -129,13 +128,20 @@ Depending on the distribution, paths in this file may need adjustments.
 Option 3. Native Build on Windows using MSVC
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Open a 'Developer PowerShell for VS 2022' prompt from the start menu.
+Open a 'Visual Studio Developer Command Prompt'. When doing so, it's recommended
+to specify the Target Architecture (-arch) and the Host Architecture (-host_arch).
 The developer prompt will configure the environment
 to select the appropriate compiler, linker and SDK paths
 required to build with Visual Studio 2022.
 
 .. code-block:: console
 
+    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat" -host_arch=amd64 -arch=amd64
+
+Compile the code from the developer prompt.
+
+.. code-block:: console
+
    cd C:\Users\me\dpdk
    meson setup -Denable_stdatomic=true build
    meson compile -C build
-- 
1.8.3.1

[PATCH v2 2/2] doc: provide Meson version that works

[Andre Muezerie]

Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
---
 doc/guides/windows_gsg/build_dpdk.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
index c5fad81..76bfc22 100644
--- a/doc/guides/windows_gsg/build_dpdk.rst
+++ b/doc/guides/windows_gsg/build_dpdk.rst
@@ -74,7 +74,7 @@ A good option to choose is the MSI installer for both meson and ninja together::
 
 Meson version 0.58 was unusable with LLVM toolchain
 because of an `issue <https://github.com/mesonbuild/meson/issues/8981>`_, but
-more recent versions are working fine.
+more recent versions are working fine. Meson version 1.5.2 was tested and worked.
 
 
 Install the Backend
-- 
1.8.3.1

Re: [PATCH v2 2/2] doc: provide Meson version that works

[Dmitry Kozlyuk]

2024-10-25 12:30 (UTC-0700), Andre Muezerie:
> Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
> ---
>  doc/guides/windows_gsg/build_dpdk.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
> index c5fad81..76bfc22 100644
> --- a/doc/guides/windows_gsg/build_dpdk.rst
> +++ b/doc/guides/windows_gsg/build_dpdk.rst
> @@ -74,7 +74,7 @@ A good option to choose is the MSI installer for both meson and ninja together::
>  
>  Meson version 0.58 was unusable with LLVM toolchain
>  because of an `issue <https://github.com/mesonbuild/meson/issues/8981>`_, but
> -more recent versions are working fine.
> +more recent versions are working fine. Meson version 1.5.2 was tested and worked.
>  
>  
>  Install the Backend

In order to address reviewer feedback on a single patch,
you are supposed to send an updated version of that patch,
not a series of the original patch (as v2 1/2)
and a patch with amendments (as v2 2/2, i.e. this patch).
IOW, you should have sent a single v2 patch with the proper text.

As for this documentation paragraph: please drop the mention of Meson 0.58
and simply state that Meson 1.5.2 or newer is recommended.
The warning was put in place because the bug lasted many Meson versions.

Re: [PATCH v2 1/2] doc: enhanced build instructions on Windows

[Dmitry Kozlyuk]

2024-10-25 12:30 (UTC-0700), Andre Muezerie:
> -Open a 'Developer PowerShell for VS 2022' prompt from the start menu.
> +Open a 'Visual Studio Developer Command Prompt'. When doing so, it's recommended
> +to specify the Target Architecture (-arch) and the Host Architecture (-host_arch).

It seems that Microsoft documentation [1] uses "target" and "host" terms
for what Meson documentation [2] calls "host" and "build" respectively.
This deserves a notice to avoid confusion.

[1]: https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022
[2]: https://mesonbuild.com/Cross-compilation.html

Why manually specifying architectures is recommended?
If it is mandatory, please use imperative so that no one skips this step.
However, Meson has cross-compilation features, don't they work
(cross-compilation from Windows has never been considered yet)?

>  The developer prompt will configure the environment
>  to select the appropriate compiler, linker and SDK paths
>  required to build with Visual Studio 2022.
>  
>  .. code-block:: console
>  
> +    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat" -host_arch=amd64 -arch=amd64
> +
> +Compile the code from the developer prompt.
> +
> +.. code-block:: console
> +
>     cd C:\Users\me\dpdk
>     meson setup -Denable_stdatomic=true build
>     meson compile -C build

[PATCH v3] doc: enhance build instructions on Windows

[Andre Muezerie]

Enhance build instructions on Windows

Signed-off-by: Andre Muezerie <andremue@linux.microsoft.com>
---
v3:
 - Recommended Meson version to use and removed mention about old bug.
 - Set VS developer prompt to produce 64 bit binaries if needed.
v2:
 - provide Meson version that works

 .mailmap                              |  1 +
 doc/guides/windows_gsg/build_dpdk.rst | 19 ++++++++++++++-----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/.mailmap b/.mailmap
index 5290420..60db768 100644
--- a/.mailmap
+++ b/.mailmap
@@ -98,6 +98,7 @@ Anatolii Gerasymenko <anatolii.gerasymenko@intel.com>
 Anatoly Burakov <anatoly.burakov@intel.com>
 Anbarasan Murugesan <anbarasanx.murugesan@intel.com>
 Anders Roxell <anders.roxell@linaro.org>
+Andre Muezerie <andremue@linux.microsoft.com> <andremue@microsoft.com>
 Andrea Arcangeli <aarcange@redhat.com>
 Andrea Grandi <andrea.grandi@intel.com>
 Andre Richter <andre.o.richter@gmail.com>
diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
index 708875c..c81a818 100644
--- a/doc/guides/windows_gsg/build_dpdk.rst
+++ b/doc/guides/windows_gsg/build_dpdk.rst
@@ -72,10 +72,7 @@ A good option to choose is the MSI installer for both meson and ninja together::
 
 	http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer%22
 
-Required version is Meson 0.57.
-
-Versions starting from 0.58 are unusable with LLVM toolchain
-because of a `Meson issue <https://github.com/mesonbuild/meson/issues/8981>`_.
+Meson version 1.5.2 or newer is recommended.
 
 
 Install the Backend
@@ -129,11 +126,23 @@ Depending on the distribution, paths in this file may need adjustments.
 Option 3. Native Build on Windows using MSVC
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Open a 'Developer PowerShell for VS 2022' prompt from the start menu.
+Open a 'Visual Studio Developer Command Prompt'.
 The developer prompt will configure the environment
 to select the appropriate compiler, linker and SDK paths
 required to build with Visual Studio 2022.
 
+Windows 32-bit is currently not supported, so if your Visual Studio environment defaults
+to 32-bits you can instruct the toolset to produce 64-bit binaries using "-arch" parameter.
+For more details about the Developer Prompt options look at the `Visual Studio Developer
+Command Prompt and Developer PowerShell
+<https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022>`_.
+
+.. code-block:: console
+
+    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat" -arch=amd64
+
+Compile the code from the developer prompt.
+
 .. code-block:: console
 
    cd C:\Users\me\dpdk
-- 
1.8.3.1

Re: [PATCH v3] doc: enhance build instructions on Windows

[Dmitry Kozlyuk]

2024-10-28 12:45 (UTC-0700), Andre Muezerie:
> Enhance build instructions on Windows

Commit messages should explain why the previous state had been problematic
and how the new state solves the issues. For example:

	doc: modernize build instructions on Windows

	Meson 0.57 was an unstable version and is now outdated.
	The referenced bug in Meson 0.58 is fixed in stable releases.
	Recommend the latest stable release which is tested.

	...likewise about command prompt changes...

[...]
> @@ -129,11 +126,23 @@ Depending on the distribution, paths in this file may need adjustments.
>  Option 3. Native Build on Windows using MSVC
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -Open a 'Developer PowerShell for VS 2022' prompt from the start menu.
> +Open a 'Visual Studio Developer Command Prompt'.
>  The developer prompt will configure the environment
>  to select the appropriate compiler, linker and SDK paths
>  required to build with Visual Studio 2022.
>  
> +Windows 32-bit is currently not supported, so if your Visual Studio environment defaults
> +to 32-bits you can instruct the toolset to produce 64-bit binaries using "-arch" parameter.
> +For more details about the Developer Prompt options look at the `Visual Studio Developer
> +Command Prompt and Developer PowerShell
> +<https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022>`_.
> +
> +.. code-block:: console
> +
> +    "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat" -arch=amd64
> +
> +Compile the code from the developer prompt.
> +
>  .. code-block:: console
>  
>     cd C:\Users\me\dpdk

It will be unclear to the reader to which machine "32-bit" refers.
Suggestion:

	Building DPDK applications that run on 32-bit Windows is currently not
	supported. If your Visual Studio environment defaults to producing
	32-bit binaries...

With the above corrections,
Acked-by: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>