[PATCH] meson: update doc logic for Windows

[PATCH] meson: update doc logic for Windows

[Vipin Varghese]

Support for shell scripts doxy-html-custom, generate_doxygen and
generate_examples are absent. The current patch address the same by
disabling document build notifying the user.

Steps to reproduce the error:
 - Install dependencies doxygen & sphinix build on Windwos server 2019.
 - Build DPDK with option enable_docs=true for API or User Guide.

This produces error
```
FAILED: doc/api/examples.dox
sh -e dpdk/doc/api/generate_examples.sh dpdk/examples doc/api/examples.dox
```

Signed-off-by: Vipin Varghese <vipin.varghese@amd.com>
---
 doc/meson.build | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/meson.build b/doc/meson.build
index 6f74706aa2..d7c35a12f2 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -3,6 +3,14 @@
 
 doc_targets = []
 doc_target_names = []
+
+if is_windows
+    if get_option('enable_docs')
+        message('Docs target not supported on windows')
+    endif
+    subdir_done()
+endif
+
 subdir('api')
 subdir('guides')
 
-- 
2.25.1

Re: [PATCH] meson: update doc logic for Windows

[Thomas Monjalon]

Hello,

Thank you for looking at this problem.

26/03/2022 03:59, Vipin Varghese:
> Support for shell scripts doxy-html-custom, generate_doxygen and
> generate_examples are absent. The current patch address the same by
> disabling document build notifying the user.

It should not prevent generating guides with sphinx.

> Steps to reproduce the error:
>  - Install dependencies doxygen & sphinix build on Windwos server 2019.
>  - Build DPDK with option enable_docs=true for API or User Guide.
> 
> This produces error
> ```
> FAILED: doc/api/examples.dox
> sh -e dpdk/doc/api/generate_examples.sh dpdk/examples doc/api/examples.dox
> ```

I suppose we could replace shell scripts with Python equivalent.

RE: [PATCH] meson: update doc logic for Windows

[Varghese, Vipin]

[AMD Official Use Only]

Hi Thomas,

<snipp>

Thank you for looking at this problem.

26/03/2022 03:59, Vipin Varghese:
> Support for shell scripts doxy-html-custom, generate_doxygen and 
> generate_examples are absent. The current patch address the same by 
> disabling document build notifying the user.

It should not prevent generating guides with sphinx.

We did get error from `doc/meson` stating ` echo command not available on windows` for both cmd and powershell for the line
```
run_target('doc', command: [echo, message, doc_target_names],
    depends: doc_targets)
```

> Steps to reproduce the error:
>  - Install dependencies doxygen & sphinix build on Windwos server 2019.
>  - Build DPDK with option enable_docs=true for API or User Guide.
>
> This produces error
> ```
> FAILED: doc/api/examples.dox
> sh -e dpdk/doc/api/generate_examples.sh dpdk/examples 
> doc/api/examples.dox ```

I suppose we could replace shell scripts with Python equivalent.

I am trying to minimize the changes as first step: fix the build error by disabling on windows`.
Next step we can convert to python to make it cross platform independent.

Re: [PATCH] meson: update doc logic for Windows

[Dmitry Kozlyuk]

2022-03-28 03:02 (UTC+0000), Varghese, Vipin:
> [AMD Official Use Only]
> 
> Hi Thomas,
> 
> <snipp>
> 
> Thank you for looking at this problem.
> 
> 26/03/2022 03:59, Vipin Varghese:
> > Support for shell scripts doxy-html-custom, generate_doxygen and 
> > generate_examples are absent. The current patch address the same by 
> > disabling document build notifying the user.  
> 
> It should not prevent generating guides with sphinx.
> 
> We did get error from `doc/meson` stating ` echo command not available on windows` for both cmd and powershell for the line
> ```
> run_target('doc', command: [echo, message, doc_target_names],
>     depends: doc_targets)
> ```

This line never searches for "echo" command,
e8c90926bdde ("doc: fix build on Windows with Meson 0.58")
introduced "echo" variable precisely to avoid this.
Can you give the full log?

> > Steps to reproduce the error:
> >  - Install dependencies doxygen & sphinix build on Windwos server 2019.
> >  - Build DPDK with option enable_docs=true for API or User Guide.
> >
> > This produces error
> > ```
> > FAILED: doc/api/examples.dox
> > sh -e dpdk/doc/api/generate_examples.sh dpdk/examples 
> > doc/api/examples.dox ```  
> 
> I suppose we could replace shell scripts with Python equivalent.
> 
> I am trying to minimize the changes as first step: fix the build error by disabling on windows`.
> Next step we can convert to python to make it cross platform independent.

