[v4,7/8] doc: add documention for windows

Message ID 20190322225505.13988-8-anand.rawat@intel.com
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • HelloWorld example for windows
Related show

Checks

Context Check Description
ci/Intel-compilation success Compilation OK
ci/checkpatch success coding style OK

Commit Message

Anand Rawat March 22, 2019, 10:55 p.m.
Added documentation to build helloworld example
on windows using meson and clang. Updated the
maintainers list to include windows maintainers.

Signed-off-by: Pallavi Kadam <pallavi.kadam@intel.com>
Signed-off-by: Anand Rawat <anand.rawat@intel.com>
Reviewed-by: Jeff Shaw <jeffrey.b.shaw@intel.com>
Reviewed-by: Ranjit Menon <ranjit.menon@intel.com>
---
 MAINTAINERS                           |  7 +++
 doc/guides/index.rst                  |  3 +-
 doc/guides/windows_gsg/build_dpdk.rst | 73 +++++++++++++++++++++++++++
 doc/guides/windows_gsg/index.rst      | 14 +++++
 doc/guides/windows_gsg/intro.rst      | 20 ++++++++
 5 files changed, 116 insertions(+), 1 deletion(-)
 create mode 100644 doc/guides/windows_gsg/build_dpdk.rst
 create mode 100644 doc/guides/windows_gsg/index.rst
 create mode 100644 doc/guides/windows_gsg/intro.rst

Comments

Jerin Jacob Kollanukkaran March 23, 2019, 4:51 p.m. | #1
On Fri, 2019-03-22 at 15:55 -0700, Anand Rawat wrote:
> Added documentation to build helloworld example
> on windows using meson and clang. Updated the
> maintainers list to include windows maintainers.
> 
> Signed-off-by: Pallavi Kadam <pallavi.kadam@intel.com>
> Signed-off-by: Anand Rawat <anand.rawat@intel.com>
> Reviewed-by: Jeff Shaw <jeffrey.b.shaw@intel.com>
> Reviewed-by: Ranjit Menon <ranjit.menon@intel.com>
> ---
> 
> +Install the Linker
> +------------------
> +
> +Download and install the Build Tools for Visual Studio to link and
> build the files
> +on windwos, from `Microsoft* website <
> https://visualstudio.microsoft.com/downloads>`_.


# I think, Build tools does not have link.exe. Based on my testing, I
need to install Micro soft Visual studio community edition get the
link.exe.

For instance, in my case, link.exe is installed in following URL in
Visual Studio, not anywhere in build tools path.

C:\Program Files (x86)\Microsoft Visual
Studio\2017\Community\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64

If it is correct then doc needs to be updated.

# I could compile and run the dpdk-helloworld.exe, Are following
warnings expected?

[16/16] Linking target examples/dpdk-helloworld.exe.
clang.exe: warning: argument unused during compilation: '-pthread' [-
Wunused-command-line-argument]
LINK : warning LNK4044: unrecognized option '/O1'; ignored
LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored
LINK : warning LNK4044: unrecognized option '/-start-group'; ignored
LINK : warning LNK4044: unrecognized option '/-end-group'; ignored
LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored
Bruce Richardson March 25, 2019, 10:24 a.m. | #2
On Sat, Mar 23, 2019 at 04:51:27PM +0000, Jerin Jacob Kollanukkaran wrote:
> On Fri, 2019-03-22 at 15:55 -0700, Anand Rawat wrote:
> > Added documentation to build helloworld example
> > on windows using meson and clang. Updated the
> > maintainers list to include windows maintainers.
> > 
> > Signed-off-by: Pallavi Kadam <pallavi.kadam@intel.com>
> > Signed-off-by: Anand Rawat <anand.rawat@intel.com>
> > Reviewed-by: Jeff Shaw <jeffrey.b.shaw@intel.com>
> > Reviewed-by: Ranjit Menon <ranjit.menon@intel.com>
> > ---
> > 
> > +Install the Linker
> > +------------------
> > +
> > +Download and install the Build Tools for Visual Studio to link and
> > build the files
> > +on windwos, from `Microsoft* website <
> > https://visualstudio.microsoft.com/downloads>`_.
> 
> 
> # I think, Build tools does not have link.exe. Based on my testing, I
> need to install Micro soft Visual studio community edition get the
> link.exe.
> 
> For instance, in my case, link.exe is installed in following URL in
> Visual Studio, not anywhere in build tools path.
> 
> C:\Program Files (x86)\Microsoft Visual
> Studio\2017\Community\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64
> 
> If it is correct then doc needs to be updated.
> 
> # I could compile and run the dpdk-helloworld.exe, Are following
> warnings expected?
> 
> [16/16] Linking target examples/dpdk-helloworld.exe.
> clang.exe: warning: argument unused during compilation: '-pthread' [-
> Wunused-command-line-argument]
> LINK : warning LNK4044: unrecognized option '/O1'; ignored
> LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored
> LINK : warning LNK4044: unrecognized option '/-start-group'; ignored
> LINK : warning LNK4044: unrecognized option '/-end-group'; ignored
> LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored

Yes, they are, and, in my investigations anyway, I haven't found any way to
get rid of them. The meson support for windows is very much targetted at
users of msvc and clang-cl (which uses the msvc-style flags) rather than
regular clang, so the support is not as clean as I would like. Thankfully,
though, it does appear to be working thus far! :-)
Pallavi Kadam March 25, 2019, 5:43 p.m. | #3
On 3/25/2019 3:24 AM, Bruce Richardson wrote:
> On Sat, Mar 23, 2019 at 04:51:27PM +0000, Jerin Jacob Kollanukkaran wrote:
>> On Fri, 2019-03-22 at 15:55 -0700, Anand Rawat wrote:
>>> Added documentation to build helloworld example
>>> on windows using meson and clang. Updated the
>>> maintainers list to include windows maintainers.
>>>
>>> Signed-off-by: Pallavi Kadam <pallavi.kadam@intel.com>
>>> Signed-off-by: Anand Rawat <anand.rawat@intel.com>
>>> Reviewed-by: Jeff Shaw <jeffrey.b.shaw@intel.com>
>>> Reviewed-by: Ranjit Menon <ranjit.menon@intel.com>
>>> ---
>>>
>>> +Install the Linker
>>> +------------------
>>> +
>>> +Download and install the Build Tools for Visual Studio to link and
>>> build the files
>>> +on windwos, from `Microsoft* website <
>>> https://visualstudio.microsoft.com/downloads>`_.
>>
>> # I think, Build tools does not have link.exe. Based on my testing, I
>> need to install Micro soft Visual studio community edition get the
>> link.exe.
>>
>> For instance, in my case, link.exe is installed in following URL in
>> Visual Studio, not anywhere in build tools path.
>>
>> C:\Program Files (x86)\Microsoft Visual
>> Studio\2017\Community\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64
>>
>> If it is correct then doc needs to be updated.
>>
>> # I could compile and run the dpdk-helloworld.exe, Are following
>> warnings expected?
>>
>> [16/16] Linking target examples/dpdk-helloworld.exe.
>> clang.exe: warning: argument unused during compilation: '-pthread' [-
>> Wunused-command-line-argument]
>> LINK : warning LNK4044: unrecognized option '/O1'; ignored
>> LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored
>> LINK : warning LNK4044: unrecognized option '/-start-group'; ignored
>> LINK : warning LNK4044: unrecognized option '/-end-group'; ignored
>> LINK : warning LNK4044: unrecognized option '/-no-as-needed'; ignored
> Yes, they are, and, in my investigations anyway, I haven't found any way to
> get rid of them. The meson support for windows is very much targetted at
> users of msvc and clang-cl (which uses the msvc-style flags) rather than
> regular clang, so the support is not as clean as I would like. Thankfully,
> though, it does appear to be working thus far! :-)

Thanks, Bruce. Yes, few warnings are expected for now.

Regarding link.exe, will update the docs to install the build tools and 
select the 'Visual C++ build tools' option which also installs the 
linker and SDK required to build on windows.

Doing so, link.exe can be installed in the following URL and installing 
Visual Studio can be avoided.

C:\Program Files (x86)\Microsoft Visual 
Studio\2017\BuildTools\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64

Patch

diff --git a/MAINTAINERS b/MAINTAINERS
index 452b8eb82..0080c8f4c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -272,6 +272,13 @@  FreeBSD UIO
 M: Bruce Richardson <bruce.richardson@intel.com>
 F: kernel/freebsd/nic_uio/
 