If something is explicitly requested but not supported,
there should be a failure.
By the way, -Denable_docs=true works when cross-compiling for Windows,
so disabling docs for this target is not right.
I think we should sort out what's causing an issue with "echo" for you
(it shouldn't happen), then fix the scripts to fully enable docs.

RE: [PATCH] meson: update doc logic for Windows

[Varghese, Vipin]

[AMD Official Use Only]

Hi Dmitry,

Thanks for inputs, please find my question below

<snip>

2022-03-28 03:02 (UTC+0000), Varghese, Vipin:
> [AMD Official Use Only]
>
> Hi Thomas,
>
> <snipp>
>
> Thank you for looking at this problem.
>
> 26/03/2022 03:59, Vipin Varghese:
> > Support for shell scripts doxy-html-custom, generate_doxygen and 
> > generate_examples are absent. The current patch address the same by 
> > disabling document build notifying the user.
>
> It should not prevent generating guides with sphinx.
>
> We did get error from `doc/meson` stating ` echo command not available 
> on windows` for both cmd and powershell for the line ``` 
> run_target('doc', command: [echo, message, doc_target_names],
>     depends: doc_targets)
> ```

This line never searches for "echo" command, e8c90926bdde ("doc: fix build on Windows with Meson 0.58") introduced "echo" variable precisely to avoid this.
Can you give the full log?

> > Steps to reproduce the error:
> >  - Install dependencies doxygen & sphinix build on Windwos server 2019.
> >  - Build DPDK with option enable_docs=true for API or User Guide.
> >
> > This produces error
> > ```
> > FAILED: doc/api/examples.dox
> > sh -e dpdk/doc/api/generate_examples.sh dpdk/examples 
> > doc/api/examples.dox ```
>
> I suppose we could replace shell scripts with Python equivalent.
>
> I am trying to minimize the changes as first step: fix the build error by disabling on windows`.
> Next step we can convert to python to make it cross platform independent.

If something is explicitly requested but not supported, there should be a failure.
By the way, -Denable_docs=true works when cross-compiling for Windows, so disabling docs for this target is not right.
I think we should sort out what's causing an issue with "echo" for you (it shouldn't happen), then fix the scripts to fully enable docs.

Are you recommending 

Windows libraries and binaries should be cross build from linux (where all dependencies and shell script works)?

Or 

let us enhance the check for windows native build, if yes for option `-Denable_docs=true, we can stop the build for docs`.

If the latter is suggestion I will share v2 patch to check the same.

RE: [PATCH] meson: update doc logic for Windows

[Varghese, Vipin]

[AMD Official Use Only]

<snipp>
>
> 26/03/2022 03:59, Vipin Varghese:
> > Support for shell scripts doxy-html-custom, generate_doxygen and 
> > generate_examples are absent. The current patch address the same by 
> > disabling document build notifying the user.
>
> It should not prevent generating guides with sphinx.
>
> We did get error from `doc/meson` stating ` echo command not available 
> on windows` for both cmd and powershell for the line ``` 
> run_target('doc', command: [echo, message, doc_target_names],
>     depends: doc_targets)
> ```

This line never searches for "echo" command, e8c90926bdde ("doc: fix build on Windows with Meson 0.58") introduced "echo" variable precisely to avoid this.
Can you give the full log?

Hi Dmitry, as requested please find the logs attached below for windows native build for DPDK

Modified `doc/meson.build` to highlight the docs build echo log as

```
if doc_targets.length() == 0
    message = 'No docs targets found'
else
    message = 'Building docs:'
endif

message('=========================================\n\n\n\n\n\n')

run_target('doc', command: [echo, message, doc_target_names],
    depends: doc_targets)

message('=========================================\n\n\n\n\n\n')
```

Meson Logs:
```
The Meson build system
Version: 0.61.3
<snipp>

Program doxygen found: YES (C:\Program Files\doxygen\bin\doxygen.EXE)
Program generate_doxygen.sh found: YES (sh -e C:\Users\Administrator\Desktop\dpdk\doc\api\generate_doxygen.sh)
Program generate_examples.sh found: YES (sh -e C:\Users\Administrator\Desktop\dpdk\doc\api\generate_examples.sh)
Program doxy-html-custom.sh found: YES (sh -e C:\Users\Administrator\Desktop\dpdk\doc\api\doxy-html-custom.sh)
Configuring doxy-api.conf using configuration
Program sphinx-build found: YES (C:\Users\Administrator\AppData\Local\Programs\Python\Python310\Scripts\sphinx-build.EXE)

```

Actual log from `meson build` (there is no echo message stating No docs targets found or Building docs:)
```
Message: =========================================






Message: =========================================
```

Ninja build error log
```
Found ninja-1.10.2 at "C:\Program Files\Meson\ninja.EXE"
Cleaning... 0 files.
[1/2] Generating doc/api/examples.dox with a custom command
FAILED: doc/api/examples.dox
"sh" "-e" "C:/Users/Administrator/Desktop/dpdk/doc/api/generate_examples.sh" "C:/Users/Administrator/Desktop/dpdk/examples" "doc/api/examples.dox"
CreateProcess failed: The system cannot find the file specified.
ninja: build stopped: subcommand failed.

C:\Users\Administrator\Desktop\dpdk>
```


<snipp>

> I suppose we could replace shell scripts with Python equivalent.
>
> I am trying to minimize the changes as first step: fix the build error by disabling on windows`.
> Next step we can convert to python to make it cross platform independent.

If something is explicitly requested but not supported, there should be a failure.
By the way, -Denable_docs=true works when cross-compiling for Windows, so disabling docs for this target is not right.
I think we should sort out what's causing an issue with "echo" for you (it shouldn't happen), then fix the scripts to fully enable docs.

Are you recommending

Windows libraries and binaries should be cross build from linux (where all dependencies and shell script works)?

Or

let us enhance the check for windows native build, if yes for option `-Denable_docs=true, we can stop the build for docs`.

If the latter is suggestion, I will share v2 patch to check the same.

Re: [PATCH] meson: update doc logic for Windows

[Dmitry Kozlyuk]

2022-03-28 12:29 (UTC+0000), Varghese, Vipin:
[...]
> > We did get error from `doc/meson` stating ` echo command not available 
> > on windows` for both cmd and powershell for the line ``` 
> > run_target('doc', command: [echo, message, doc_target_names],
> >     depends: doc_targets)
> > ```  
> 
> This line never searches for "echo" command, e8c90926bdde ("doc: fix build on Windows with Meson 0.58") introduced "echo" variable precisely to avoid this.
> Can you give the full log?
> 
> > > Steps to reproduce the error:
> > >  - Install dependencies doxygen & sphinix build on Windwos server 2019.
> > >  - Build DPDK with option enable_docs=true for API or User Guide.
> > >
> > > This produces error
> > > ```
> > > FAILED: doc/api/examples.dox
> > > sh -e dpdk/doc/api/generate_examples.sh dpdk/examples 
> > > doc/api/examples.dox ```

Thanks for confirming that the "echo" issue did not reappear.