+Windows support
+M: Harini Ramakrishnan <harini.ramakrishnan@microsoft.com>
+M: Omar Cardona <ocardona@microsoft.com>
+M: Anand Rawat <anand.rawat@intel.com>
+M: Ranjit Menon <ranjit.menon@intel.com>
+F: lib/librte_eal/windows/
+
 
 Core Libraries
 --------------
diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index 8a9ed65c8..8a1601b27 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -1,5 +1,5 @@ 
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2010-2014 Intel Corporation.
+    Copyright(c) 2010-2019 Intel Corporation.
 
 DPDK documentation
 ==================
@@ -9,6 +9,7 @@  DPDK documentation
 
    linux_gsg/index
    freebsd_gsg/index
+   windows_gsg/index
    sample_app_ug/index
    prog_guide/index
    howto/index
diff --git a/doc/guides/windows_gsg/build_dpdk.rst b/doc/guides/windows_gsg/build_dpdk.rst
new file mode 100644
index 000000000..06b148eca
--- /dev/null
+++ b/doc/guides/windows_gsg/build_dpdk.rst
@@ -0,0 +1,73 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Intel Corporation.
+
+Compiling the DPDK Target from Source
+=====================================
+
+System Requirements
+-------------------
+
+The DPDK and its applications require the Clang-LLVM* C compiler and MSVC* linker.
+The Meson* Build system is used to prepare the sources for compilation with the Ninja backend.
+
+\*Other names and brands may be claimed as the property of others.
+
+Install the Compiler
+--------------------
+
+Download and install the clang compiler from `LLVM* website <http://releases.llvm.org/download.html>`_.
+For example, Clang-LLVM direct download link::
+
+	http://releases.llvm.org/7.0.1/LLVM-7.0.1-win64.exe
+
+
+Install the Linker
+------------------
+
+Download and install the Build Tools for Visual Studio to link and build the files
+on windwos, from `Microsoft* website <https://visualstudio.microsoft.com/downloads>`_.
+
+
+Install the Build System
+------------------------
+
+Download and install the build system from `Meson* website <http://mesonbuild.com/Getting-meson.html>`_.
+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
+
+Install the Backend
+-------------------
+
+If using Ninja, download and install the backend from `Ninja* website <https://ninja-build.org/>`_ or
+install along with the meson build system.
+
+Build the code
+--------------
+
+The build environment is setup to build the EAL and the helloworld example by
+default.
+
+Using the ninja backend
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+    cd C:\Users\me\dpdk
+    meson build
+    cd build
+    ninja
+
+Run the helloworld example
+==========================
+
+Navigate to the build directory and run `dpdk-helloworld.exe`.
+
+.. code-block:: console
+
+    cd C:\Users\me\dpdk\build
+    helloworld.exe
+    hello from core 1
+    hello from core 3
+    hello from core 0
+    hello from core 2
diff --git a/doc/guides/windows_gsg/index.rst b/doc/guides/windows_gsg/index.rst
new file mode 100644
index 000000000..d9b7990a8
--- /dev/null
+++ b/doc/guides/windows_gsg/index.rst
@@ -0,0 +1,14 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Intel Corporation.
+
+.. _windows_gsg:
+
+Getting Started Guide for Windows
+=================================
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    intro
+    build_dpdk
diff --git a/doc/guides/windows_gsg/intro.rst b/doc/guides/windows_gsg/intro.rst
new file mode 100644
index 000000000..a0285732d
--- /dev/null
+++ b/doc/guides/windows_gsg/intro.rst
@@ -0,0 +1,20 @@ 
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Intel Corporation.
+
+Introduction
+============
+
+This document contains instructions for installing and configuring the Data
+Plane Development Kit (DPDK) software. The document describes how to compile
+and run a DPDK application in a Windows* OS application environment, without
+going deeply into detail.
+
+\*Other names and brands may be claimed as the property of others.
+
+Limitations
+===========
+
+DPDK for Windows is currently a work in progress. Not all DPDK source files
+compile. Support is being added in pieces so as to limit the overall scope
+of any individual patch series. The goal is to be able to run any DPDK
+application natively on Windows.