[...]
> Are you recommending 
> 
> Windows libraries and binaries should be cross build from linux (where all dependencies and shell script works)?
> 
> Or 
> 
> let us enhance the check for windows native build, if yes for option `-Denable_docs=true, we can stop the build for docs`.
> 
> If the latter is suggestion I will share v2 patch to check the same.

I recommend enhancing the Windows native build
by enabling full-fledged docs generation :)
I'm reluctant to accept this patch, even corrected,
because it effectively works against better Windows support:
- it makes less meson code reachable on Windows,
  allowing it to accumulate incompatible changes;
- it treats Windows as special,
  while we want it to be a platform supported on par with the others.
That being said, the latter option is acceptable for sure,
because it fixes a build failure in certain configuration.

RE: [PATCH] meson: update doc logic for Windows

[Varghese, Vipin]

[AMD Official Use Only]



> -----Original Message-----
> From: Dmitry Kozlyuk <dmitry.kozliuk@gmail.com>
> Sent: Tuesday, March 29, 2022 4:21 AM
> To: Varghese, Vipin <Vipin.Varghese@amd.com>
> Cc: Thomas Monjalon <thomas@monjalon.net>;
> david.marchand@redhat.com; Tummala, Sivaprasad
> <Sivaprasad.Tummala@amd.com>; dev@dpdk.org
> Subject: Re: [PATCH] meson: update doc logic for Windows
> 
> [CAUTION: External Email]
> 
> 2022-03-28 12:29 (UTC+0000), Varghese, Vipin:
> [...]
> > > We did get error from `doc/meson` stating ` echo command not
> > > available on windows` for both cmd and powershell for the line ```
> > > run_target('doc', command: [echo, message, doc_target_names],
> > >     depends: doc_targets)
> > > ```
> >
> > This line never searches for "echo" command, e8c90926bdde ("doc: fix
> build on Windows with Meson 0.58") introduced "echo" variable precisely to
> avoid this.
> > Can you give the full log?
> >
> > > > Steps to reproduce the error:
> > > >  - Install dependencies doxygen & sphinix build on Windwos server
> 2019.
> > > >  - Build DPDK with option enable_docs=true for API or User Guide.
> > > >
> > > > This produces error
> > > > ```
> > > > FAILED: doc/api/examples.dox
> > > > sh -e dpdk/doc/api/generate_examples.sh dpdk/examples
> > > > doc/api/examples.dox ```
> 
> Thanks for confirming that the "echo" issue did not reappear.
> 
> [...]
> > Are you recommending
> >
> > Windows libraries and binaries should be cross build from linux (where all
> dependencies and shell script works)?
> >
> > Or
> >
> > let us enhance the check for windows native build, if yes for option `-
> Denable_docs=true, we can stop the build for docs`.
> >
> > If the latter is suggestion I will share v2 patch to check the same.
> 
> I recommend enhancing the Windows native build by enabling full-fledged
> docs generation :) I'm reluctant to accept this patch, even corrected, because
> it effectively works against better Windows support:
> - it makes less meson code reachable on Windows,
>   allowing it to accumulate incompatible changes;
> - it treats Windows as special,
>   while we want it to be a platform supported on par with the others.
> That being said, the latter option is acceptable for sure, because it fixes a
> build failure in certain configuration.

As stated in patch with Windows native build using meson `-Denable_docs=true` result in build error

```
FAILED: doc/api/examples.dox
sh -e dpdk/doc/api/generate_examples.sh dpdk/examples doc/api/examples.dox ```
```

The reason is because shell script is not supported on Windows CMD. The scope of the patch is addressing the issue `by continuing the build processing with a warning to user`.

IMO the current patch can be deprecated or removed from mainline one `once full fledge docs generation is supported by native Windows build` as suggested by Dmitry.